projects / thirdparty / glibc.git / blame
| Commit | Line | Data |
|---|---|---|
| a9b5d2ee UD |
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 | ||
| 26510bdd CD |
42 | To automatically generate a new "libm-test-ulps" run "make regen-ulps". |
| 43 | This generates the file "math/NewUlps" in the build directory. The file | |
| 44 | contains the sorted results of all the tests. You can use the "NewUlps" | |
| 45 | file as the machine's updated "libm-test-ulps" file. Copy "NewUlps" to | |
| 46 | "libm-test-ulps" in the appropriate machine sysdep directory. Verify | |
| 47 | the changes, post your patch, and check it in after review. | |
| 48 | ||
| 49 | To manually generate a new "libm-test-ulps" file, first remove "ULPs" | |
| 50 | file in the current directory, then you can execute for example: | |
| 085b2d41 | 51 | ./testrun.sh math/test-double -u --ignore-max-ulp=yes |
| a9b5d2ee | 52 | This generates a file "ULPs" with all double ULPs in it, ignoring any |
| 26510bdd CD |
53 | previously calculated ULPs, and running with the newly built dynamic |
| 54 | loader and math library (assumes you didn't install your build). Now | |
| 55 | generate the ULPs for all other formats, the tests will be appending the | |
| 56 | data to the "ULPs" file. As final step run "gen-libm-test.pl" with the | |
| 57 | file as input and ask to generate a pretty printed output in the file | |
| 58 | "NewUlps": | |
| 9ce0ecbe | 59 | gen-libm-test.pl -u ULPs -n |
| 26510bdd CD |
60 | Copy "NewUlps" to "libm-test-ulps" in the appropriate machine sysdep |
| 61 | directory. | |
| 62 | ||
| 63 | Note that the test drivers have an option "-u" to output an unsorted | |
| 64 | list of all epsilons that the functions have. The output can be read | |
| 65 | in directly but it's better to pretty print it first. | |
| 66 | "gen-libm-test.pl" has an option to generate a pretty-printed and | |
| 67 | sorted new ULPs file from the output of the test drivers. | |
| a9b5d2ee UD |
68 | |
| 69 | Contents of libm-test-ulps | |
| 70 | ========================== | |
| 71 | Since libm-test-ulps can be generated automatically, just a few | |
| 72 | notes. The file contains lines for single tests, like: | |
| 73 | Test "cos (pi/2) == 0": | |
| 74 | float: 1 | |
| 75 | ||
| 76 | and lines for maximal errors of single functions, like: | |
| 77 | Function "yn": | |
| 78 | idouble: 6.0000 | |
| 79 | ||
| 80 | The keywords are float, ifloat, double, idouble, ldouble and ildouble | |
| b7dab1e4 | 81 | (the prefix i stands for inline). |
| a9b5d2ee UD |
82 | |
| 83 | Adding tests to libm-test.inc | |
| 84 | ============================= | |
| 85 | ||
| 86 | The tests are evaluated by a set of special test macros. The macros | |
| 87 | start with "TEST_" followed by a specification the input values, an | |
| 88 | underscore and a specification of the output values. As an example, | |
| 89 | the test macro for a function with input of type FLOAT (FLOAT is | |
| 90 | either float, double, long double) and output of type FLOAT is | |
| 91 | "TEST_f_f". The macro's parameter are the name of the function, the | |
| 92 | input parameter, output parameter and optionally one exception | |
| 93 | parameter. | |
| 94 | ||
| 95 | The accepted parameter types are: | |
| 96 | - "f" for FLOAT | |
| 97 | - "b" for boolean - just tests if the output parameter evaluates to 0 | |
| 98 | or 1 (only for output). | |
| 99 | - "c" for complex. This parameter needs two values, first the real, | |
| 100 | then the imaginary part. | |
| 101 | - "i" for int. | |
| 102 | - "l" for long int. | |
| 103 | - "L" for long long int. | |
| 104 | - "F" for the address of a FLOAT (only as input parameter) | |
| 105 | - "I" for the address of an int (only as input parameter) | |
| 106 | ||
| 107 | Some functions need special handling. For example gamma sets the | |
| 108 | global variable signgam and frexp takes an argument to &int. This | |
| 109 | special treatment is coded in "gen-libm-test.pl" and used while | |
| 110 | parsing "libm-test.inc". |