diff options
Diffstat (limited to 'math/README.libm-test')
| -rw-r--r-- | math/README.libm-test | 81 |
1 files changed, 67 insertions, 14 deletions
diff --git a/math/README.libm-test b/math/README.libm-test index b8353b13b4..4fa675cc1b 100644 --- a/math/README.libm-test +++ b/math/README.libm-test @@ -21,20 +21,45 @@ NaNs and minus zero), some more or less random values are tested. Files that are part of libm-test ================================ -The main file is "libm-test.inc". It is platform and floating point -format independent. The file must be preprocessed by the Perl script -"gen-libm-test.pl". The results are "libm-test.c" and a file -"libm-test-ulps.h" with platform specific deltas. - -The test drivers test-double.c, test-float.c, test-ldouble.c test the -normal double, float and long double implementation of libm. The test -drivers with an i in it (test-idouble.c, test-ifloat.c, -test-ildoubl.c) test the corresponding inline functions (where -available - otherwise they also test the real functions in libm). - -"gen-libm-test.pl" needs a platform specific files with ULPs (Units of -Last Precision). The file is called "libm-test-ulps" and lives in -platform specific sysdep directory. +The main file is "libm-test.inc". It is independent of the target +platform and the specific real floating type and format and contains +placeholder test "templates" for math functions defined in libm. +The file, along with a generated file named "auto-libm-test-out", +is preprocessed by the Perl script "gen-libm-test.pl" to expand +the templates and produce a set of test cases for each math function +that are specific to the target platform but still independent of +the real floating type. The results of the processing are +"libm-test.c" and a file "libm-test-ulps.h" with platform specific +deltas by which the actual math function results may deviate from +the expected results and still be considered correct. + +The test drivers "test-double.c", "test-float.c", and "test-ldouble.c" +test the normal double, float and long double implementation of libm. +The test drivers with an 'i' in their name ("test-idouble.c", +"test-ifloat.c", and "test-ildoubl.c") test the corresponding inline +functions (where available - otherwise they also test the real +functions in libm). Each driver selects the desired real floating +type to exercise the math functions to test with (float, double, or +long double) by defining a small set of macros just before including +the generic "libm-test.c" file. Each driver also either defines or +undefines the __NO_MATH_INLINES macro just before including +"libm-test.c" to select either the real or inline functions, +respectively. Each driver is compiled into a single executable test +program with the corresponding name. + +As mentioned above, the "gen-libm-test.pl" script looks for a file +named "libm-test-ulps" in the platform specific sysdep directory (or +its fpu or nofpu subdirectory) and for each variant (real floating +type and rounding mode) of every tested function reads from it the +maximum difference expressed as Units of Least Precision (ULP) the +actual result of the function may deviate from the expected result +before it's considered incorrect. + +The "auto-libm-test-out" file contains sets of test cases to exercise, +the conditions under which to exercise each, and the expected results. +The file is generated by the "gen-auto-libm-tests" program from the +"auto-libm-test-in" file. See the comments in gen-auto-libm-tests.c +for details about the content and format of the -in and -out files. How can I generate "libm-test-ulps"? ==================================== @@ -101,3 +126,31 @@ The accepted parameter types are: - "L" for long long int. - "F" for the address of a FLOAT (only as input parameter) - "I" for the address of an int (only as input parameter) + +How to read the test output +=========================== + +Running each test on its own at the default level of verbosity will +print on stdout a line describing the implementation of math functions +exercised by the test (float, double, or long double), along with +whether the inline set has been selected, regardless of whether or +not any inline functions actually exist. This is then followed by +the details of test failures (if any). The output concludes by +a summary listing the number of test cases exercised and the number +of test failures uncovered. + +For each test failure (and for each test case at higher levels of +verbosity), the output contains the name of the function under test +and its arguments or conditions that triggered the failure. Note +that the name of the function in the output need not correspond +exactly to the name of the math function actually invoked. For example, +the output will refer to the "acos" function even if the actual function +under test is acosf (for the float version) or acosl (for the long +double version). Also note that the function arguments may be shown +in either the decimal or the hexadecimal floating point format which +may or may not correspond to the format used in the auto-libm-test-in +file. Besides the name of the function, for each test failure the +output contains the actual and expected results and the difference +between the two, printed in both the decimal and hexadecimal +floating point format, and the ULP and maximum ULP for the test +case. |