| 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".
|
|---|
