tools/test/testfloat/testfloat-source.txt

   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