diff options
Diffstat (limited to 'tools/test/testfloat/testfloat-source.txt')
| -rw-r--r-- | tools/test/testfloat/testfloat-source.txt | 444 |
1 files changed, 444 insertions, 0 deletions
diff --git a/tools/test/testfloat/testfloat-source.txt b/tools/test/testfloat/testfloat-source.txt new file mode 100644 index 0000000..b8f7e9b --- /dev/null +++ b/tools/test/testfloat/testfloat-source.txt @@ -0,0 +1,444 @@ + +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 accomodate 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 accomodate 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'. + + |
