1 2TestFloat Release 2a Source Documentation 3 4John R. Hauser 51998 December 16 6 7 8------------------------------------------------------------------------------- 9Introduction 10 11TestFloat is a program for testing that a floating-point implementation 12conforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. 13All standard operations supported by the system can be tested, except for 14conversions to and from decimal. Any of the following machine formats can 15be tested: single precision, double precision, extended double precision, 16and/or quadruple precision. Testing extended double-precision or quadruple- 17precision formats requires a C compiler that supports 64-bit integer 18arithmetic. 19 20This document gives information needed for compiling and/or porting 21TestFloat. 22 23The source code for TestFloat is intended to be relatively machine- 24independent. TestFloat is written in C, and should be compilable using 25any ISO/ANSI C compiler. At the time of this writing, the program has 26been successfully compiled using the GNU C Compiler (`gcc') for several 27platforms. Because ISO/ANSI C does not provide access to some features 28of IEC/IEEE floating-point such as the exception flags, porting TestFloat 29unfortunately involves some machine-dependent coding. 30 31TestFloat depends on SoftFloat, which is a software implementation of 32floating-point that conforms to the IEC/IEEE Standard. SoftFloat is not 33included with the TestFloat sources. It can be obtained from the Web 34page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. 35 36In addition to a program for testing a machine's floating-point, the 37TestFloat package includes a variant for testing SoftFloat called 38`testsoftfloat'. The sources for both programs are intermixed, and both are 39described here. 40 41The first release of TestFloat (Release 1) was called _FloatTest_. The old 42name has been obsolete for some time. 43 44 45------------------------------------------------------------------------------- 46Limitations 47 48TestFloat as written requires an ISO/ANSI-style C compiler. No attempt has 49been made to accomodate compilers that are not ISO-conformant. Older ``K&R- 50style'' compilers are not adequate for compiling TestFloat. All testing I 51have done so far has been with the GNU C Compiler. Compilation with other 52compilers should be possible but has not been tested. 53 54The TestFloat sources assume that source code file names can be longer than 558 characters. In order to compile under an MS-DOS-style system, many of the 56source files will need to be renamed, and the source and makefiles edited 57appropriately. Once compiled, the TestFloat program does not depend on the 58existence of long file names. 59 60The underlying machine is assumed to be binary with a word size that is a 61power of 2. Bytes are 8 bits. Testing of extended double-precision and 62quadruple-precision formats depends on the C compiler implementing a 64-bit 63integer type. If the largest integer type supported by the C compiler is 6432 bits, only single- and double-precision operations can be tested. 65 66 67------------------------------------------------------------------------------- 68Contents 69 70 Introduction 71 Limitations 72 Contents 73 Legal Notice 74 TestFloat Source Directory Structure 75 Target-Independent Modules 76 Target-Specific Modules 77 Target-Specific Header Files 78 processors/*.h 79 testfloat/*/milieu.h 80 Target-Specific Floating-Point Subroutines 81 Steps to Creating the TestFloat Executables 82 Improving the Random Number Generator 83 Contact Information 84 85 86 87------------------------------------------------------------------------------- 88Legal Notice 89 90TestFloat was written by John R. Hauser. 91 92THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 93has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 94TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 95PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 96AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 97 98 99------------------------------------------------------------------------------- 100TestFloat Source Directory Structure 101 102Because TestFloat is targeted to multiple platforms, its source code 103is slightly scattered between target-specific and target-independent 104directories and files. The directory structure is as follows: 105 106 processors 107 testfloat 108 templates 109 386-Win32-gcc 110 SPARC-Solaris-gcc 111 112The two topmost directories and their contents are: 113 114 testfloat - Most of the source code needed for TestFloat. 115 processors - Target-specific header files that are not specific to 116 TestFloat. 117 118Within the `testfloat' directory are subdirectories for each of the 119targeted platforms. The TestFloat source code is distributed with targets 120`386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already 121prepared. These can be used as examples for porting to new targets. Source 122files that are not within these target-specific subdirectories are intended 123to be target-independent. 124 125The naming convention used for the target-specific directories is 126`<processor>-<executable-type>-<compiler>'. The names of the supplied 127target directories should be interpreted as follows: 128 129 <processor>: 130 386 - Intel 386-compatible processor. 131 SPARC - SPARC processor (as used by Sun machines). 132 <executable-type>: 133 Win32 - Microsoft Win32 executable. 134 Solaris - Sun Solaris executable. 135 <compiler>: 136 gcc - GNU C Compiler. 137 138You do not need to maintain this convention if you do not want to. 139 140Alongside the supplied target-specific directories there is a `templates' 141directory containing a set of ``generic'' target-specific source files. 142A new target directory can be created by copying the `templates' directory 143and editing the files inside. (Complete instructions for porting TestFloat 144to a new target are in the section _Steps_to_Creating_the_TestFloat_ 145_Executables_.) Note that the `templates' directory will not work as a 146target directory without some editing. To avoid confusion, it would be wise 147to refrain from editing the files inside `templates' directly. 148 149In addition to the distributed sources, TestFloat depends on the existence 150of an appropriately-compiled SoftFloat binary and the corresponding header 151file `softfloat.h'. SoftFloat is not included with the TestFloat sources. 152It can be obtained from the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/ 153arithmetic/SoftFloat.html'. 154 155As distributed, the makefiles for TestFloat assume the existence of three 156sibling directories: 157 158 processors 159 softfloat 160 testfloat 161 162Only 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