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