You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
444 lines
20 KiB
444 lines
20 KiB
|
|
TestFloat Release 2a Source Documentation |
|
|
|
John R. Hauser |
|
1998 December 16 |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Introduction |
|
|
|
TestFloat is a program for testing that a floating-point implementation |
|
conforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. |
|
All standard operations supported by the system can be tested, except for |
|
conversions to and from decimal. Any of the following machine formats can |
|
be tested: single precision, double precision, extended double precision, |
|
and/or quadruple precision. Testing extended double-precision or quadruple- |
|
precision formats requires a C compiler that supports 64-bit integer |
|
arithmetic. |
|
|
|
This document gives information needed for compiling and/or porting |
|
TestFloat. |
|
|
|
The source code for TestFloat is intended to be relatively machine- |
|
independent. TestFloat is written in C, and should be compilable using |
|
any ISO/ANSI C compiler. At the time of this writing, the program has |
|
been successfully compiled using the GNU C Compiler (`gcc') for several |
|
platforms. Because ISO/ANSI C does not provide access to some features |
|
of IEC/IEEE floating-point such as the exception flags, porting TestFloat |
|
unfortunately involves some machine-dependent coding. |
|
|
|
TestFloat depends on SoftFloat, which is a software implementation of |
|
floating-point that conforms to the IEC/IEEE Standard. SoftFloat is not |
|
included with the TestFloat sources. It can be obtained from the Web |
|
page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. |
|
|
|
In addition to a program for testing a machine's floating-point, the |
|
TestFloat package includes a variant for testing SoftFloat called |
|
`testsoftfloat'. The sources for both programs are intermixed, and both are |
|
described here. |
|
|
|
The first release of TestFloat (Release 1) was called _FloatTest_. The old |
|
name has been obsolete for some time. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Limitations |
|
|
|
TestFloat as written requires an ISO/ANSI-style C compiler. No attempt has |
|
been made to accommodate compilers that are not ISO-conformant. Older ``K&R- |
|
style'' compilers are not adequate for compiling TestFloat. All testing I |
|
have done so far has been with the GNU C Compiler. Compilation with other |
|
compilers should be possible but has not been tested. |
|
|
|
The TestFloat sources assume that source code file names can be longer than |
|
8 characters. In order to compile under an MS-DOS-style system, many of the |
|
source files will need to be renamed, and the source and makefiles edited |
|
appropriately. Once compiled, the TestFloat program does not depend on the |
|
existence of long file names. |
|
|
|
The underlying machine is assumed to be binary with a word size that is a |
|
power of 2. Bytes are 8 bits. Testing of extended double-precision and |
|
quadruple-precision formats depends on the C compiler implementing a 64-bit |
|
integer type. If the largest integer type supported by the C compiler is |
|
32 bits, only single- and double-precision operations can be tested. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Contents |
|
|
|
Introduction |
|
Limitations |
|
Contents |
|
Legal Notice |
|
TestFloat Source Directory Structure |
|
Target-Independent Modules |
|
Target-Specific Modules |
|
Target-Specific Header Files |
|
processors/*.h |
|
testfloat/*/milieu.h |
|
Target-Specific Floating-Point Subroutines |
|
Steps to Creating the TestFloat Executables |
|
Improving the Random Number Generator |
|
Contact Information |
|
|
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Legal Notice |
|
|
|
TestFloat was written by John R. Hauser. |
|
|
|
THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort |
|
has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT |
|
TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO |
|
PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY |
|
AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
TestFloat Source Directory Structure |
|
|
|
Because TestFloat is targeted to multiple platforms, its source code |
|
is slightly scattered between target-specific and target-independent |
|
directories and files. The directory structure is as follows: |
|
|
|
processors |
|
testfloat |
|
templates |
|
386-Win32-gcc |
|
SPARC-Solaris-gcc |
|
|
|
The two topmost directories and their contents are: |
|
|
|
testfloat - Most of the source code needed for TestFloat. |
|
processors - Target-specific header files that are not specific to |
|
TestFloat. |
|
|
|
Within the `testfloat' directory are subdirectories for each of the |
|
targeted platforms. The TestFloat source code is distributed with targets |
|
`386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already |
|
prepared. These can be used as examples for porting to new targets. Source |
|
files that are not within these target-specific subdirectories are intended |
|
to be target-independent. |
|
|
|
The naming convention used for the target-specific directories is |
|
`<processor>-<executable-type>-<compiler>'. The names of the supplied |
|
target directories should be interpreted as follows: |
|
|
|
<processor>: |
|
386 - Intel 386-compatible processor. |
|
SPARC - SPARC processor (as used by Sun machines). |
|
<executable-type>: |
|
Win32 - Microsoft Win32 executable. |
|
Solaris - Sun Solaris executable. |
|
<compiler>: |
|
gcc - GNU C Compiler. |
|
|
|
You do not need to maintain this convention if you do not want to. |
|
|
|
Alongside the supplied target-specific directories there is a `templates' |
|
directory containing a set of ``generic'' target-specific source files. |
|
A new target directory can be created by copying the `templates' directory |
|
and editing the files inside. (Complete instructions for porting TestFloat |
|
to a new target are in the section _Steps_to_Creating_the_TestFloat_ |
|
_Executables_.) Note that the `templates' directory will not work as a |
|
target directory without some editing. To avoid confusion, it would be wise |
|
to refrain from editing the files inside `templates' directly. |
|
|
|
In addition to the distributed sources, TestFloat depends on the existence |
|
of an appropriately-compiled SoftFloat binary and the corresponding header |
|
file `softfloat.h'. SoftFloat is not included with the TestFloat sources. |
|
It can be obtained from the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/ |
|
arithmetic/SoftFloat.html'. |
|
|
|
As distributed, the makefiles for TestFloat assume the existence of three |
|
sibling directories: |
|
|
|
processors |
|
softfloat |
|
testfloat |
|
|
|
Only the `processors' and `testfloat' directories are included in the |
|
TestFloat package. The `softfloat' directory is assumed to contain a |
|
target-specific subdirectory within which the SoftFloat header file and |
|
compiled binary can be found. (See the source documentation accompanying |
|
SoftFloat.) The `processors' directory distributed with TestFloat is |
|
intended to be identical to that included with the SoftFloat source. |
|
|
|
These are the defaults, but other organizations of the sources are possible. |
|
The TestFloat makefiles and `milieu.h' files (see below) are easily edited |
|
to accommodate other arrangements. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Target-Independent Modules |
|
|
|
The TestFloat program is composed of a number of modules, some target- |
|
specific and some target-independent. The target-independent modules are as |
|
follows: |
|
|
|
-- The `fail' module provides a common routine for writing an error message |
|
and aborting. |
|
|
|
-- The `random' module generates random integer values. |
|
|
|
-- The `writeHex' module defines routines for writing the various types in |
|
the hexadecimal form used by TestFloat. |
|
|
|
-- The `testCases' module generates test cases for the various types. |
|
|
|
-- The `testLoops' module contains various routines for exercising two |
|
implementations of a function and reporting any differences observed. |
|
|
|
-- The `slowfloat' module provides the simple floating-point implementation |
|
used by `testsoftfloat' for comparing against SoftFloat. The heart |
|
of `slowfloat' is found in either `slowfloat-32' or `slowfloat-64', |
|
depending on whether the `BITS64' macro is defined. |
|
|
|
-- The `systfloat' module gives a SoftFloat-like interface to the machine's |
|
floating-point. |
|
|
|
-- The `testFunction' module implements `testfloat's main loop for testing a |
|
function for all of the relevant rounding modes and rounding precisions. |
|
(The `testsoftfloat' program contains its own version of this code.) |
|
|
|
-- The `testfloat' and `testsoftfloat' modules are the main modules for the |
|
`testfloat' and `testsoftfloat' programs. |
|
|
|
Except possibly for `systfloat', these modules should not need to be |
|
modified. |
|
|
|
The `systfloat' module uses the floating-point operations of the C language |
|
to access a machine's floating-point. Unfortunately, some IEC/IEEE |
|
floating-point operations are not accessible within ISO/ANSI C. The |
|
following machine functions cannot be tested unless an alternate `systfloat' |
|
module is provided: |
|
|
|
<float>_to_int32 (rounded according to rounding mode) |
|
<float>_to_int64 (rounded according to rounding mode) |
|
<float>_round_to_int |
|
<float>_rem |
|
<float>_sqrt, except float64_sqrt |
|
<float>_eq_signaling |
|
<float>_le_quiet |
|
<float>_lt_quiet |
|
|
|
The `-list' option to `testfloat' will show the operations the program is |
|
prepared to test. The section _Target-Specific_Floating-Point_Subroutines_ |
|
later in this document explains how to create a target-specific `systfloat' |
|
module to change the set of testable functions. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Target-Specific Modules |
|
|
|
No target-specific modules are needed for `testsoftfloat'. |
|
|
|
The `testfloat' program uses two target-specific modules: |
|
|
|
-- The `systmodes' module defines functions for setting the modes |
|
controlling the system's floating-point, including the rounding mode and |
|
the rounding precision for extended double precision. |
|
|
|
-- The `systflags' module provides a function for clearing and examining the |
|
system's floating-point exception flags. |
|
|
|
These modules must be supplied for each target. They can be implemented in |
|
any way desired, so long as all is reflected in the target's makefile. For |
|
the targets that come with the distributed source, each of these modules is |
|
implemented as a single assembly language or C language source file. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Target-Specific Header Files |
|
|
|
The purpose of the two target-specific header files is detailed below. |
|
In the following, the `*' symbol is used in place of the name of a specific |
|
target, such as `386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some |
|
other text as explained below. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
processors/*.h |
|
|
|
The target-specific `processors' header file defines integer types |
|
of various sizes, and also defines certain C preprocessor macros that |
|
characterize the target. The two examples supplied are `386-gcc.h' and |
|
`SPARC-gcc.h'. The naming convention used for processor header files is |
|
`<processor>-<compiler>.h'. The `processors' header file used to compile |
|
TestFloat should be the same as that used to compile SoftFloat. |
|
|
|
If 64-bit integers are supported by the compiler, the macro name `BITS64' |
|
should be defined here along with the corresponding 64-bit integer |
|
types. In addition, the function-like macro `LIT64' must be defined for |
|
constructing 64-bit integer literals (constants). The `LIT64' macro is used |
|
consistently in the TestFloat code to annotate 64-bit literals. |
|
|
|
If an inlining attribute (such as an `inline' keyword) is provided by the |
|
compiler, the macro `INLINE' should be defined to the appropriate keyword. |
|
If not, `INLINE' can be set to the keyword `static'. The `INLINE' macro |
|
appears in the TestFloat source code before every function that should be |
|
inlined by the compiler. |
|
|
|
For maximum flexibility, the TestFloat source files do not include the |
|
`processors' header file directly; rather, this file is included by the |
|
target-specific `milieu.h' header, and `milieu.h' is included by the source |
|
files. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
testfloat/*/milieu.h |
|
|
|
The `milieu.h' header file provides declarations that are needed to |
|
compile TestFloat. In particular, it is through this header file that |
|
the appropriate `processors' header is included to characterize the target |
|
processor. In addition, deviations from ISO/ANSI C by the compiler (such as |
|
names not properly declared in system header files) are corrected in this |
|
header if possible. |
|
|
|
If the preprocessor macro `BITS64' is defined in the `processors' header |
|
file but only the 32-bit version of SoftFloat is actually used, the `BITS64' |
|
macro should be undefined here after the `processors' header has defined it. |
|
|
|
If the C compiler implements the `long double' floating-point type of C |
|
as extended double precision, then `LONG_DOUBLE_IS_FLOATX80' should be |
|
defined here. Alternatively, if the C `long double' type is implemented as |
|
quadruple precision, `LONG_DOUBLE_IS_FLOAT128' should be defined. At most |
|
one of these macros should be defined. A C compiler is allowed to implement |
|
`long double' the same as `double', in which case neither of these macros |
|
should be defined. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Target-Specific Floating-Point Subroutines |
|
|
|
This section applies only to `testfloat' and not to `testsoftfloat'. |
|
|
|
By default, TestFloat tests a machine's floating-point by testing the |
|
floating-point operations of the C language. Unfortunately, some IEC/IEEE |
|
floating-point operations are not defined within ISO/ANSI C. If a machine |
|
implements such ``non-C'' operations, target-specific subroutines for |
|
the operations can be supplied to allow TestFloat to test these machine |
|
features. Typically, such subroutines will need to be written in assembly |
|
language, although equivalent functions can sometimes be found among the |
|
system's software libraries. |
|
|
|
The following machine functions cannot be tested by TestFloat unless target- |
|
specific subroutines are supplied for them: |
|
|
|
<float>_to_int32 (rounded according to rounding mode) |
|
<float>_to_int64 (rounded according to rounding mode) |
|
<float>_round_to_int |
|
<float>_rem |
|
<float>_sqrt, except float64_sqrt |
|
<float>_eq_signaling |
|
<float>_le_quiet |
|
<float>_lt_quiet |
|
|
|
In addition to these, none of the `floatx80' functions can be tested by |
|
default if the C `long double' type is something other than extended double |
|
precision; and likewise, none of the `float128' functions can be tested by |
|
default if `long double' is not quadruple precision. Since `long double' |
|
cannot be both extended double precision and quadruple precision at the |
|
same time, at least one of these types cannot be tested by TestFloat without |
|
appropriate subroutines being supplied for that type. (On the other hand, |
|
few systems implement _both_ extended double-precision and quadruple- |
|
precision floating-point; and unless a system does implement both, it does |
|
not need both tested.) |
|
|
|
Note that the `-list' option to `testfloat' will show the operations |
|
TestFloat is prepared to test. |
|
|
|
TestFloat's `systfloat' module supplies the system version of the functions |
|
to be tested. The names of the `systfloat' subroutines are the same as the |
|
function names used as arguments to the `testfloat' command but with `syst_' |
|
prefixed--thus, for example, `syst_float32_add' and `syst_int32_to_float32'. |
|
The default `systfloat' module maps these system functions to the standard |
|
C operations; so `syst_float32_add', for example, is implemented using the |
|
C `+' operation for the single-precision `float' type. For each system |
|
function supplied by `systfloat', a corresponding `SYST_<function>' |
|
preprocessor macro is defined in `systfloat.h' to indicate that the function |
|
exists to be tested (e.g., `SYST_FLOAT32_ADD'). The `systfloat.h' header |
|
file also declares function prototypes for the `systfloat' functions. |
|
|
|
(The `systfloat.h' file that comes with the TestFloat package declares |
|
prototypes for all of the possible `systfloat' functions, whether defined in |
|
`systfloat' or not. There is no penalty for declaring a function prototype |
|
that is never used.) |
|
|
|
A target-specific version of the `systfloat' module can easily be created to |
|
replace the generic one. This in fact has been done for the example targets |
|
`386-Win32-gcc' and `SPARC-Solaris-gcc'. For each target, an assembly |
|
language `systfloat.S' has been created in the target directory along with |
|
a corresponding `systfloat.h' header file defining the `SYST_<function>' |
|
macros for the functions implemented. The makefiles of the targets have |
|
been edited to use these target-specific versions of `systfloat' rather than |
|
the generic one. |
|
|
|
The `systfloat' modules of the example targets have been written entirely |
|
in assembly language in order to bypass any peculiarities of the C compiler. |
|
Although this is probably a good idea, it is certainly not required. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Steps to Creating the TestFloat Executables |
|
|
|
Porting and/or compiling TestFloat involves the following steps: |
|
|
|
1. Port SoftFloat and create a SoftFloat binary. (Refer to the |
|
documentation accompanying SoftFloat.) |
|
|
|
2. If one does not already exist, create an appropriate target-specific |
|
subdirectory under `testfloat' by copying the given `templates' |
|
directory. The remaining steps occur within the target-specific |
|
subdirectory. |
|
|
|
3. Edit the files `milieu.h' and `Makefile' to reflect the current |
|
environment. |
|
|
|
4. Make `testsoftfloat' by executing `make testsoftfloat' (or `make |
|
testsoftfloat.exe', or whatever the `testsoftfloat' executable is |
|
called). Verify that SoftFloat is working correctly by testing it with |
|
`testsoftfloat'. |
|
|
|
If you only wanted `testsoftfloat', you are done. The steps for `testfloat' |
|
continue: |
|
|
|
5. In the target-specific subdirectory, implement the `systmodes' and |
|
`systflags' modules. (The `syst_float_set_rounding_precision' function |
|
need not do anything if the system does not support extended double |
|
precision.) |
|
|
|
6. If the target machine supports standard floating-point functions that are |
|
not accessible within ISO/ANSI C, or if the C compiler cannot be trusted |
|
to use the machine's floating-point directly, create a target-specific |
|
`systfloat' module. |
|
|
|
7. In the target-specific subdirectory, execute `make'. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Improving the Random Number Generator |
|
|
|
If you are serious about using TestFloat for testing floating-point, you |
|
should consider replacing the supplied `random.c' with a better target- |
|
specific one. The standard C `rand' function is rather poor on some |
|
systems, and consequently `random.c' has been written to assume very little |
|
about the quality of `rand'. As a result, the `rand' function is called |
|
more frequently than it might need to be, shortening the time before |
|
the random number generator repeats, and possibly wasting time as well. |
|
If `rand' is better on your system, or if another better random number |
|
generator is available (such as `rand48' on most Unix systems), TestFloat |
|
can be improved by overriding the given `random.c' with a target-specific |
|
one. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Contact Information |
|
|
|
At the time of this writing, the most up-to-date information about |
|
TestFloat and the latest release can be found at the Web page `http:// |
|
HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'. |
|
|
|
|
|
|