1 2 TestFloat Release 2a Source Documentation 3 4 John R. Hauser 5 1998 December 16 6 7 8 ------------------------------------------------------------------------------- 9 Introduction 10 11 TestFloat is a program for testing that a floating-point implementation 12 conforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. 13 All standard operations supported by the system can be tested, except for 14 conversions to and from decimal. Any of the following machine formats can 15 be tested: single precision, double precision, extended double precision, 16 and/or quadruple precision. Testing extended double-precision or quadruple- 17 precision formats requires a C compiler that supports 64-bit integer 18 arithmetic. 19 20 This document gives information needed for compiling and/or porting 21 TestFloat. 22 23 The source code for TestFloat is intended to be relatively machine- 24 independent. TestFloat is written in C, and should be compilable using 25 any ISO/ANSI C compiler. At the time of this writing, the program has 26 been successfully compiled using the GNU C Compiler (`gcc') for several 27 platforms. Because ISO/ANSI C does not provide access to some features 28 of IEC/IEEE floating-point such as the exception flags, porting TestFloat 29 unfortunately involves some machine-dependent coding. 30 31 TestFloat depends on SoftFloat, which is a software implementation of 32 floating-point that conforms to the IEC/IEEE Standard. SoftFloat is not 33 included with the TestFloat sources. It can be obtained from the Web 34 page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. 35 36 In addition to a program for testing a machine's floating-point, the 37 TestFloat package includes a variant for testing SoftFloat called 38 `testsoftfloat'. The sources for both programs are intermixed, and both are 39 described here. 40 41 The first release of TestFloat (Release 1) was called _FloatTest_. The old 42 name has been obsolete for some time. 43 44 45 ------------------------------------------------------------------------------- 46 Limitations 47 48 TestFloat as written requires an ISO/ANSI-style C compiler. No attempt has 49 been made to accommodate compilers that are not ISO-conformant. Older ``K&R- 50 style'' compilers are not adequate for compiling TestFloat. All testing I 51 have done so far has been with the GNU C Compiler. Compilation with other 52 compilers should be possible but has not been tested. 53 54 The TestFloat sources assume that source code file names can be longer than 55 8 characters. In order to compile under an MS-DOS-style system, many of the 56 source files will need to be renamed, and the source and makefiles edited 57 appropriately. Once compiled, the TestFloat program does not depend on the 58 existence of long file names. 59 60 The underlying machine is assumed to be binary with a word size that is a 61 power of 2. Bytes are 8 bits. Testing of extended double-precision and 62 quadruple-precision formats depends on the C compiler implementing a 64-bit 63 integer type. If the largest integer type supported by the C compiler is 64 32 bits, only single- and double-precision operations can be tested. 65 66 67 ------------------------------------------------------------------------------- 68 Contents 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 ------------------------------------------------------------------------------- 88 Legal Notice 89 90 TestFloat was written by John R. Hauser. 91 92 THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 93 has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 94 TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 95 PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 96 AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 97 98 99 ------------------------------------------------------------------------------- 100 TestFloat Source Directory Structure 101 102 Because TestFloat is targeted to multiple platforms, its source code 103 is slightly scattered between target-specific and target-independent 104 directories and files. The directory structure is as follows: 105 106 processors 107 testfloat 108 templates 109 386-Win32-gcc 110 SPARC-Solaris-gcc 111 112 The 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 118 Within the `testfloat' directory are subdirectories for each of the 119 targeted platforms. The TestFloat source code is distributed with targets 120 `386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already 121 prepared. These can be used as examples for porting to new targets. Source 122 files that are not within these target-specific subdirectories are intended 123 to be target-independent. 124 125 The naming convention used for the target-specific directories is 126 `<processor>-<executable-type>-<compiler>'. The names of the supplied 127 target 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 138 You do not need to maintain this convention if you do not want to. 139 140 Alongside the supplied target-specific directories there is a `templates' 141 directory containing a set of ``generic'' target-specific source files. 142 A new target directory can be created by copying the `templates' directory 143 and editing the files inside. (Complete instructions for porting TestFloat 144 to a new target are in the section _Steps_to_Creating_the_TestFloat_ 145 _Executables_.) Note that the `templates' directory will not work as a 146 target directory without some editing. To avoid confusion, it would be wise 147 to refrain from editing the files inside `templates' directly. 148 149 In addition to the distributed sources, TestFloat depends on the existence 150 of an appropriately-compiled SoftFloat binary and the corresponding header 151 file `softfloat.h'. SoftFloat is not included with the TestFloat sources. 152 It can be obtained from the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/ 153 arithmetic/SoftFloat.html'. 154 155 As distributed, the makefiles for TestFloat assume the existence of three 156 sibling directories: 157 158 processors 159 softfloat 160 testfloat 161 162 Only the `processors' and `testfloat' directories are included in the 163 TestFloat package. The `softfloat' directory is assumed to contain a 164 target-specific subdirectory within which the SoftFloat header file and 165 compiled binary can be found. (See the source documentation accompanying 166 SoftFloat.) The `processors' directory distributed with TestFloat is 167 intended to be identical to that included with the SoftFloat source. 168 169 These are the defaults, but other organizations of the sources are possible. 170 The TestFloat makefiles and `milieu.h' files (see below) are easily edited 171 to accommodate other arrangements. 172 173 174 ------------------------------------------------------------------------------- 175 Target-Independent Modules 176 177 The TestFloat program is composed of a number of modules, some target- 178 specific and some target-independent. The target-independent modules are as 179 follows: 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 209 Except possibly for `systfloat', these modules should not need to be 210 modified. 211 212 The `systfloat' module uses the floating-point operations of the C language 213 to access a machine's floating-point. Unfortunately, some IEC/IEEE 214 floating-point operations are not accessible within ISO/ANSI C. The 215 following machine functions cannot be tested unless an alternate `systfloat' 216 module 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 227 The `-list' option to `testfloat' will show the operations the program is 228 prepared to test. The section _Target-Specific_Floating-Point_Subroutines_ 229 later in this document explains how to create a target-specific `systfloat' 230 module to change the set of testable functions. 231 232 233 ------------------------------------------------------------------------------- 234 Target-Specific Modules 235 236 No target-specific modules are needed for `testsoftfloat'. 237 238 The `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 247 These modules must be supplied for each target. They can be implemented in 248 any way desired, so long as all is reflected in the target's makefile. For 249 the targets that come with the distributed source, each of these modules is 250 implemented as a single assembly language or C language source file. 251 252 253 ------------------------------------------------------------------------------- 254 Target-Specific Header Files 255 256 The purpose of the two target-specific header files is detailed below. 257 In the following, the `*' symbol is used in place of the name of a specific 258 target, such as `386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some 259 other text as explained below. 260 261 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 262 processors/*.h 263 264 The target-specific `processors' header file defines integer types 265 of various sizes, and also defines certain C preprocessor macros that 266 characterize 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 269 TestFloat should be the same as that used to compile SoftFloat. 270 271 If 64-bit integers are supported by the compiler, the macro name `BITS64' 272 should be defined here along with the corresponding 64-bit integer 273 types. In addition, the function-like macro `LIT64' must be defined for 274 constructing 64-bit integer literals (constants). The `LIT64' macro is used 275 consistently in the TestFloat code to annotate 64-bit literals. 276 277 If an inlining attribute (such as an `inline' keyword) is provided by the 278 compiler, the macro `INLINE' should be defined to the appropriate keyword. 279 If not, `INLINE' can be set to the keyword `static'. The `INLINE' macro 280 appears in the TestFloat source code before every function that should be 281 inlined by the compiler. 282 283 For maximum flexibility, the TestFloat source files do not include the 284 `processors' header file directly; rather, this file is included by the 285 target-specific `milieu.h' header, and `milieu.h' is included by the source 286 files. 287 288 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 289 testfloat/*/milieu.h 290 291 The `milieu.h' header file provides declarations that are needed to 292 compile TestFloat. In particular, it is through this header file that 293 the appropriate `processors' header is included to characterize the target 294 processor. In addition, deviations from ISO/ANSI C by the compiler (such as 295 names not properly declared in system header files) are corrected in this 296 header if possible. 297 298 If the preprocessor macro `BITS64' is defined in the `processors' header 299 file but only the 32-bit version of SoftFloat is actually used, the `BITS64' 300 macro should be undefined here after the `processors' header has defined it. 301 302 If the C compiler implements the `long double' floating-point type of C 303 as extended double precision, then `LONG_DOUBLE_IS_FLOATX80' should be 304 defined here. Alternatively, if the C `long double' type is implemented as 305 quadruple precision, `LONG_DOUBLE_IS_FLOAT128' should be defined. At most 306 one 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 308 should be defined. 309 310 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 311 312 313 ------------------------------------------------------------------------------- 314 Target-Specific Floating-Point Subroutines 315 316 This section applies only to `testfloat' and not to `testsoftfloat'. 317 318 By default, TestFloat tests a machine's floating-point by testing the 319 floating-point operations of the C language. Unfortunately, some IEC/IEEE 320 floating-point operations are not defined within ISO/ANSI C. If a machine 321 implements such ``non-C'' operations, target-specific subroutines for 322 the operations can be supplied to allow TestFloat to test these machine 323 features. Typically, such subroutines will need to be written in assembly 324 language, although equivalent functions can sometimes be found among the 325 system's software libraries. 326 327 The following machine functions cannot be tested by TestFloat unless target- 328 specific 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 339 In addition to these, none of the `floatx80' functions can be tested by 340 default if the C `long double' type is something other than extended double 341 precision; and likewise, none of the `float128' functions can be tested by 342 default if `long double' is not quadruple precision. Since `long double' 343 cannot be both extended double precision and quadruple precision at the 344 same time, at least one of these types cannot be tested by TestFloat without 345 appropriate subroutines being supplied for that type. (On the other hand, 346 few systems implement _both_ extended double-precision and quadruple- 347 precision floating-point; and unless a system does implement both, it does 348 not need both tested.) 349 350 Note that the `-list' option to `testfloat' will show the operations 351 TestFloat is prepared to test. 352 353 TestFloat's `systfloat' module supplies the system version of the functions 354 to be tested. The names of the `systfloat' subroutines are the same as the 355 function names used as arguments to the `testfloat' command but with `syst_' 356 prefixed--thus, for example, `syst_float32_add' and `syst_int32_to_float32'. 357 The default `systfloat' module maps these system functions to the standard 358 C operations; so `syst_float32_add', for example, is implemented using the 359 C `+' operation for the single-precision `float' type. For each system 360 function supplied by `systfloat', a corresponding `SYST_<function>' 361 preprocessor macro is defined in `systfloat.h' to indicate that the function 362 exists to be tested (e.g., `SYST_FLOAT32_ADD'). The `systfloat.h' header 363 file also declares function prototypes for the `systfloat' functions. 364 365 (The `systfloat.h' file that comes with the TestFloat package declares 366 prototypes for all of the possible `systfloat' functions, whether defined in 367 `systfloat' or not. There is no penalty for declaring a function prototype 368 that is never used.) 369 370 A target-specific version of the `systfloat' module can easily be created to 371 replace 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 373 language `systfloat.S' has been created in the target directory along with 374 a corresponding `systfloat.h' header file defining the `SYST_<function>' 375 macros for the functions implemented. The makefiles of the targets have 376 been edited to use these target-specific versions of `systfloat' rather than 377 the generic one. 378 379 The `systfloat' modules of the example targets have been written entirely 380 in assembly language in order to bypass any peculiarities of the C compiler. 381 Although this is probably a good idea, it is certainly not required. 382 383 384 ------------------------------------------------------------------------------- 385 Steps to Creating the TestFloat Executables 386 387 Porting and/or compiling TestFloat involves the following steps: 388 389 1. Port SoftFloat and create a SoftFloat binary. (Refer to the 390 documentation accompanying SoftFloat.) 391 392 2. 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 397 3. Edit the files `milieu.h' and `Makefile' to reflect the current 398 environment. 399 400 4. 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 405 If you only wanted `testsoftfloat', you are done. The steps for `testfloat' 406 continue: 407 408 5. 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 413 6. 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 418 7. In the target-specific subdirectory, execute `make'. 419 420 421 ------------------------------------------------------------------------------- 422 Improving the Random Number Generator 423 424 If you are serious about using TestFloat for testing floating-point, you 425 should consider replacing the supplied `random.c' with a better target- 426 specific one. The standard C `rand' function is rather poor on some 427 systems, and consequently `random.c' has been written to assume very little 428 about the quality of `rand'. As a result, the `rand' function is called 429 more frequently than it might need to be, shortening the time before 430 the random number generator repeats, and possibly wasting time as well. 431 If `rand' is better on your system, or if another better random number 432 generator is available (such as `rand48' on most Unix systems), TestFloat 433 can be improved by overriding the given `random.c' with a target-specific 434 one. 435 436 437 ------------------------------------------------------------------------------- 438 Contact Information 439 440 At the time of this writing, the most up-to-date information about 441 TestFloat and the latest release can be found at the Web page `http:// 442 HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'. 443 444 445
Indexes created Sat Sep 20 22:09:52 GMT 2025