testfloat-source.txt revision 206917
1206917Smarius 2206917SmariusTestFloat Release 2a Source Documentation 3206917Smarius 4206917SmariusJohn R. Hauser 5206917Smarius1998 December 16 6206917Smarius 7206917Smarius 8206917Smarius------------------------------------------------------------------------------- 9206917SmariusIntroduction 10206917Smarius 11206917SmariusTestFloat is a program for testing that a floating-point implementation 12206917Smariusconforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. 13206917SmariusAll standard operations supported by the system can be tested, except for 14206917Smariusconversions to and from decimal. Any of the following machine formats can 15206917Smariusbe tested: single precision, double precision, extended double precision, 16206917Smariusand/or quadruple precision. Testing extended double-precision or quadruple- 17206917Smariusprecision formats requires a C compiler that supports 64-bit integer 18206917Smariusarithmetic. 19206917Smarius 20206917SmariusThis document gives information needed for compiling and/or porting 21206917SmariusTestFloat. 22206917Smarius 23206917SmariusThe source code for TestFloat is intended to be relatively machine- 24206917Smariusindependent. TestFloat is written in C, and should be compilable using 25206917Smariusany ISO/ANSI C compiler. At the time of this writing, the program has 26206917Smariusbeen successfully compiled using the GNU C Compiler (`gcc') for several 27206917Smariusplatforms. Because ISO/ANSI C does not provide access to some features 28206917Smariusof IEC/IEEE floating-point such as the exception flags, porting TestFloat 29206917Smariusunfortunately involves some machine-dependent coding. 30206917Smarius 31206917SmariusTestFloat depends on SoftFloat, which is a software implementation of 32206917Smariusfloating-point that conforms to the IEC/IEEE Standard. SoftFloat is not 33206917Smariusincluded with the TestFloat sources. It can be obtained from the Web 34206917Smariuspage `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. 35206917Smarius 36206917SmariusIn addition to a program for testing a machine's floating-point, the 37206917SmariusTestFloat package includes a variant for testing SoftFloat called 38206917Smarius`testsoftfloat'. The sources for both programs are intermixed, and both are 39206917Smariusdescribed here. 40206917Smarius 41206917SmariusThe first release of TestFloat (Release 1) was called _FloatTest_. The old 42206917Smariusname has been obsolete for some time. 43206917Smarius 44206917Smarius 45206917Smarius------------------------------------------------------------------------------- 46206917SmariusLimitations 47206917Smarius 48206917SmariusTestFloat as written requires an ISO/ANSI-style C compiler. No attempt has 49206917Smariusbeen made to accomodate compilers that are not ISO-conformant. Older ``K&R- 50206917Smariusstyle'' compilers are not adequate for compiling TestFloat. All testing I 51206917Smariushave done so far has been with the GNU C Compiler. Compilation with other 52206917Smariuscompilers should be possible but has not been tested. 53206917Smarius 54206917SmariusThe TestFloat sources assume that source code file names can be longer than 55206917Smarius8 characters. In order to compile under an MS-DOS-style system, many of the 56206917Smariussource files will need to be renamed, and the source and makefiles edited 57206917Smariusappropriately. Once compiled, the TestFloat program does not depend on the 58206917Smariusexistence of long file names. 59206917Smarius 60206917SmariusThe underlying machine is assumed to be binary with a word size that is a 61206917Smariuspower of 2. Bytes are 8 bits. Testing of extended double-precision and 62206917Smariusquadruple-precision formats depends on the C compiler implementing a 64-bit 63206917Smariusinteger type. If the largest integer type supported by the C compiler is 64206917Smarius32 bits, only single- and double-precision operations can be tested. 65206917Smarius 66206917Smarius 67206917Smarius------------------------------------------------------------------------------- 68206917SmariusContents 69206917Smarius 70206917Smarius Introduction 71206917Smarius Limitations 72206917Smarius Contents 73206917Smarius Legal Notice 74206917Smarius TestFloat Source Directory Structure 75206917Smarius Target-Independent Modules 76206917Smarius Target-Specific Modules 77206917Smarius Target-Specific Header Files 78206917Smarius processors/*.h 79206917Smarius testfloat/*/milieu.h 80206917Smarius Target-Specific Floating-Point Subroutines 81206917Smarius Steps to Creating the TestFloat Executables 82206917Smarius Improving the Random Number Generator 83206917Smarius Contact Information 84206917Smarius 85206917Smarius 86206917Smarius 87206917Smarius------------------------------------------------------------------------------- 88206917SmariusLegal Notice 89206917Smarius 90206917SmariusTestFloat was written by John R. Hauser. 91206917Smarius 92206917SmariusTHIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 93206917Smariushas been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 94206917SmariusTIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 95206917SmariusPERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 96206917SmariusAND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 97206917Smarius 98206917Smarius 99206917Smarius------------------------------------------------------------------------------- 100206917SmariusTestFloat Source Directory Structure 101206917Smarius 102206917SmariusBecause TestFloat is targeted to multiple platforms, its source code 103206917Smariusis slightly scattered between target-specific and target-independent 104206917Smariusdirectories and files. The directory structure is as follows: 105206917Smarius 106206917Smarius processors 107206917Smarius testfloat 108206917Smarius templates 109206917Smarius 386-Win32-gcc 110206917Smarius SPARC-Solaris-gcc 111206917Smarius 112206917SmariusThe two topmost directories and their contents are: 113206917Smarius 114206917Smarius testfloat - Most of the source code needed for TestFloat. 115206917Smarius processors - Target-specific header files that are not specific to 116206917Smarius TestFloat. 117206917Smarius 118206917SmariusWithin the `testfloat' directory are subdirectories for each of the 119206917Smariustargeted platforms. The TestFloat source code is distributed with targets 120206917Smarius`386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already 121206917Smariusprepared. These can be used as examples for porting to new targets. Source 122206917Smariusfiles that are not within these target-specific subdirectories are intended 123206917Smariusto be target-independent. 124206917Smarius 125206917SmariusThe naming convention used for the target-specific directories is 126206917Smarius`<processor>-<executable-type>-<compiler>'. The names of the supplied 127206917Smariustarget directories should be interpreted as follows: 128206917Smarius 129206917Smarius <processor>: 130206917Smarius 386 - Intel 386-compatible processor. 131206917Smarius SPARC - SPARC processor (as used by Sun machines). 132206917Smarius <executable-type>: 133206917Smarius Win32 - Microsoft Win32 executable. 134206917Smarius Solaris - Sun Solaris executable. 135206917Smarius <compiler>: 136206917Smarius gcc - GNU C Compiler. 137206917Smarius 138206917SmariusYou do not need to maintain this convention if you do not want to. 139206917Smarius 140206917SmariusAlongside the supplied target-specific directories there is a `templates' 141206917Smariusdirectory containing a set of ``generic'' target-specific source files. 142206917SmariusA new target directory can be created by copying the `templates' directory 143206917Smariusand editing the files inside. (Complete instructions for porting TestFloat 144206917Smariusto a new target are in the section _Steps_to_Creating_the_TestFloat_ 145206917Smarius_Executables_.) Note that the `templates' directory will not work as a 146206917Smariustarget directory without some editing. To avoid confusion, it would be wise 147206917Smariusto refrain from editing the files inside `templates' directly. 148206917Smarius 149206917SmariusIn addition to the distributed sources, TestFloat depends on the existence 150206917Smariusof an appropriately-compiled SoftFloat binary and the corresponding header 151206917Smariusfile `softfloat.h'. SoftFloat is not included with the TestFloat sources. 152206917SmariusIt can be obtained from the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/ 153206917Smariusarithmetic/SoftFloat.html'. 154206917Smarius 155206917SmariusAs distributed, the makefiles for TestFloat assume the existence of three 156206917Smariussibling directories: 157206917Smarius 158206917Smarius processors 159206917Smarius softfloat 160206917Smarius testfloat 161206917Smarius 162206917SmariusOnly the `processors' and `testfloat' directories are included in the 163206917SmariusTestFloat package. The `softfloat' directory is assumed to contain a 164206917Smariustarget-specific subdirectory within which the SoftFloat header file and 165206917Smariuscompiled binary can be found. (See the source documentation accompanying 166206917SmariusSoftFloat.) The `processors' directory distributed with TestFloat is 167206917Smariusintended to be identical to that included with the SoftFloat source. 168206917Smarius 169206917SmariusThese are the defaults, but other organizations of the sources are possible. 170206917SmariusThe TestFloat makefiles and `milieu.h' files (see below) are easily edited 171206917Smariusto accomodate other arrangements. 172206917Smarius 173206917Smarius 174206917Smarius------------------------------------------------------------------------------- 175206917SmariusTarget-Independent Modules 176206917Smarius 177206917SmariusThe TestFloat program is composed of a number of modules, some target- 178206917Smariusspecific and some target-independent. The target-independent modules are as 179206917Smariusfollows: 180206917Smarius 181206917Smarius-- The `fail' module provides a common routine for writing an error message 182206917Smarius and aborting. 183206917Smarius 184206917Smarius-- The `random' module generates random integer values. 185206917Smarius 186206917Smarius-- The `writeHex' module defines routines for writing the various types in 187206917Smarius the hexadecimal form used by TestFloat. 188206917Smarius 189206917Smarius-- The `testCases' module generates test cases for the various types. 190206917Smarius 191206917Smarius-- The `testLoops' module contains various routines for exercising two 192206917Smarius implementations of a function and reporting any differences observed. 193206917Smarius 194206917Smarius-- The `slowfloat' module provides the simple floating-point implementation 195206917Smarius used by `testsoftfloat' for comparing against SoftFloat. The heart 196206917Smarius of `slowfloat' is found in either `slowfloat-32' or `slowfloat-64', 197206917Smarius depending on whether the `BITS64' macro is defined. 198206917Smarius 199206917Smarius-- The `systfloat' module gives a SoftFloat-like interface to the machine's 200206917Smarius floating-point. 201206917Smarius 202206917Smarius-- The `testFunction' module implements `testfloat's main loop for testing a 203206917Smarius function for all of the relevant rounding modes and rounding precisions. 204206917Smarius (The `testsoftfloat' program contains its own version of this code.) 205206917Smarius 206206917Smarius-- The `testfloat' and `testsoftfloat' modules are the main modules for the 207206917Smarius `testfloat' and `testsoftfloat' programs. 208206917Smarius 209206917SmariusExcept possibly for `systfloat', these modules should not need to be 210206917Smariusmodified. 211206917Smarius 212206917SmariusThe `systfloat' module uses the floating-point operations of the C language 213206917Smariusto access a machine's floating-point. Unfortunately, some IEC/IEEE 214206917Smariusfloating-point operations are not accessible within ISO/ANSI C. The 215206917Smariusfollowing machine functions cannot be tested unless an alternate `systfloat' 216206917Smariusmodule is provided: 217206917Smarius 218206917Smarius <float>_to_int32 (rounded according to rounding mode) 219206917Smarius <float>_to_int64 (rounded according to rounding mode) 220206917Smarius <float>_round_to_int 221206917Smarius <float>_rem 222206917Smarius <float>_sqrt, except float64_sqrt 223206917Smarius <float>_eq_signaling 224206917Smarius <float>_le_quiet 225206917Smarius <float>_lt_quiet 226206917Smarius 227206917SmariusThe `-list' option to `testfloat' will show the operations the program is 228206917Smariusprepared to test. The section _Target-Specific_Floating-Point_Subroutines_ 229206917Smariuslater in this document explains how to create a target-specific `systfloat' 230206917Smariusmodule to change the set of testable functions. 231206917Smarius 232206917Smarius 233206917Smarius------------------------------------------------------------------------------- 234206917SmariusTarget-Specific Modules 235206917Smarius 236206917SmariusNo target-specific modules are needed for `testsoftfloat'. 237206917Smarius 238206917SmariusThe `testfloat' program uses two target-specific modules: 239206917Smarius 240206917Smarius-- The `systmodes' module defines functions for setting the modes 241206917Smarius controlling the system's floating-point, including the rounding mode and 242206917Smarius the rounding precision for extended double precision. 243206917Smarius 244206917Smarius-- The `systflags' module provides a function for clearing and examining the 245206917Smarius system's floating-point exception flags. 246206917Smarius 247206917SmariusThese modules must be supplied for each target. They can be implemented in 248206917Smariusany way desired, so long as all is reflected in the target's makefile. For 249206917Smariusthe targets that come with the distributed source, each of these modules is 250206917Smariusimplemented as a single assembly language or C language source file. 251206917Smarius 252206917Smarius 253206917Smarius------------------------------------------------------------------------------- 254206917SmariusTarget-Specific Header Files 255206917Smarius 256206917SmariusThe purpose of the two target-specific header files is detailed below. 257206917SmariusIn the following, the `*' symbol is used in place of the name of a specific 258206917Smariustarget, such as `386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some 259206917Smariusother text as explained below. 260206917Smarius 261206917Smarius- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 262206917Smariusprocessors/*.h 263206917Smarius 264206917SmariusThe target-specific `processors' header file defines integer types 265206917Smariusof various sizes, and also defines certain C preprocessor macros that 266206917Smariuscharacterize the target. The two examples supplied are `386-gcc.h' and 267206917Smarius`SPARC-gcc.h'. The naming convention used for processor header files is 268206917Smarius`<processor>-<compiler>.h'. The `processors' header file used to compile 269206917SmariusTestFloat should be the same as that used to compile SoftFloat. 270206917Smarius 271206917SmariusIf 64-bit integers are supported by the compiler, the macro name `BITS64' 272206917Smariusshould be defined here along with the corresponding 64-bit integer 273206917Smariustypes. In addition, the function-like macro `LIT64' must be defined for 274206917Smariusconstructing 64-bit integer literals (constants). The `LIT64' macro is used 275206917Smariusconsistently in the TestFloat code to annotate 64-bit literals. 276206917Smarius 277206917SmariusIf an inlining attribute (such as an `inline' keyword) is provided by the 278206917Smariuscompiler, the macro `INLINE' should be defined to the appropriate keyword. 279206917SmariusIf not, `INLINE' can be set to the keyword `static'. The `INLINE' macro 280206917Smariusappears in the TestFloat source code before every function that should be 281206917Smariusinlined by the compiler. 282206917Smarius 283206917SmariusFor maximum flexibility, the TestFloat source files do not include the 284206917Smarius`processors' header file directly; rather, this file is included by the 285206917Smariustarget-specific `milieu.h' header, and `milieu.h' is included by the source 286206917Smariusfiles. 287206917Smarius 288206917Smarius- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 289206917Smariustestfloat/*/milieu.h 290206917Smarius 291206917SmariusThe `milieu.h' header file provides declarations that are needed to 292206917Smariuscompile TestFloat. In particular, it is through this header file that 293206917Smariusthe appropriate `processors' header is included to characterize the target 294206917Smariusprocessor. In addition, deviations from ISO/ANSI C by the compiler (such as 295206917Smariusnames not properly declared in system header files) are corrected in this 296206917Smariusheader if possible. 297206917Smarius 298206917SmariusIf the preprocessor macro `BITS64' is defined in the `processors' header 299206917Smariusfile but only the 32-bit version of SoftFloat is actually used, the `BITS64' 300206917Smariusmacro should be undefined here after the `processors' header has defined it. 301206917Smarius 302206917SmariusIf the C compiler implements the `long double' floating-point type of C 303206917Smariusas extended double precision, then `LONG_DOUBLE_IS_FLOATX80' should be 304206917Smariusdefined here. Alternatively, if the C `long double' type is implemented as 305206917Smariusquadruple precision, `LONG_DOUBLE_IS_FLOAT128' should be defined. At most 306206917Smariusone of these macros should be defined. A C compiler is allowed to implement 307206917Smarius`long double' the same as `double', in which case neither of these macros 308206917Smariusshould be defined. 309206917Smarius 310206917Smarius- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 311206917Smarius 312206917Smarius 313206917Smarius------------------------------------------------------------------------------- 314206917SmariusTarget-Specific Floating-Point Subroutines 315206917Smarius 316206917SmariusThis section applies only to `testfloat' and not to `testsoftfloat'. 317206917Smarius 318206917SmariusBy default, TestFloat tests a machine's floating-point by testing the 319206917Smariusfloating-point operations of the C language. Unfortunately, some IEC/IEEE 320206917Smariusfloating-point operations are not defined within ISO/ANSI C. If a machine 321206917Smariusimplements such ``non-C'' operations, target-specific subroutines for 322206917Smariusthe operations can be supplied to allow TestFloat to test these machine 323206917Smariusfeatures. Typically, such subroutines will need to be written in assembly 324206917Smariuslanguage, although equivalent functions can sometimes be found among the 325206917Smariussystem's software libraries. 326206917Smarius 327206917SmariusThe following machine functions cannot be tested by TestFloat unless target- 328206917Smariusspecific subroutines are supplied for them: 329206917Smarius 330206917Smarius <float>_to_int32 (rounded according to rounding mode) 331206917Smarius <float>_to_int64 (rounded according to rounding mode) 332206917Smarius <float>_round_to_int 333206917Smarius <float>_rem 334206917Smarius <float>_sqrt, except float64_sqrt 335206917Smarius <float>_eq_signaling 336206917Smarius <float>_le_quiet 337206917Smarius <float>_lt_quiet 338206917Smarius 339206917SmariusIn addition to these, none of the `floatx80' functions can be tested by 340206917Smariusdefault if the C `long double' type is something other than extended double 341206917Smariusprecision; and likewise, none of the `float128' functions can be tested by 342206917Smariusdefault if `long double' is not quadruple precision. Since `long double' 343206917Smariuscannot be both extended double precision and quadruple precision at the 344206917Smariussame time, at least one of these types cannot be tested by TestFloat without 345206917Smariusappropriate subroutines being supplied for that type. (On the other hand, 346206917Smariusfew systems implement _both_ extended double-precision and quadruple- 347206917Smariusprecision floating-point; and unless a system does implement both, it does 348206917Smariusnot need both tested.) 349206917Smarius 350206917SmariusNote that the `-list' option to `testfloat' will show the operations 351206917SmariusTestFloat is prepared to test. 352206917Smarius 353206917SmariusTestFloat's `systfloat' module supplies the system version of the functions 354206917Smariusto be tested. The names of the `systfloat' subroutines are the same as the 355206917Smariusfunction names used as arguments to the `testfloat' command but with `syst_' 356206917Smariusprefixed--thus, for example, `syst_float32_add' and `syst_int32_to_float32'. 357206917SmariusThe default `systfloat' module maps these system functions to the standard 358206917SmariusC operations; so `syst_float32_add', for example, is implemented using the 359206917SmariusC `+' operation for the single-precision `float' type. For each system 360206917Smariusfunction supplied by `systfloat', a corresponding `SYST_<function>' 361206917Smariuspreprocessor macro is defined in `systfloat.h' to indicate that the function 362206917Smariusexists to be tested (e.g., `SYST_FLOAT32_ADD'). The `systfloat.h' header 363206917Smariusfile also declares function prototypes for the `systfloat' functions. 364206917Smarius 365206917Smarius(The `systfloat.h' file that comes with the TestFloat package declares 366206917Smariusprototypes for all of the possible `systfloat' functions, whether defined in 367206917Smarius`systfloat' or not. There is no penalty for declaring a function prototype 368206917Smariusthat is never used.) 369206917Smarius 370206917SmariusA target-specific version of the `systfloat' module can easily be created to 371206917Smariusreplace the generic one. This in fact has been done for the example targets 372206917Smarius`386-Win32-gcc' and `SPARC-Solaris-gcc'. For each target, an assembly 373206917Smariuslanguage `systfloat.S' has been created in the target directory along with 374206917Smariusa corresponding `systfloat.h' header file defining the `SYST_<function>' 375206917Smariusmacros for the functions implemented. The makefiles of the targets have 376206917Smariusbeen edited to use these target-specific versions of `systfloat' rather than 377206917Smariusthe generic one. 378206917Smarius 379206917SmariusThe `systfloat' modules of the example targets have been written entirely 380206917Smariusin assembly language in order to bypass any peculiarities of the C compiler. 381206917SmariusAlthough this is probably a good idea, it is certainly not required. 382206917Smarius 383206917Smarius 384206917Smarius------------------------------------------------------------------------------- 385206917SmariusSteps to Creating the TestFloat Executables 386206917Smarius 387206917SmariusPorting and/or compiling TestFloat involves the following steps: 388206917Smarius 389206917Smarius1. Port SoftFloat and create a SoftFloat binary. (Refer to the 390206917Smarius documentation accompanying SoftFloat.) 391206917Smarius 392206917Smarius2. If one does not already exist, create an appropriate target-specific 393206917Smarius subdirectory under `testfloat' by copying the given `templates' 394206917Smarius directory. The remaining steps occur within the target-specific 395206917Smarius subdirectory. 396206917Smarius 397206917Smarius3. Edit the files `milieu.h' and `Makefile' to reflect the current 398206917Smarius environment. 399206917Smarius 400206917Smarius4. Make `testsoftfloat' by executing `make testsoftfloat' (or `make 401206917Smarius testsoftfloat.exe', or whatever the `testsoftfloat' executable is 402206917Smarius called). Verify that SoftFloat is working correctly by testing it with 403206917Smarius `testsoftfloat'. 404206917Smarius 405206917SmariusIf you only wanted `testsoftfloat', you are done. The steps for `testfloat' 406206917Smariuscontinue: 407206917Smarius 408206917Smarius5. In the target-specific subdirectory, implement the `systmodes' and 409206917Smarius `systflags' modules. (The `syst_float_set_rounding_precision' function 410206917Smarius need not do anything if the system does not support extended double 411206917Smarius precision.) 412206917Smarius 413206917Smarius6. If the target machine supports standard floating-point functions that are 414206917Smarius not accessible within ISO/ANSI C, or if the C compiler cannot be trusted 415206917Smarius to use the machine's floating-point directly, create a target-specific 416206917Smarius `systfloat' module. 417206917Smarius 418206917Smarius7. In the target-specific subdirectory, execute `make'. 419206917Smarius 420206917Smarius 421206917Smarius------------------------------------------------------------------------------- 422206917SmariusImproving the Random Number Generator 423206917Smarius 424206917SmariusIf you are serious about using TestFloat for testing floating-point, you 425206917Smariusshould consider replacing the supplied `random.c' with a better target- 426206917Smariusspecific one. The standard C `rand' function is rather poor on some 427206917Smariussystems, and consequently `random.c' has been written to assume very little 428206917Smariusabout the quality of `rand'. As a result, the `rand' function is called 429206917Smariusmore frequently than it might need to be, shortening the time before 430206917Smariusthe random number generator repeats, and possibly wasting time as well. 431206917SmariusIf `rand' is better on your system, or if another better random number 432206917Smariusgenerator is available (such as `rand48' on most Unix systems), TestFloat 433206917Smariuscan be improved by overriding the given `random.c' with a target-specific 434206917Smariusone. 435206917Smarius 436206917Smarius 437206917Smarius------------------------------------------------------------------------------- 438206917SmariusContact Information 439206917Smarius 440206917SmariusAt the time of this writing, the most up-to-date information about 441206917SmariusTestFloat and the latest release can be found at the Web page `http:// 442206917SmariusHTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'. 443206917Smarius 444206917Smarius 445