testfloat-source.txt revision 206917
159191Skris 259191SkrisTestFloat Release 2a Source Documentation 359191Skris 459191SkrisJohn R. Hauser 568651Skris1998 December 16 659191Skris 759191Skris 859191Skris------------------------------------------------------------------------------- 959191SkrisIntroduction 1068651Skris 1159191SkrisTestFloat is a program for testing that a floating-point implementation 1259191Skrisconforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. 1368651SkrisAll standard operations supported by the system can be tested, except for 1468651Skrisconversions to and from decimal. Any of the following machine formats can 1568651Skrisbe tested: single precision, double precision, extended double precision, 1668651Skrisand/or quadruple precision. Testing extended double-precision or quadruple- 17238405Sjkimprecision formats requires a C compiler that supports 64-bit integer 18160814Ssimonarithmetic. 1968651Skris 2068651SkrisThis document gives information needed for compiling and/or porting 2168651SkrisTestFloat. 22194206Ssimon 2359191SkrisThe source code for TestFloat is intended to be relatively machine- 2459191Skrisindependent. TestFloat is written in C, and should be compilable using 2568651Skrisany ISO/ANSI C compiler. At the time of this writing, the program has 2659191Skrisbeen successfully compiled using the GNU C Compiler (`gcc') for several 2759191Skrisplatforms. Because ISO/ANSI C does not provide access to some features 2859191Skrisof IEC/IEEE floating-point such as the exception flags, porting TestFloat 2959191Skrisunfortunately involves some machine-dependent coding. 3059191Skris 3159191SkrisTestFloat depends on SoftFloat, which is a software implementation of 3268651Skrisfloating-point that conforms to the IEC/IEEE Standard. SoftFloat is not 3368651Skrisincluded with the TestFloat sources. It can be obtained from the Web 3459191Skrispage `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. 3559191Skris 3659191SkrisIn addition to a program for testing a machine's floating-point, the 3759191SkrisTestFloat package includes a variant for testing SoftFloat called 3859191Skris`testsoftfloat'. The sources for both programs are intermixed, and both are 3959191Skrisdescribed here. 4059191Skris 4168651SkrisThe first release of TestFloat (Release 1) was called _FloatTest_. The old 4268651Skrisname has been obsolete for some time. 4359191Skris 4459191Skris 4559191Skris------------------------------------------------------------------------------- 4659191SkrisLimitations 4759191Skris 4868651SkrisTestFloat as written requires an ISO/ANSI-style C compiler. No attempt has 4968651Skrisbeen made to accomodate compilers that are not ISO-conformant. Older ``K&R- 5068651Skrisstyle'' compilers are not adequate for compiling TestFloat. All testing I 5168651Skrishave done so far has been with the GNU C Compiler. Compilation with other 5268651Skriscompilers should be possible but has not been tested. 5368651Skris 5468651SkrisThe TestFloat sources assume that source code file names can be longer than 5568651Skris8 characters. In order to compile under an MS-DOS-style system, many of the 5668651Skrissource files will need to be renamed, and the source and makefiles edited 5768651Skrisappropriately. Once compiled, the TestFloat program does not depend on the 5868651Skrisexistence of long file names. 5968651Skris 6068651SkrisThe underlying machine is assumed to be binary with a word size that is a 6168651Skrispower of 2. Bytes are 8 bits. Testing of extended double-precision and 6268651Skrisquadruple-precision formats depends on the C compiler implementing a 64-bit 6368651Skrisinteger type. If the largest integer type supported by the C compiler is 6468651Skris32 bits, only single- and double-precision operations can be tested. 65238405Sjkim 66238405Sjkim 67238405Sjkim------------------------------------------------------------------------------- 68238405SjkimContents 69238405Sjkim 70238405Sjkim Introduction 71238405Sjkim Limitations 72238405Sjkim Contents 73238405Sjkim Legal Notice 74238405Sjkim TestFloat Source Directory Structure 75238405Sjkim Target-Independent Modules 76238405Sjkim Target-Specific Modules 77238405Sjkim Target-Specific Header Files 78238405Sjkim processors/*.h 79238405Sjkim testfloat/*/milieu.h 80238405Sjkim Target-Specific Floating-Point Subroutines 81238405Sjkim Steps to Creating the TestFloat Executables 82160814Ssimon Improving the Random Number Generator 83160814Ssimon Contact Information 84160814Ssimon 85160814Ssimon 86160814Ssimon 8768651Skris------------------------------------------------------------------------------- 8868651SkrisLegal Notice 89237658Sjkim 9068651SkrisTestFloat was written by John R. Hauser. 9168651Skris 9268651SkrisTHIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 9368651Skrishas been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 94246771SjkimTIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 9568651SkrisPERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 9668651SkrisAND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 9768651Skris 9868651Skris 9968651Skris------------------------------------------------------------------------------- 100194206SsimonTestFloat Source Directory Structure 101194206Ssimon 102194206SsimonBecause TestFloat is targeted to multiple platforms, its source code 103194206Ssimonis slightly scattered between target-specific and target-independent 104238405Sjkimdirectories and files. The directory structure is as follows: 105238405Sjkim 106238405Sjkim processors 107238405Sjkim testfloat 108238405Sjkim templates 109238405Sjkim 386-Win32-gcc 110238405Sjkim SPARC-Solaris-gcc 111238405Sjkim 112238405SjkimThe two topmost directories and their contents are: 113238405Sjkim 114238405Sjkim testfloat - Most of the source code needed for TestFloat. 115238405Sjkim processors - Target-specific header files that are not specific to 116238405Sjkim TestFloat. 117238405Sjkim 118238405SjkimWithin the `testfloat' directory are subdirectories for each of the 119238405Sjkimtargeted platforms. The TestFloat source code is distributed with targets 120238405Sjkim`386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already 121238405Sjkimprepared. These can be used as examples for porting to new targets. Source 122238405Sjkimfiles that are not within these target-specific subdirectories are intended 123238405Sjkimto be target-independent. 124238405Sjkim 125238405SjkimThe naming convention used for the target-specific directories is 126238405Sjkim`<processor>-<executable-type>-<compiler>'. The names of the supplied 127238405Sjkimtarget directories should be interpreted as follows: 128238405Sjkim 129238405Sjkim <processor>: 130238405Sjkim 386 - Intel 386-compatible processor. 131238405Sjkim SPARC - SPARC processor (as used by Sun machines). 132238405Sjkim <executable-type>: 13368651Skris Win32 - Microsoft Win32 executable. 13468651Skris Solaris - Sun Solaris executable. 13568651Skris <compiler>: 13668651Skris gcc - GNU C Compiler. 13768651Skris 13868651SkrisYou do not need to maintain this convention if you do not want to. 13968651Skris 14068651SkrisAlongside the supplied target-specific directories there is a `templates' 14159191Skrisdirectory containing a set of ``generic'' target-specific source files. 14259191SkrisA new target directory can be created by copying the `templates' directory 14359191Skrisand editing the files inside. (Complete instructions for porting TestFloat 14459191Skristo a new target are in the section _Steps_to_Creating_the_TestFloat_ 14559191Skris_Executables_.) Note that the `templates' directory will not work as a 14659191Skristarget directory without some editing. To avoid confusion, it would be wise 14759191Skristo refrain from editing the files inside `templates' directly. 14859191Skris 14959191SkrisIn addition to the distributed sources, TestFloat depends on the existence 15059191Skrisof an appropriately-compiled SoftFloat binary and the corresponding header 15159191Skrisfile `softfloat.h'. SoftFloat is not included with the TestFloat sources. 15259191SkrisIt can be obtained from the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/ 15368651Skrisarithmetic/SoftFloat.html'. 15468651Skris 15568651SkrisAs distributed, the makefiles for TestFloat assume the existence of three 15668651Skrissibling directories: 15768651Skris 15868651Skris processors 15968651Skris softfloat 16068651Skris testfloat 16168651Skris 16259191SkrisOnly the `processors' and `testfloat' directories are included in the 163TestFloat package. The `softfloat' directory is assumed to contain a 164target-specific subdirectory within which the SoftFloat header file and 165compiled binary can be found. (See the source documentation accompanying 166SoftFloat.) The `processors' directory distributed with TestFloat is 167intended to be identical to that included with the SoftFloat source. 168 169These are the defaults, but other organizations of the sources are possible. 170The TestFloat makefiles and `milieu.h' files (see below) are easily edited 171to accomodate other arrangements. 172 173 174------------------------------------------------------------------------------- 175Target-Independent Modules 176 177The TestFloat program is composed of a number of modules, some target- 178specific and some target-independent. The target-independent modules are as 179follows: 180 181-- The `fail' module provides a common routine for writing an error message 182 and aborting. 183 184-- The `random' module generates random integer values. 185 186-- The `writeHex' module defines routines for writing the various types in 187 the hexadecimal form used by TestFloat. 188 189-- The `testCases' module generates test cases for the various types. 190 191-- The `testLoops' module contains various routines for exercising two 192 implementations of a function and reporting any differences observed. 193 194-- The `slowfloat' module provides the simple floating-point implementation 195 used by `testsoftfloat' for comparing against SoftFloat. The heart 196 of `slowfloat' is found in either `slowfloat-32' or `slowfloat-64', 197 depending on whether the `BITS64' macro is defined. 198 199-- The `systfloat' module gives a SoftFloat-like interface to the machine's 200 floating-point. 201 202-- The `testFunction' module implements `testfloat's main loop for testing a 203 function for all of the relevant rounding modes and rounding precisions. 204 (The `testsoftfloat' program contains its own version of this code.) 205 206-- The `testfloat' and `testsoftfloat' modules are the main modules for the 207 `testfloat' and `testsoftfloat' programs. 208 209Except possibly for `systfloat', these modules should not need to be 210modified. 211 212The `systfloat' module uses the floating-point operations of the C language 213to access a machine's floating-point. Unfortunately, some IEC/IEEE 214floating-point operations are not accessible within ISO/ANSI C. The 215following machine functions cannot be tested unless an alternate `systfloat' 216module is provided: 217 218 <float>_to_int32 (rounded according to rounding mode) 219 <float>_to_int64 (rounded according to rounding mode) 220 <float>_round_to_int 221 <float>_rem 222 <float>_sqrt, except float64_sqrt 223 <float>_eq_signaling 224 <float>_le_quiet 225 <float>_lt_quiet 226 227The `-list' option to `testfloat' will show the operations the program is 228prepared to test. The section _Target-Specific_Floating-Point_Subroutines_ 229later in this document explains how to create a target-specific `systfloat' 230module to change the set of testable functions. 231 232 233------------------------------------------------------------------------------- 234Target-Specific Modules 235 236No target-specific modules are needed for `testsoftfloat'. 237 238The `testfloat' program uses two target-specific modules: 239 240-- The `systmodes' module defines functions for setting the modes 241 controlling the system's floating-point, including the rounding mode and 242 the rounding precision for extended double precision. 243 244-- The `systflags' module provides a function for clearing and examining the 245 system's floating-point exception flags. 246 247These modules must be supplied for each target. They can be implemented in 248any way desired, so long as all is reflected in the target's makefile. For 249the targets that come with the distributed source, each of these modules is 250implemented as a single assembly language or C language source file. 251 252 253------------------------------------------------------------------------------- 254Target-Specific Header Files 255 256The purpose of the two target-specific header files is detailed below. 257In the following, the `*' symbol is used in place of the name of a specific 258target, such as `386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some 259other text as explained below. 260 261- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 262processors/*.h 263 264The target-specific `processors' header file defines integer types 265of various sizes, and also defines certain C preprocessor macros that 266characterize the target. The two examples supplied are `386-gcc.h' and 267`SPARC-gcc.h'. The naming convention used for processor header files is 268`<processor>-<compiler>.h'. The `processors' header file used to compile 269TestFloat should be the same as that used to compile SoftFloat. 270 271If 64-bit integers are supported by the compiler, the macro name `BITS64' 272should be defined here along with the corresponding 64-bit integer 273types. In addition, the function-like macro `LIT64' must be defined for 274constructing 64-bit integer literals (constants). The `LIT64' macro is used 275consistently in the TestFloat code to annotate 64-bit literals. 276 277If an inlining attribute (such as an `inline' keyword) is provided by the 278compiler, the macro `INLINE' should be defined to the appropriate keyword. 279If not, `INLINE' can be set to the keyword `static'. The `INLINE' macro 280appears in the TestFloat source code before every function that should be 281inlined by the compiler. 282 283For maximum flexibility, the TestFloat source files do not include the 284`processors' header file directly; rather, this file is included by the 285target-specific `milieu.h' header, and `milieu.h' is included by the source 286files. 287 288- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 289testfloat/*/milieu.h 290 291The `milieu.h' header file provides declarations that are needed to 292compile TestFloat. In particular, it is through this header file that 293the appropriate `processors' header is included to characterize the target 294processor. In addition, deviations from ISO/ANSI C by the compiler (such as 295names not properly declared in system header files) are corrected in this 296header if possible. 297 298If the preprocessor macro `BITS64' is defined in the `processors' header 299file but only the 32-bit version of SoftFloat is actually used, the `BITS64' 300macro should be undefined here after the `processors' header has defined it. 301 302If the C compiler implements the `long double' floating-point type of C 303as extended double precision, then `LONG_DOUBLE_IS_FLOATX80' should be 304defined here. Alternatively, if the C `long double' type is implemented as 305quadruple precision, `LONG_DOUBLE_IS_FLOAT128' should be defined. At most 306one of these macros should be defined. A C compiler is allowed to implement 307`long double' the same as `double', in which case neither of these macros 308should be defined. 309 310- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 311 312 313------------------------------------------------------------------------------- 314Target-Specific Floating-Point Subroutines 315 316This section applies only to `testfloat' and not to `testsoftfloat'. 317 318By default, TestFloat tests a machine's floating-point by testing the 319floating-point operations of the C language. Unfortunately, some IEC/IEEE 320floating-point operations are not defined within ISO/ANSI C. If a machine 321implements such ``non-C'' operations, target-specific subroutines for 322the operations can be supplied to allow TestFloat to test these machine 323features. Typically, such subroutines will need to be written in assembly 324language, although equivalent functions can sometimes be found among the 325system's software libraries. 326 327The following machine functions cannot be tested by TestFloat unless target- 328specific subroutines are supplied for them: 329 330 <float>_to_int32 (rounded according to rounding mode) 331 <float>_to_int64 (rounded according to rounding mode) 332 <float>_round_to_int 333 <float>_rem 334 <float>_sqrt, except float64_sqrt 335 <float>_eq_signaling 336 <float>_le_quiet 337 <float>_lt_quiet 338 339In addition to these, none of the `floatx80' functions can be tested by 340default if the C `long double' type is something other than extended double 341precision; and likewise, none of the `float128' functions can be tested by 342default if `long double' is not quadruple precision. Since `long double' 343cannot be both extended double precision and quadruple precision at the 344same time, at least one of these types cannot be tested by TestFloat without 345appropriate subroutines being supplied for that type. (On the other hand, 346few systems implement _both_ extended double-precision and quadruple- 347precision floating-point; and unless a system does implement both, it does 348not need both tested.) 349 350Note that the `-list' option to `testfloat' will show the operations 351TestFloat is prepared to test. 352 353TestFloat's `systfloat' module supplies the system version of the functions 354to be tested. The names of the `systfloat' subroutines are the same as the 355function names used as arguments to the `testfloat' command but with `syst_' 356prefixed--thus, for example, `syst_float32_add' and `syst_int32_to_float32'. 357The default `systfloat' module maps these system functions to the standard 358C operations; so `syst_float32_add', for example, is implemented using the 359C `+' operation for the single-precision `float' type. For each system 360function supplied by `systfloat', a corresponding `SYST_<function>' 361preprocessor macro is defined in `systfloat.h' to indicate that the function 362exists to be tested (e.g., `SYST_FLOAT32_ADD'). The `systfloat.h' header 363file also declares function prototypes for the `systfloat' functions. 364 365(The `systfloat.h' file that comes with the TestFloat package declares 366prototypes for all of the possible `systfloat' functions, whether defined in 367`systfloat' or not. There is no penalty for declaring a function prototype 368that is never used.) 369 370A target-specific version of the `systfloat' module can easily be created to 371replace the generic one. This in fact has been done for the example targets 372`386-Win32-gcc' and `SPARC-Solaris-gcc'. For each target, an assembly 373language `systfloat.S' has been created in the target directory along with 374a corresponding `systfloat.h' header file defining the `SYST_<function>' 375macros for the functions implemented. The makefiles of the targets have 376been edited to use these target-specific versions of `systfloat' rather than 377the generic one. 378 379The `systfloat' modules of the example targets have been written entirely 380in assembly language in order to bypass any peculiarities of the C compiler. 381Although this is probably a good idea, it is certainly not required. 382 383 384------------------------------------------------------------------------------- 385Steps to Creating the TestFloat Executables 386 387Porting and/or compiling TestFloat involves the following steps: 388 3891. Port SoftFloat and create a SoftFloat binary. (Refer to the 390 documentation accompanying SoftFloat.) 391 3922. If one does not already exist, create an appropriate target-specific 393 subdirectory under `testfloat' by copying the given `templates' 394 directory. The remaining steps occur within the target-specific 395 subdirectory. 396 3973. Edit the files `milieu.h' and `Makefile' to reflect the current 398 environment. 399 4004. Make `testsoftfloat' by executing `make testsoftfloat' (or `make 401 testsoftfloat.exe', or whatever the `testsoftfloat' executable is 402 called). Verify that SoftFloat is working correctly by testing it with 403 `testsoftfloat'. 404 405If you only wanted `testsoftfloat', you are done. The steps for `testfloat' 406continue: 407 4085. In the target-specific subdirectory, implement the `systmodes' and 409 `systflags' modules. (The `syst_float_set_rounding_precision' function 410 need not do anything if the system does not support extended double 411 precision.) 412 4136. If the target machine supports standard floating-point functions that are 414 not accessible within ISO/ANSI C, or if the C compiler cannot be trusted 415 to use the machine's floating-point directly, create a target-specific 416 `systfloat' module. 417 4187. In the target-specific subdirectory, execute `make'. 419 420 421------------------------------------------------------------------------------- 422Improving the Random Number Generator 423 424If you are serious about using TestFloat for testing floating-point, you 425should consider replacing the supplied `random.c' with a better target- 426specific one. The standard C `rand' function is rather poor on some 427systems, and consequently `random.c' has been written to assume very little 428about the quality of `rand'. As a result, the `rand' function is called 429more frequently than it might need to be, shortening the time before 430the random number generator repeats, and possibly wasting time as well. 431If `rand' is better on your system, or if another better random number 432generator is available (such as `rand48' on most Unix systems), TestFloat 433can be improved by overriding the given `random.c' with a target-specific 434one. 435 436 437------------------------------------------------------------------------------- 438Contact Information 439 440At the time of this writing, the most up-to-date information about 441TestFloat and the latest release can be found at the Web page `http:// 442HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'. 443 444 445