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