1: README for libm-test math test suite
    2: ====================================
    3: 
    4: The libm-test math test suite tests a number of function points of
    5: math functions in the GNU C library.  The following sections contain a
    6: brief overview.  Please note that the test drivers and the Perl script
    7: "gen-libm-test.pl" have some options.  A full list of options is
    8: available with --help (for the test drivers) and -h for
    9: "gen-libm-test.pl".
   10: 
   11: 
   12: What is tested?
   13: ===============
   14: The tests just evaluate the functions at specified points and compare
   15: the results with precomputed values and the requirements of the ISO
   16: C99 standard.
   17: 
   18: Besides testing the special values mandated by IEEE 754 (infinities,
   19: NaNs and minus zero), some more or less random values are tested.
   20: 
   21: Files that are part of libm-test
   22: ================================
   23: 
   24: The main file is "libm-test.inc".  It is platform and floating point
   25: format independent.  The file must be preprocessed by the Perl script
   26: "gen-libm-test.pl".  The results are "libm-test.c" and a file
   27: "libm-test-ulps.h" with platform specific deltas.
   28: 
   29: The test drivers test-double.c, test-float.c, test-ldouble.c test the
   30: normal double, float and long double implementation of libm.  The test
   31: drivers with an i in it (test-idouble.c, test-ifloat.c,
   32: test-ildoubl.c) test the corresponding inline functions (where
   33: available - otherwise they also test the real functions in libm).
   34: 
   35: "gen-libm-test.pl" needs a platform specific files with ULPs (Units of
   36: Last Precision).  The file is called "libm-test-ulps" and lives in
   37: platform specific sysdep directory.
   38: 
   39: How can I generate "libm-test-ulps"?
   40: ====================================
   41: 
   42: The test drivers have an option "-u" to output an unsorted list of all
   43: epsilons that the functions have.  The output can be read in directly
   44: but it's better to pretty print it first.  "gen-libm-test.pl"  has an option
   45: to generate a pretty-printed and sorted new ULPs file from the output
   46: of the test drivers.
   47: 
   48: To generate a new "libm-test-ulps" file, first remove "ULPs" file in the
   49: current directory, then you can execute for example:
   50: test-double -u --ignore-max-ulp=yes
   51: This generates a file "ULPs" with all double ULPs in it, ignoring any
   52: previous calculated ULPs.
   53: Now generate the ULPs for all other formats, the tests will be appending
   54: the data to the "ULPs" file.  As final step run "gen-libm-test.pl" with the
   55: file as input and ask to generate a pretty printed output in the file "NewUlps":
   56:   gen-libm-test.pl -u ULPs -n
   57: 
   58: Now you can rename "NewUlps" to "libm-test-ulps" and move it into
   59: sysdeps.
   60: 
   61: Contents of libm-test-ulps
   62: ==========================
   63: Since libm-test-ulps can be generated automatically, just a few
   64: notes.  The file contains lines for single tests, like:
   65: Test "cos (pi/2) == 0":
   66: float:  1
   67: 
   68: and lines for maximal errors of single functions, like:
   69: Function "yn":
   70: idouble:  6.0000
   71: 
   72: The keywords are float, ifloat, double, idouble, ldouble and ildouble
   73: (the prefix i stands for inline).  You can also specify known
   74: failures, e.g.:
   75: 
   76: Test "cos (pi/2) == 0":
   77: float:  1
   78: float: fail
   79: 
   80: Adding tests to libm-test.inc
   81: =============================
   82: 
   83: The tests are evaluated by a set of special test macros.  The macros
   84: start with "TEST_" followed by a specification the input values, an
   85: underscore and a specification of the output values.  As an example,
   86: the test macro for a function with input of type FLOAT (FLOAT is
   87: either float, double, long double) and output of type FLOAT is
   88: "TEST_f_f".  The macro's parameter are the name of the function, the
   89: input parameter, output parameter and optionally one exception
   90: parameter.
   91: 
   92: The accepted parameter types are:
   93: - "f" for FLOAT
   94: - "b" for boolean - just tests if the output parameter evaluates to 0
   95:   or 1 (only for output).
   96: - "c" for complex.  This parameter needs two values, first the real,
   97:   then the imaginary part.
   98: - "i" for int.
   99: - "l" for long int.
  100: - "L" for long long int.
  101: - "F" for the address of a FLOAT (only as input parameter)
  102: - "I" for the address of an int (only as input parameter)
  103: 
  104: Some functions need special handling.  For example gamma sets the
  105: global variable signgam and frexp takes an argument to &int.  This
  106: special treatment is coded in "gen-libm-test.pl" and used while
  107: parsing "libm-test.inc".