Clarify math/README.libm-test. Add "How to read the test output."

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.