The libm-test math test suite tests a number of function points of
math functions in the GNU C library. The following sections contain a
-brief overview. Please note that the test drivers and the Perl script
-"gen-libm-test.pl" have some options. A full list of options is
-available with --help (for the test drivers) and -h for
-"gen-libm-test.pl".
+brief overview. Please note that the test drivers and the Python
+script "gen-libm-test.py" have some options. A full list of options
+is available with --help (for the test drivers) and -h for
+"gen-libm-test.py".
What is 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 files are "libm-test-<func>.inc". They are independent of
+the target platform and the specific real floating type and format and
+contain placeholder test "templates" for math functions defined in
+libm. These files, along with generated files named
+"auto-libm-test-out-<func>", are preprocessed by the Python script
+"gen-libm-test.py" 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-<func>.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-<func>.c", "test-float-<func>.c", and
+"test-ldouble-<func>.c", generated by the Makefile, test the normal
+double, float and long double implementation of libm. The test
+drivers with an 'i' in their name ("test-idouble-<func>.c",
+"test-ifloat-<func>.c", and "test-ildoubl-<func>.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-<func>.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.py" 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-<func>" files contain sets of test cases to
+exercise, the conditions under which to exercise each, and the
+expected results. The files are 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"?
====================================
-The test drivers have an option "-u" to output an unsorted list of all
-epsilons that the functions have. The output can be read in directly
-but it's better to pretty print it first. "gen-libm-test.pl" has an option
-to generate a pretty-printed and sorted new ULPs file from the output
-of the test drivers.
+To automatically generate a new "libm-test-ulps" run "make regen-ulps".
+This generates the file "math/NewUlps" in the build directory. The file
+contains the sorted results of all the tests. You can use the "NewUlps"
+file as the machine's updated "libm-test-ulps" file. Copy "NewUlps" to
+"libm-test-ulps" in the appropriate machine sysdep directory. Verify
+the changes, post your patch, and check it in after review.
-To generate a new "libm-test-ulps" file, first remove "ULPs" file in the
-current directory, then you can execute for example:
-test-double -u --ignore-max-ulp=yes
+To manually generate a new "libm-test-ulps" file, first remove "ULPs"
+file in the current directory, then you can execute for example:
+ ./testrun.sh math/test-double -u --ignore-max-ulp=yes
This generates a file "ULPs" with all double ULPs in it, ignoring any
-previous calculated ULPs.
-Now generate the ULPs for all other formats, the tests will be appending
-the data to the "ULPs" file. As final step run "gen-libm-test.pl" with the
-file as input and ask to generate a pretty printed output in the file "NewUlps":
- gen-libm-test.pl -u ULPs -n
-
-Now you can rename "NewUlps" to "libm-test-ulps" and move it into
-sysdeps.
+previously calculated ULPs, and running with the newly built dynamic
+loader and math library (assumes you didn't install your build). Now
+generate the ULPs for all other formats, the tests will be appending the
+data to the "ULPs" file. As final step run "gen-libm-test.py" with the
+file as input and ask to generate a pretty printed output in the file
+"NewUlps":
+ gen-libm-test.py -u ULPs -n NewUlps
+Copy "NewUlps" to "libm-test-ulps" in the appropriate machine sysdep
+directory.
+
+Note that the test drivers have an option "-u" to output an unsorted
+list of all epsilons that the functions have. The output can be read
+in directly but it's better to pretty print it first.
+"gen-libm-test.py" has an option to generate a pretty-printed and
+sorted new ULPs file from the output of the test drivers.
Contents of libm-test-ulps
==========================
-Since libm-test-ulps can be generated automatically, just a few
-notes. The file contains lines for single tests, like:
-Test "cos (pi/2) == 0":
-float: 1
-and lines for maximal errors of single functions, like:
+Since libm-test-ulps can be generated automatically, just a few notes.
+The file contains lines for maximal errors of single functions, like:
+
Function "yn":
-idouble: 6.0000
+idouble: 6
The keywords are float, ifloat, double, idouble, ldouble and ildouble
-(the prefix i stands for inline). You can also specify known
-failures, e.g.:
+(the prefix i stands for inline).
-Test "cos (pi/2) == 0":
-float: 1
-float: fail
-
-Adding tests to libm-test.inc
-=============================
+Adding tests to libm-test-<func>.inc
+====================================
The tests are evaluated by a set of special test macros. The macros
start with "TEST_" followed by a specification the input values, an
The accepted parameter types are:
- "f" for FLOAT
+- "j" for long double.
+- "a" for ARG_FLOAT, the argument type for narrowing functions.
- "b" for boolean - just tests if the output parameter evaluates to 0
or 1 (only for output).
- "c" for complex. This parameter needs two values, first the real,
- "i" for int.
- "l" for long int.
- "L" for long long int.
+- "u" for unsigned int.
+- "M" for intmax_t.
+- "U" for uintmax_t.
+- "p" for an argument (described in the previous character) passed
+ through a pointer rather than directly.
- "F" for the address of a FLOAT (only as input parameter)
- "I" for the address of an int (only as input parameter)
-
-Some functions need special handling. For example gamma sets the
-global variable signgam and frexp takes an argument to &int. This
-special treatment is coded in "gen-libm-test.pl" and used while
-parsing "libm-test.inc".
+- "1" for an additional output (either output through a pointer passed
+ as an argument, or to a global variable such as signgam).
+
+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.
projects / thirdparty / glibc.git / blobdiff