1999-10-25 20:18:27 +00:00
|
|
|
README for libm-test math test suite
|
|
|
|
|
====================================
|
|
|
|
|
|
|
|
|
|
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".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
What is tested?
|
|
|
|
|
===============
|
|
|
|
|
The tests just evaluate the functions at specified points and compare
|
|
|
|
|
the results with precomputed values and the requirements of the ISO
|
|
|
|
|
C99 standard.
|
|
|
|
|
|
|
|
|
|
Besides testing the special values mandated by IEEE 754 (infinities,
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
How can I generate "libm-test-ulps"?
|
|
|
|
|
====================================
|
|
|
|
|
|
New Makefile target `regen-ulps'.
The wiki "Regeneration" page has this to say about update ULPs.
"The libm-test-ulps files are semiautomatically updated. To
update an ulps baseline, run each of the failing tests (test-float,
test-double, etc.) with -u; this will generate a file called ULPs;
concatenate each of those files with the existing libm-test-ulps
file, after removing any entries for particularly huge numbers of
ulps that you do not want to mark as expected. Then run
gen-libm-test.pl -n -u FILE where FILE is the concatenated file
produced in the previous step. This generates a file called
NewUlps which is the new sorted version of libm-test-ulps."
The same information is listed in math/README.libm-test, and is a
lot of manual work that you often want to run over-and-over again
while working on a particular test.
The `regen-ulps' convenience target does this automatically for
developers.
We strictly assume the source tree is readonly and add a
new --output-dir option to libm-test.inc to allow for writing
out ULPs to $(objpfx).
When run the new target does the following:
* Starts with the baseline ULPs file.
* Runs each of the libm math tests with -u.
* Adds new changes seen with -u to the baseline.
* Sorts and prepares the test output with gen-libm-test.pl.
* Leaves math/NewUlps in your build tree to copy to your source
tree, cleanup, and checkin.
The math test documentation in math/README.libm-test is updated
document the new Makefile target.
---
2013-04-06 Carlos O'Donell <carlos@redhat.com>
* Makefile.in (regen-ulps): New target.
* math/Makefile [ifneq (no,$(PERL)]: Declare regen-ulps with .PHONY.
[ifneq (no,$(PERL)] (run-regen-ulps): New variable.
[ifneq (no,$(PERL)] (regen-ulps): New target.
[ifeq (no,$(PERL)] (regen-ulps): New target.
* math/libm-test.inc (ulps_file_name): Define.
(output_dir): New variable.
(options): Add "output-dir" option.
(parse_opt): Handle 'o' case.
(main): If output_dir is non-NULL use it as a prefix
otherwise use "".
* math/README.libm-test: Update `How can I generate "libm-test-ulps"?'
2013-04-06 20:22:47 +00:00
|
|
|
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 manually generate a new "libm-test-ulps" file, first remove "ULPs"
|
|
|
|
|
file in the current directory, then you can execute for example:
|
2013-04-06 21:13:19 +00:00
|
|
|
./testrun.sh math/test-double -u --ignore-max-ulp=yes
|
1999-10-25 20:18:27 +00:00
|
|
|
This generates a file "ULPs" with all double ULPs in it, ignoring any
|
New Makefile target `regen-ulps'.
The wiki "Regeneration" page has this to say about update ULPs.
"The libm-test-ulps files are semiautomatically updated. To
update an ulps baseline, run each of the failing tests (test-float,
test-double, etc.) with -u; this will generate a file called ULPs;
concatenate each of those files with the existing libm-test-ulps
file, after removing any entries for particularly huge numbers of
ulps that you do not want to mark as expected. Then run
gen-libm-test.pl -n -u FILE where FILE is the concatenated file
produced in the previous step. This generates a file called
NewUlps which is the new sorted version of libm-test-ulps."
The same information is listed in math/README.libm-test, and is a
lot of manual work that you often want to run over-and-over again
while working on a particular test.
The `regen-ulps' convenience target does this automatically for
developers.
We strictly assume the source tree is readonly and add a
new --output-dir option to libm-test.inc to allow for writing
out ULPs to $(objpfx).
When run the new target does the following:
* Starts with the baseline ULPs file.
* Runs each of the libm math tests with -u.
* Adds new changes seen with -u to the baseline.
* Sorts and prepares the test output with gen-libm-test.pl.
* Leaves math/NewUlps in your build tree to copy to your source
tree, cleanup, and checkin.
The math test documentation in math/README.libm-test is updated
document the new Makefile target.
---
2013-04-06 Carlos O'Donell <carlos@redhat.com>
* Makefile.in (regen-ulps): New target.
* math/Makefile [ifneq (no,$(PERL)]: Declare regen-ulps with .PHONY.
[ifneq (no,$(PERL)] (run-regen-ulps): New variable.
[ifneq (no,$(PERL)] (regen-ulps): New target.
[ifeq (no,$(PERL)] (regen-ulps): New target.
* math/libm-test.inc (ulps_file_name): Define.
(output_dir): New variable.
(options): Add "output-dir" option.
(parse_opt): Handle 'o' case.
(main): If output_dir is non-NULL use it as a prefix
otherwise use "".
* math/README.libm-test: Update `How can I generate "libm-test-ulps"?'
2013-04-06 20:22:47 +00:00
|
|
|
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.pl" with the
|
|
|
|
|
file as input and ask to generate a pretty printed output in the file
|
|
|
|
|
"NewUlps":
|
2004-03-24 22:05:34 +00:00
|
|
|
gen-libm-test.pl -u ULPs -n
|
New Makefile target `regen-ulps'.
The wiki "Regeneration" page has this to say about update ULPs.
"The libm-test-ulps files are semiautomatically updated. To
update an ulps baseline, run each of the failing tests (test-float,
test-double, etc.) with -u; this will generate a file called ULPs;
concatenate each of those files with the existing libm-test-ulps
file, after removing any entries for particularly huge numbers of
ulps that you do not want to mark as expected. Then run
gen-libm-test.pl -n -u FILE where FILE is the concatenated file
produced in the previous step. This generates a file called
NewUlps which is the new sorted version of libm-test-ulps."
The same information is listed in math/README.libm-test, and is a
lot of manual work that you often want to run over-and-over again
while working on a particular test.
The `regen-ulps' convenience target does this automatically for
developers.
We strictly assume the source tree is readonly and add a
new --output-dir option to libm-test.inc to allow for writing
out ULPs to $(objpfx).
When run the new target does the following:
* Starts with the baseline ULPs file.
* Runs each of the libm math tests with -u.
* Adds new changes seen with -u to the baseline.
* Sorts and prepares the test output with gen-libm-test.pl.
* Leaves math/NewUlps in your build tree to copy to your source
tree, cleanup, and checkin.
The math test documentation in math/README.libm-test is updated
document the new Makefile target.
---
2013-04-06 Carlos O'Donell <carlos@redhat.com>
* Makefile.in (regen-ulps): New target.
* math/Makefile [ifneq (no,$(PERL)]: Declare regen-ulps with .PHONY.
[ifneq (no,$(PERL)] (run-regen-ulps): New variable.
[ifneq (no,$(PERL)] (regen-ulps): New target.
[ifeq (no,$(PERL)] (regen-ulps): New target.
* math/libm-test.inc (ulps_file_name): Define.
(output_dir): New variable.
(options): Add "output-dir" option.
(parse_opt): Handle 'o' case.
(main): If output_dir is non-NULL use it as a prefix
otherwise use "".
* math/README.libm-test: Update `How can I generate "libm-test-ulps"?'
2013-04-06 20:22:47 +00:00
|
|
|
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.pl" has an option to generate a pretty-printed and
|
|
|
|
|
sorted new ULPs file from the output of the test drivers.
|
1999-10-25 20:18:27 +00:00
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
Function "yn":
|
|
|
|
|
idouble: 6.0000
|
|
|
|
|
|
|
|
|
|
The keywords are float, ifloat, double, idouble, ldouble and ildouble
|
2013-05-04 16:45:15 +00:00
|
|
|
(the prefix i stands for inline).
|
1999-10-25 20:18:27 +00:00
|
|
|
|
|
|
|
|
Adding tests to libm-test.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
|
|
|
|
|
underscore and a specification of the output values. As an example,
|
|
|
|
|
the test macro for a function with input of type FLOAT (FLOAT is
|
|
|
|
|
either float, double, long double) and output of type FLOAT is
|
|
|
|
|
"TEST_f_f". The macro's parameter are the name of the function, the
|
|
|
|
|
input parameter, output parameter and optionally one exception
|
|
|
|
|
parameter.
|
|
|
|
|
|
|
|
|
|
The accepted parameter types are:
|
|
|
|
|
- "f" for FLOAT
|
|
|
|
|
- "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,
|
|
|
|
|
then the imaginary part.
|
|
|
|
|
- "i" for int.
|
|
|
|
|
- "l" for long int.
|
|
|
|
|
- "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)
|
|
|
|
|
|
|
|
|
|
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".
|
