tools/test/testfloat/testfloat.txt

   1
   2 TestFloat Release 2a General 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.
  17
  18 TestFloat actually comes in two variants:  one is a program for testing
  19 a machine's floating-point, and the other is a program for testing
  20 the SoftFloat software implementation of floating-point.  (Information
  21 about SoftFloat can be found at the SoftFloat Web page, `http://
  22 HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.)  The version that
  23 tests SoftFloat is expected to be of interest only to people compiling the
  24 SoftFloat sources.  However, because the two versions share much in common,
  25 they are discussed together in all the TestFloat documentation.
  26
  27 This document explains how to use the TestFloat programs.  It does not
  28 attempt to define or explain the IEC/IEEE Standard for floating-point.
  29 Details about the standard are available elsewhere.
  30
  31 The first release of TestFloat (Release 1) was called _FloatTest_.  The old
  32 name has been obsolete for some time.
  33
  34
  35 -------------------------------------------------------------------------------
  36 Limitations
  37
  38 TestFloat's output is not always easily interpreted.  Detailed knowledge
  39 of the IEC/IEEE Standard and its vagaries is needed to use TestFloat
  40 responsibly.
  41
  42 TestFloat performs relatively simple tests designed to check the fundamental
  43 soundness of the floating-point under test.  TestFloat may also at times
  44 manage to find rarer and more subtle bugs, but it will probably only find
  45 such bugs by accident.  Software that purposefully seeks out various kinds
  46 of subtle floating-point bugs can be found through links posted on the
  47 TestFloat Web page (`http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/
  48 TestFloat.html').
  49
  50
  51 -------------------------------------------------------------------------------
  52 Contents
  53
  54     Introduction
  55     Limitations
  56     Contents
  57     Legal Notice
  58     What TestFloat Does
  59     Executing TestFloat
  60     Functions Tested by TestFloat
  61         Conversion Functions
  62         Standard Arithmetic Functions
  63         Remainder and Round-to-Integer Functions
  64         Comparison Functions
  65     Interpreting TestFloat Output
  66     Variations Allowed by the IEC/IEEE Standard
  67         Underflow
  68         NaNs
  69         Conversions to Integer
  70     TestFloat Options
  71         -help
  72         -list
  73         -level <num>
  74         -errors <num>
  75         -errorstop
  76         -forever
  77         -checkNaNs
  78         -precision32, -precision64, -precision80
  79         -nearesteven, -tozero, -down, -up
  80         -tininessbefore, -tininessafter
  81     Function Sets
  82     Contact Information
  83
  84
  85
  86 -------------------------------------------------------------------------------
  87 Legal Notice
  88
  89 TestFloat was written by John R. Hauser.
  90
  91 THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE.  Although reasonable effort
  92 has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT
  93 TIMES RESULT IN INCORRECT BEHAVIOR.  USE OF THIS SOFTWARE IS RESTRICTED TO
  94 PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY
  95 AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE.
  96
  97
  98 -------------------------------------------------------------------------------
  99 What TestFloat Does
 100
 101 TestFloat tests a system's floating-point by comparing its behavior with
 102 that of TestFloat's own internal floating-point implemented in software.
 103 For each operation tested, TestFloat generates a large number of test cases,
 104 made up of simple pattern tests intermixed with weighted random inputs.
 105 The cases generated should be adequate for testing carry chain propagations,
 106 plus the rounding of adds, subtracts, multiplies, and simple operations like
 107 conversions.  TestFloat makes a point of checking all boundary cases of the
 108 arithmetic, including underflows, overflows, invalid operations, subnormal
 109 inputs, zeros (positive and negative), infinities, and NaNs.  For the
 110 interesting operations like adds and multiplies, literally millions of test
 111 cases can be checked.
 112
 113 TestFloat is not remarkably good at testing difficult rounding cases for
 114 divisions and square roots.  It also makes no attempt to find bugs specific
 115 to SRT divisions and the like (such as the infamous Pentium divide bug).
 116 Software that tests for such failures can be found through links on the
 117 TestFloat Web page, `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/
 118 TestFloat.html'.
 119
 120 NOTE!
 121 It is the responsibility of the user to verify that the discrepancies
 122 TestFloat finds actually represent faults in the system being tested.
 123 Advice to help with this task is provided later in this document.
 124 Furthermore, even if TestFloat finds no fault with a floating-point
 125 implementation, that in no way guarantees that the implementation is bug-
 126 free.
 127
 128 For each operation, TestFloat can test all four rounding modes required
 129 by the IEC/IEEE Standard.  TestFloat verifies not only that the numeric
 130 results of an operation are correct, but also that the proper floating-point
 131 exception flags are raised.  All five exception flags are tested, including
 132 the inexact flag.  TestFloat does not attempt to verify that the floating-
 133 point exception flags are actually implemented as sticky flags.
 134
 135 For machines that implement extended double precision with rounding
 136 precision control (such as Intel's 80x86), TestFloat can test the add,
 137 subtract, multiply, divide, and square root functions at all the standard
 138 rounding precisions.  The rounding precision can be set equivalent to single
 139 precision, to double precision, or to the full extended double precision.
 140 Rounding precision control can only be applied to the extended double-
 141 precision format and only for the five standard arithmetic operations:  add,
 142 subtract, multiply, divide, and square root.  Other functions can be tested
 143 only at full precision.
 144
 145 As a rule, TestFloat is not particular about the bit patterns of NaNs that
 146 appear as function results.  Any NaN is considered as good a result as
 147 another.  This laxness can be overridden so that TestFloat checks for
 148 particular bit patterns within NaN results.  See the sections _Variations_
 149 _Allowed_by_the_IEC/IEEE_Standard_ and _TestFloat_Options_ for details.
 150
 151 Not all IEC/IEEE Standard functions are supported by all machines.
 152 TestFloat can only test functions that exist on the machine.  But even if
 153 a function is supported by the machine, TestFloat may still not be able
 154 to test the function if it is not accessible through standard ISO C (the
 155 programming language in which TestFloat is written) and if the person who
 156 compiled TestFloat did not provide an alternate means for TestFloat to
 157 invoke the machine function.
 158
 159 TestFloat compares a machine's floating-point against the SoftFloat software
 160 implementation of floating-point, also written by me.  SoftFloat is built
 161 into the TestFloat executable and does not need to be supplied by the user.
 162 If SoftFloat is wanted for some other reason (to compile a new version
 163 of TestFloat, for instance), it can be found separately at the Web page
 164 `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.
 165
 166 For testing SoftFloat itself, the TestFloat package includes a program that
 167 compares SoftFloat's floating-point against _another_ software floating-
 168 point implementation.  The second software floating-point is simpler and
 169 slower than SoftFloat, and is completely independent of SoftFloat.  Although
 170 the second software floating-point cannot be guaranteed to be bug-free, the
 171 chance that it would mimic any of SoftFloat's bugs is remote.  Consequently,
 172 an error in one or the other floating-point version should appear as an
 173 unexpected discrepancy between the two implementations.  Note that testing
 174 SoftFloat should only be necessary when compiling a new TestFloat executable
 175 or when compiling SoftFloat for some other reason.
 176
 177
 178 -------------------------------------------------------------------------------
 179 Executing TestFloat
 180
 181 TestFloat is intended to be executed from a command line interpreter.  The
 182 `testfloat' program is invoked as follows:
 183
 184     testfloat [<option>...] <function>
 185
 186 Here square brackets ([]) indicate optional items, while angled brackets
 187 (<>) denote parameters to be filled in.
 188
 189 The `<function>' argument is a name like `float32_add' or `float64_to_int32'.
 190 The complete list of function names is given in the next section,
 191 _Functions_Tested_by_TestFloat_.  It is also possible to test all machine
 192 functions in a single invocation.  The various options to TestFloat are
 193 detailed in the section _TestFloat_Options_ later in this document.  If
 194 `testfloat' is executed without any arguments, a summary of TestFloat usage
 195 is written.
 196
 197 TestFloat will ordinarily test a function for all four rounding modes, one
 198 after the other.  If the rounding mode is not supposed to have any affect
 199 on the results--for instance, some operations do not require rounding--only
 200 the nearest/even rounding mode is checked.  For extended double-precision
 201 operations affected by rounding precision control, TestFloat also tests all
 202 three rounding precision modes, one after the other.  Testing can be limited
 203 to a single rounding mode and/or rounding precision with appropriate options
 204 (see _TestFloat_Options_).
 205
 206 As it executes, TestFloat writes status information to the standard error
 207 output, which should be the screen by default.  In order for this status to
 208 be displayed properly, the standard error stream should not be redirected
 209 to a file.  The discrepancies TestFloat finds are written to the standard
 210 output stream, which is easily redirected to a file if desired.  Ordinarily,
 211 the errors TestFloat reports and the ongoing status information appear
 212 intermixed on the same screen.
 213
 214 The version of TestFloat for testing SoftFloat is called `testsoftfloat'.
 215 It is invoked the same as `testfloat',
 216
 217     testsoftfloat [<option>...] <function>
 218
 219 and operates similarly.
 220
 221
 222 -------------------------------------------------------------------------------
 223 Functions Tested by TestFloat
 224
 225 TestFloat tests all operations required by the IEC/IEEE Standard except for
 226 conversions to and from decimal.  The operations are
 227
 228 -- Conversions among the supported floating-point formats, and also between
 229    integers (32-bit and 64-bit) and any of the floating-point formats.
 230
 231 -- The usual add, subtract, multiply, divide, and square root operations
 232    for all supported floating-point formats.
 233
 234 -- For each format, the floating-point remainder operation defined by the
 235    IEC/IEEE Standard.
 236
 237 -- For each floating-point format, a ``round to integer'' operation that
 238    rounds to the nearest integer value in the same format.  (The floating-
 239    point formats can hold integer values, of course.)
 240
 241 -- Comparisons between two values in the same floating-point format.
 242
 243 Detailed information about these functions is given below.  In the function
 244 names used by TestFloat, single precision is called `float32', double
 245 precision is `float64', extended double precision is `floatx80', and
 246 quadruple precision is `float128'.  TestFloat uses the same names for
 247 functions as SoftFloat.
 248
 249 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 250 Conversion Functions
 251
 252 All conversions among the floating-point formats and all conversion between
 253 a floating-point format and 32-bit and 64-bit signed integers can be tested.
 254 The conversion functions are:
 255
 256    int32_to_float32      int64_to_float32
 257    int32_to_float64      int64_to_float32
 258    int32_to_floatx80     int64_to_floatx80
 259    int32_to_float128     int64_to_float128
 260
 261    float32_to_int32      float32_to_int64
 262    float32_to_int32      float64_to_int64
 263    floatx80_to_int32     floatx80_to_int64
 264    float128_to_int32     float128_to_int64
 265
 266    float32_to_float64    float32_to_floatx80   float32_to_float128
 267    float64_to_float32    float64_to_floatx80   float64_to_float128
 268    floatx80_to_float32   floatx80_to_float64   floatx80_to_float128
 269    float128_to_float32   float128_to_float64   float128_to_floatx80
 270
 271 These conversions all round according to the current rounding mode as
 272 necessary.  Conversions from a smaller to a larger floating-point format are
 273 always exact and so require no rounding.  Conversions from 32-bit integers
 274 to double precision or to any larger floating-point format are also exact,
 275 and likewise for conversions from 64-bit integers to extended double and
 276 quadruple precisions.
 277
 278 ISO/ANSI C requires that conversions to integers be rounded toward zero.
 279 Such conversions can be tested with the following functions that ignore any
 280 rounding mode:
 281
 282    float32_to_int32_round_to_zero    float32_to_int64_round_to_zero
 283    float64_to_int32_round_to_zero    float64_to_int64_round_to_zero
 284    floatx80_to_int32_round_to_zero   floatx80_to_int64_round_to_zero
 285    float128_to_int32_round_to_zero   float128_to_int64_round_to_zero
 286
 287 TestFloat assumes that conversions from floating-point to integer should
 288 raise the invalid exception if the source value cannot be rounded to a
 289 representable integer of the desired size (32 or 64 bits).  If such a
 290 conversion overflows, TestFloat expects the largest integer with the same
 291 sign as the operand to be returned.  If the floating-point operand is a NaN,
 292 TestFloat allows either the largest positive or largest negative integer to
 293 be returned.
 294
 295 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 296 Standard Arithmetic Functions
 297
 298 The following standard arithmetic functions can be tested:
 299
 300    float32_add    float32_sub    float32_mul    float32_div    float32_sqrt
 301    float64_add    float64_sub    float64_mul    float64_div    float64_sqrt
 302    floatx80_add   floatx80_sub   floatx80_mul   floatx80_div   floatx80_sqrt
 303    float128_add   float128_sub   float128_mul   float128_div   float128_sqrt
 304
 305 The extended double-precision (`floatx80') functions can be rounded to
 306 reduced precision under rounding precision control.
 307
 308 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 309 Remainder and Round-to-Integer Functions
 310
 311 For each format, TestFloat can test the IEC/IEEE Standard remainder and
 312 round-to-integer functions.  The remainder functions are:
 313
 314    float32_rem
 315    float64_rem
 316    floatx80_rem
 317    float128_rem
 318
 319 The round-to-integer functions are:
 320
 321    float32_round_to_int
 322    float64_round_to_int
 323    floatx80_round_to_int
 324    float128_round_to_int
 325
 326 The remainder functions are always exact and so do not require rounding.
 327
 328 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 329 Comparison Functions
 330
 331 The following floating-point comparison functions can be tested:
 332
 333    float32_eq    float32_le    float32_lt
 334    float64_eq    float64_le    float64_lt
 335    floatx80_eq   floatx80_le   floatx80_lt
 336    float128_eq   float128_le   float128_lt
 337
 338 The abbreviation `eq' stands for ``equal'' (=); `le' stands for ``less than
 339 or equal'' (<=); and `lt' stands for ``less than'' (<).
 340
 341 The IEC/IEEE Standard specifies that the less-than-or-equal and less-than
 342 functions raise the invalid exception if either input is any kind of NaN.
 343 The equal functions, for their part, are defined not to raise the invalid
 344 exception on quiet NaNs.  For completeness, the following additional
 345 functions can be tested if supported:
 346
 347    float32_eq_signaling    float32_le_quiet    float32_lt_quiet
 348    float64_eq_signaling    float64_le_quiet    float64_lt_quiet
 349    floatx80_eq_signaling   floatx80_le_quiet   floatx80_lt_quiet
 350    float128_eq_signaling   float128_le_quiet   float128_lt_quiet
 351
 352 The `signaling' equal functions are identical to the standard functions
 353 except that the invalid exception should be raised for any NaN input.
 354 Likewise, the `quiet' comparison functions should be identical to their
 355 counterparts except that the invalid exception is not raised for quiet NaNs.
 356
 357 Obviously, no comparison functions ever require rounding.  Any rounding mode
 358 is ignored.
 359
 360 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 361
 362
 363 -------------------------------------------------------------------------------
 364 Interpreting TestFloat Output
 365
 366 The ``errors'' reported by TestFloat may or may not really represent errors
 367 in the system being tested.  For each test case tried, TestFloat performs
 368 the same floating-point operation for the two implementations being compared
 369 and reports any unexpected difference in the results.  The two results could
 370 differ for several reasons:
 371
 372 -- The IEC/IEEE Standard allows for some variation in how conforming
 373    floating-point behaves.  Two implementations can occasionally give
 374    different results without either being incorrect.
 375
 376 -- The trusted floating-point emulation could be faulty.  This could be
 377    because there is a bug in the way the enulation is coded, or because a
 378    mistake was made when the code was compiled for the current system.
 379
 380 -- TestFloat may not work properly, reporting discrepancies that do not
 381    exist.
 382
 383 -- Lastly, the floating-point being tested could actually be faulty.
 384
 385 It is the responsibility of the user to determine the causes for the
 386 discrepancies TestFloat reports.  Making this determination can require
 387 detailed knowledge about the IEC/IEEE Standard.  Assuming TestFloat is
 388 working properly, any differences found will be due to either the first or
 389 last of these reasons.  Variations in the IEC/IEEE Standard that could lead
 390 to false error reports are discussed in the section _Variations_Allowed_by_
 391 _the_IEC/IEEE_Standard_.
 392
 393 For each error (or apparent error) TestFloat reports, a line of text
 394 is written to the default output.  If a line would be longer than 79
 395 characters, it is divided.  The first part of each error line begins in the
 396 leftmost column, and any subsequent ``continuation'' lines are indented with
 397 a tab.
 398
 399 Each error reported by `testfloat' is of the form:
 400
 401     <inputs>  soft: <output-from-emulation>  syst: <output-from-system>
 402
 403 The `<inputs>' are the inputs to the operation.  Each output is shown as a
 404 pair:  the result value first, followed by the exception flags.  The `soft'
 405 label stands for ``software'' (or ``SoftFloat''), while `syst' stands for
 406 ``system,'' the machine's floating-point.
 407
 408 For example, two typical error lines could be
 409
 410     800.7FFF00  87F.000100  soft: 001.000000 ....x  syst: 001.000000 ...ux
 411     081.000004  000.1FFFFF  soft: 001.000000 ....x  syst: 001.000000 ...ux
 412
 413 In the first line, the inputs are `800.7FFF00' and `87F.000100'.  The
 414 internal emulation result is `001.000000' with flags `....x', and the
 415 system result is the same but with flags `...ux'.  All the items composed of
 416 hexadecimal digits and a single period represent floating-point values (here
 417 single precision).  These cases were reported as errors because the flag
 418 results differ.
 419
 420 In addition to the exception flags, there are seven data types that may
 421 be represented.  Four are floating-point types:  single precision, double
 422 precision, extended double precision, and quadruple precision.  The
 423 remaining three types are 32-bit and 64-bit two's-complement integers and
 424 Boolean values (the results of comparison operations).  Boolean values are
 425 represented as a single character, either a `0' or a `1'.  32-bit integers
 426 are written as 8 hexadecimal digits in two's-complement form.  Thus,
 427 `FFFFFFFF' is -1, and `7FFFFFFF' is the largest positive 32-bit integer.
 428 64-bit integers are the same except with 16 hexadecimal digits.
 429
 430 Floating-point values are written in a correspondingly primitive form.
 431 Double-precision values are represented by 16 hexadecimal digits that give
 432 the raw bits of the floating-point encoding.  A period separates the 3rd and
 433 4th hexadecimal digits to mark the division between the exponent bits and
 434 fraction bits.  Some notable double-precision values include:
 435
 436     000.0000000000000    +0
 437     3FF.0000000000000     1
 438     400.0000000000000     2
 439     7FF.0000000000000    +infinity
 440
 441     800.0000000000000    -0
 442     BFF.0000000000000    -1
 443     C00.0000000000000    -2
 444     FFF.0000000000000    -infinity
 445
 446     3FE.FFFFFFFFFFFFF    largest representable number preceding +1
 447
 448 The following categories are easily distinguished (assuming the `x's are not
 449 all 0):
 450
 451     000.xxxxxxxxxxxxx    positive subnormal (denormalized) numbers
 452     7FF.xxxxxxxxxxxxx    positive NaNs
 453     800.xxxxxxxxxxxxx    negative subnormal numbers
 454     FFF.xxxxxxxxxxxxx    negative NaNs
 455
 456 Quadruple-precision values are written the same except with 4 hexadecimal
 457 digits for the sign and exponent and 28 for the fraction.  Notable values
 458 include:
 459
 460     0000.0000000000000000000000000000    +0
 461     3FFF.0000000000000000000000000000     1
 462     4000.0000000000000000000000000000     2
 463     7FFF.0000000000000000000000000000    +infinity
 464
 465     8000.0000000000000000000000000000    -0
 466     BFFF.0000000000000000000000000000    -1
 467     C000.0000000000000000000000000000    -2
 468     FFFF.0000000000000000000000000000    -infinity
 469
 470     3FFE.FFFFFFFFFFFFFFFFFFFFFFFFFFFF    largest representable number
 471                                              preceding +1
 472
 473 Extended double-precision values are a little unusual in that the leading
 474 significand bit is not hidden as with other formats.  When correctly
 475 encoded, the leading significand bit of an extended double-precision value
 476 will be 0 if the value is zero or subnormal, and will be 1 otherwise.
 477 Hence, the same values listed above appear in extended double-precision as
 478 follows (note the leading `8' digit in the significands):
 479
 480     0000.0000000000000000    +0
 481     3FFF.8000000000000000     1
 482     4000.8000000000000000     2
 483     7FFF.8000000000000000    +infinity
 484
 485     8000.0000000000000000    -0
 486     BFFF.8000000000000000    -1
 487     C000.8000000000000000    -2
 488     FFFF.8000000000000000    -infinity
 489
 490     3FFE.FFFFFFFFFFFFFFFF    largest representable number preceding +1
 491
 492 The representation of single-precision values is unusual for a different
 493 reason.  Because the subfields of standard single-precision do not fall
 494 on neat 4-bit boundaries, single-precision outputs are slightly perturbed.
 495 These are written as 9 hexadecimal digits, with a period separating the 3rd
 496 and 4th hexadecimal digits.  Broken out into bits, the 9 hexademical digits
 497 cover the single-precision subfields as follows:
 498
 499     x000 .... ....  .  .... .... .... .... .... ....    sign       (1 bit)
 500     .... xxxx xxxx  .  .... .... .... .... .... ....    exponent   (8 bits)
 501     .... .... ....  .  0xxx xxxx xxxx xxxx xxxx xxxx    fraction  (23 bits)
 502
 503 As shown in this schematic, the first hexadecimal digit contains only
 504 the sign, and will be either `0' or `8'.  The next two digits give the
 505 biased exponent as an 8-bit integer.  This is followed by a period and
 506 6 hexadecimal digits of fraction.  The most significant hexadecimal digit
 507 of the fraction can be at most a `7'.
 508
 509 Notable single-precision values include:
 510
 511     000.000000    +0
 512     07F.000000     1
 513     080.000000     2
 514     0FF.000000    +infinity
 515
 516     800.000000    -0
 517     87F.000000    -1
 518     880.000000    -2
 519     8FF.000000    -infinity
 520
 521     07E.7FFFFF    largest representable number preceding +1
 522
 523 Again, certain categories are easily distinguished (assuming the `x's are
 524 not all 0):
 525
 526     000.xxxxxx    positive subnormal (denormalized) numbers
 527     0FF.xxxxxx    positive NaNs
 528     800.xxxxxx    negative subnormal numbers
 529     8FF.xxxxxx    negative NaNs
 530
 531 Lastly, exception flag values are represented by five characters, one
 532 character per flag.  Each flag is written as either a letter or a period
 533 (`.') according to whether the flag was set or not by the operation.  A
 534 period indicates the flag was not set.  The letter used to indicate a set
 535 flag depends on the flag:
 536
 537     v    invalid flag
 538     z    division-by-zero flag
 539     o    overflow flag
 540     u    underflow flag
 541     x    inexact flag
 542
 543 For example, the notation `...ux' indicates that the underflow and inexact
 544 exception flags were set and that the other three flags (invalid, division-
 545 by-zero, and overflow) were not set.  The exception flags are always shown
 546 following the value returned as the result of the operation.
 547
 548 The output from `testsoftfloat' is of the same form, except that the results
 549 are labeled `true' and `soft':
 550
 551     <inputs>  true: <simple-software-result>  soft: <SoftFloat-result>
 552
 553 The ``true'' result is from the simpler, slower software floating-point,
 554 which, although not necessarily correct, is more likely to be right than
 555 the SoftFloat (`soft') result.
 556
 557
 558 -------------------------------------------------------------------------------
 559 Variations Allowed by the IEC/IEEE Standard
 560
 561 The IEC/IEEE Standard admits some variation among conforming
 562 implementations.  Because TestFloat expects the two implementations being
 563 compared to deliver bit-for-bit identical results under most circumstances,
 564 this leeway in the standard can result in false errors being reported if
 565 the two implementations do not make the same choices everywhere the standard
 566 provides an option.
 567
 568 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 569 Underflow
 570
 571 The standard specifies that the underflow exception flag is to be raised
 572 when two conditions are met simultaneously:  (1) _tininess_ and (2) _loss_
 573 _of_accuracy_.  A result is tiny when its magnitude is nonzero yet smaller
 574 than any normalized floating-point number.  The standard allows tininess to
 575 be determined either before or after a result is rounded to the destination
 576 precision.  If tininess is detected before rounding, some borderline cases
 577 will be flagged as underflows even though the result after rounding actually
 578 lies within the normal floating-point range.  By detecting tininess after
 579 rounding, a system can avoid some unnecessary signaling of underflow.
 580
 581 Loss of accuracy occurs when the subnormal format is not sufficient
 582 to represent an underflowed result accurately.  The standard allows
 583 loss of accuracy to be detected either as an _inexact_result_ or as a
 584 _denormalization_loss_.  If loss of accuracy is detected as an inexact
 585 result, the underflow flag is raised whenever an underflowed quantity
 586 cannot be exactly represented in the subnormal format (that is, whenever the
 587 inexact flag is also raised).  A denormalization loss, on the other hand,
 588 occurs only when the subnormal format is not able to represent the result
 589 that would have been returned if the destination format had infinite range.
 590 Some underflowed results are inexact but do not suffer a denormalization
 591 loss.  By detecting loss of accuracy as a denormalization loss, a system can
 592 once again avoid some unnecessary signaling of underflow.
 593
 594 The `-tininessbefore' and `-tininessafter' options can be used to control
 595 whether TestFloat expects tininess on underflow to be detected before or
 596 after rounding.  (See _TestFloat_Options_ below.)  One or the other is
 597 selected as the default when TestFloat is compiled, but these command
 598 options allow the default to be overridden.
 599
 600 Most (possibly all) systems detect loss of accuracy as an inexact result.
 601 The current version of TestFloat can only test for this case.
 602
 603 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 604 NaNs
 605
 606 The IEC/IEEE Standard gives the floating-point formats a large number of
 607 NaN encodings and specifies that NaNs are to be returned as results under
 608 certain conditions.  However, the standard allows an implementation almost
 609 complete freedom over _which_ NaN to return in each situation.
 610
 611 By default, TestFloat does not check the bit patterns of NaN results.  When
 612 the result of an operation should be a NaN, any NaN is considered as good
 613 as another.  This laxness can be overridden with the `-checkNaNs' option.
 614 (See _TestFloat_Options_ below.)  In order for this option to be sensible,
 615 TestFloat must have been compiled so that its internal floating-point
 616 implementation (SoftFloat) generates the proper NaN results for the system
 617 being tested.
 618
 619 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 620 Conversions to Integer
 621
 622 Conversion of a floating-point value to an integer format will fail if the
 623 source value is a NaN or if it is too large.  The IEC/IEEE Standard does not
 624 specify what value should be returned as the integer result in these cases.
 625 Moreover, according to the standard, the invalid exception can be raised or
 626 an unspecified alternative mechanism may be used to signal such cases.
 627
 628 TestFloat assumes that conversions to integer will raise the invalid
 629 exception if the source value cannot be rounded to a representable integer.
 630 When the conversion overflows, TestFloat expects the largest integer with
 631 the same sign as the operand to be returned.  If the floating-point operand
 632 is a NaN, TestFloat allows either the largest positive or largest negative
 633 integer to be returned.  The current version of TestFloat provides no means
 634 to alter these conventions.
 635
 636 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 637
 638
 639 -------------------------------------------------------------------------------
 640 TestFloat Options
 641
 642 The `testfloat' (and `testsoftfloat') program accepts several command
 643 options.  If mutually contradictory options are given, the last one has
 644 priority.
 645
 646 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 647 -help
 648
 649 The `-help' option causes a summary of program usage to be written, after
 650 which the program exits.
 651
 652 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 653 -list
 654
 655 The `-list' option causes a list of testable functions to be written,
 656 after which the program exits.  Some machines do not implement all of the
 657 functions TestFloat can test, plus it may not be possible to test functions
 658 that are inaccessible from the C language.
 659
 660 The `testsoftfloat' program does not have this option.  All SoftFloat
 661 functions can be tested by `testsoftfloat'.
 662
 663 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 664 -level <num>
 665
 666 The `-level' option sets the level of testing.  The argument to `-level' can
 667 be either 1 or 2.  The default is level 1.  Level 2 performs many more tests
 668 than level 1.  Testing at level 2 can take as much as a day (even longer for
 669 `testsoftfloat'), but can reveal bugs not found by level 1.
 670
 671 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 672 -errors <num>
 673
 674 The `-errors' option instructs TestFloat to report no more than the
 675 specified number of errors for any combination of function, rounding mode,
 676 etc.  The argument to `-errors' must be a nonnegative decimal number.  Once
 677 the specified number of error reports has been generated, TestFloat ends the
 678 current test and begins the next one, if any.  The default is `-errors 20'.
 679
 680 Against intuition, `-errors 0' causes TestFloat to report every error it
 681 finds.
 682
 683 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 684 -errorstop
 685
 686 The `-errorstop' option causes the program to exit after the first function
 687 for which any errors are reported.
 688
 689 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 690 -forever
 691
 692 The `-forever' option causes a single operation to be repeatedly tested.
 693 Only one rounding mode and/or rounding precision can be tested in a single
 694 invocation.  If not specified, the rounding mode defaults to nearest/even.
 695 For extended double-precision operations, the rounding precision defaults
 696 to full extended double precision.  The testing level is set to 2 by this
 697 option.
 698
 699 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 700 -checkNaNs
 701
 702 The `-checkNaNs' option causes TestFloat to verify the bitwise correctness
 703 of NaN results.  In order for this option to be sensible, TestFloat must
 704 have been compiled so that its internal floating-point implementation
 705 (SoftFloat) generates the proper NaN results for the system being tested.
 706
 707 This option is not available to `testsoftfloat'.
 708
 709 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 710 -precision32, -precision64, -precision80
 711
 712 For extended double-precision functions affected by rounding precision
 713 control, the `-precision32' option restricts testing to only the cases
 714 in which rounding precision is equivalent to single precision.  The other
 715 rounding precision options are not tested.  Likewise, the `-precision64'
 716 and `-precision80' options fix the rounding precision equivalent to double
 717 precision or extended double precision, respectively.  These options are
 718 ignored for functions not affected by rounding precision control.
 719
 720 These options are not available if extended double precision is not
 721 supported by the machine or if extended double precision functions cannot be
 722 tested.
 723
 724 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 725 -nearesteven, -tozero, -down, -up
 726
 727 The `-nearesteven' option restricts testing to only the cases in which the
 728 rounding mode is nearest/even.  The other rounding mode options are not
 729 tested.  Likewise, `-tozero' forces rounding to zero; `-down' forces
 730 rounding down; and `-up' forces rounding up.  These options are ignored for
 731 functions that are exact and thus do not round.
 732
 733 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 734 -tininessbefore, -tininessafter
 735
 736 The `-tininessbefore' option indicates that the system detects tininess
 737 on underflow before rounding.  The `-tininessafter' option indicates that
 738 tininess is detected after rounding.  TestFloat alters its expectations
 739 accordingly.  These options override the default selected when TestFloat was
 740 compiled.  Choosing the wrong one of these two options should cause error
 741 reports for some (not all) functions.
 742
 743 For `testsoftfloat', these options operate more like the rounding precision
 744 and rounding mode options, in that they restrict the tests performed by
 745 `testsoftfloat'.  By default, `testsoftfloat' tests both cases for any
 746 function for which there is a difference.
 747
 748 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 749
 750
 751 -------------------------------------------------------------------------------
 752 Function Sets
 753
 754 Just as TestFloat can test an operation for all four rounding modes in
 755 sequence, multiple operations can be tested with a single invocation of
 756 TestFloat.  Three sets are recognized:  `-all1', `-all2', and `-all'.  The
 757 set `-all1' comprises all one-operand functions; `-all2' is all two-operand
 758 functions; and `-all' is all functions.  A function set can be used in place
 759 of a function name in the TestFloat command line, such as
 760
 761     testfloat [<option>...] -all
 762
 763
 764 -------------------------------------------------------------------------------
 765 Contact Information
 766
 767 At the time of this writing, the most up-to-date information about
 768 TestFloat and the latest release can be found at the Web page `http://
 769 HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'.
 770
 771