diff options
Diffstat (limited to 'testfloat/testfloat.txt')
| -rw-r--r-- | testfloat/testfloat.txt | 771 |
1 files changed, 771 insertions, 0 deletions
diff --git a/testfloat/testfloat.txt b/testfloat/testfloat.txt new file mode 100644 index 000000000000..6e72c1d89fd3 --- /dev/null +++ b/testfloat/testfloat.txt @@ -0,0 +1,771 @@ + +TestFloat Release 2a General Documentation + +John R. Hauser +1998 December 16 + + +------------------------------------------------------------------------------- +Introduction + +TestFloat is a program for testing that a floating-point implementation +conforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. +All standard operations supported by the system can be tested, except for +conversions to and from decimal. Any of the following machine formats can +be tested: single precision, double precision, extended double precision, +and/or quadruple precision. + +TestFloat actually comes in two variants: one is a program for testing +a machine's floating-point, and the other is a program for testing +the SoftFloat software implementation of floating-point. (Information +about SoftFloat can be found at the SoftFloat Web page, `http:// +HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.) The version that +tests SoftFloat is expected to be of interest only to people compiling the +SoftFloat sources. However, because the two versions share much in common, +they are discussed together in all the TestFloat documentation. + +This document explains how to use the TestFloat programs. It does not +attempt to define or explain the IEC/IEEE Standard for floating-point. +Details about the standard are available elsewhere. + +The first release of TestFloat (Release 1) was called _FloatTest_. The old +name has been obsolete for some time. + + +------------------------------------------------------------------------------- +Limitations + +TestFloat's output is not always easily interpreted. Detailed knowledge +of the IEC/IEEE Standard and its vagaries is needed to use TestFloat +responsibly. + +TestFloat performs relatively simple tests designed to check the fundamental +soundness of the floating-point under test. TestFloat may also at times +manage to find rarer and more subtle bugs, but it will probably only find +such bugs by accident. Software that purposefully seeks out various kinds +of subtle floating-point bugs can be found through links posted on the +TestFloat Web page (`http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/ +TestFloat.html'). + + +------------------------------------------------------------------------------- +Contents + + Introduction + Limitations + Contents + Legal Notice + What TestFloat Does + Executing TestFloat + Functions Tested by TestFloat + Conversion Functions + Standard Arithmetic Functions + Remainder and Round-to-Integer Functions + Comparison Functions + Interpreting TestFloat Output + Variations Allowed by the IEC/IEEE Standard + Underflow + NaNs + Conversions to Integer + TestFloat Options + -help + -list + -level <num> + -errors <num> + -errorstop + -forever + -checkNaNs + -precision32, -precision64, -precision80 + -nearesteven, -tozero, -down, -up + -tininessbefore, -tininessafter + Function Sets + Contact Information + + + +------------------------------------------------------------------------------- +Legal Notice + +TestFloat was written by John R. Hauser. + +THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort +has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT +TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO +PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY +AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. + + +------------------------------------------------------------------------------- +What TestFloat Does + +TestFloat tests a system's floating-point by comparing its behavior with +that of TestFloat's own internal floating-point implemented in software. +For each operation tested, TestFloat generates a large number of test cases, +made up of simple pattern tests intermixed with weighted random inputs. +The cases generated should be adequate for testing carry chain propagations, +plus the rounding of adds, subtracts, multiplies, and simple operations like +conversions. TestFloat makes a point of checking all boundary cases of the +arithmetic, including underflows, overflows, invalid operations, subnormal +inputs, zeros (positive and negative), infinities, and NaNs. For the +interesting operations like adds and multiplies, literally millions of test +cases can be checked. + +TestFloat is not remarkably good at testing difficult rounding cases for +divisions and square roots. It also makes no attempt to find bugs specific +to SRT divisions and the like (such as the infamous Pentium divide bug). +Software that tests for such failures can be found through links on the +TestFloat Web page, `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/ +TestFloat.html'. + +NOTE! +It is the responsibility of the user to verify that the discrepancies +TestFloat finds actually represent faults in the system being tested. +Advice to help with this task is provided later in this document. +Furthermore, even if TestFloat finds no fault with a floating-point +implementation, that in no way guarantees that the implementation is bug- +free. + +For each operation, TestFloat can test all four rounding modes required +by the IEC/IEEE Standard. TestFloat verifies not only that the numeric +results of an operation are correct, but also that the proper floating-point +exception flags are raised. All five exception flags are tested, including +the inexact flag. TestFloat does not attempt to verify that the floating- +point exception flags are actually implemented as sticky flags. + +For machines that implement extended double precision with rounding +precision control (such as Intel's 80x86), TestFloat can test the add, +subtract, multiply, divide, and square root functions at all the standard +rounding precisions. The rounding precision can be set equivalent to single +precision, to double precision, or to the full extended double precision. +Rounding precision control can only be applied to the extended double- +precision format and only for the five standard arithmetic operations: add, +subtract, multiply, divide, and square root. Other functions can be tested +only at full precision. + +As a rule, TestFloat is not particular about the bit patterns of NaNs that +appear as function results. Any NaN is considered as good a result as +another. This laxness can be overridden so that TestFloat checks for +particular bit patterns within NaN results. See the sections _Variations_ +_Allowed_by_the_IEC/IEEE_Standard_ and _TestFloat_Options_ for details. + +Not all IEC/IEEE Standard functions are supported by all machines. +TestFloat can only test functions that exist on the machine. But even if +a function is supported by the machine, TestFloat may still not be able +to test the function if it is not accessible through standard ISO C (the +programming language in which TestFloat is written) and if the person who +compiled TestFloat did not provide an alternate means for TestFloat to +invoke the machine function. + +TestFloat compares a machine's floating-point against the SoftFloat software +implementation of floating-point, also written by me. SoftFloat is built +into the TestFloat executable and does not need to be supplied by the user. +If SoftFloat is wanted for some other reason (to compile a new version +of TestFloat, for instance), it can be found separately at the Web page +`http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. + +For testing SoftFloat itself, the TestFloat package includes a program that +compares SoftFloat's floating-point against _another_ software floating- +point implementation. The second software floating-point is simpler and +slower than SoftFloat, and is completely independent of SoftFloat. Although +the second software floating-point cannot be guaranteed to be bug-free, the +chance that it would mimic any of SoftFloat's bugs is remote. Consequently, +an error in one or the other floating-point version should appear as an +unexpected discrepancy between the two implementations. Note that testing +SoftFloat should only be necessary when compiling a new TestFloat executable +or when compiling SoftFloat for some other reason. + + +------------------------------------------------------------------------------- +Executing TestFloat + +TestFloat is intended to be executed from a command line interpreter. The +`testfloat' program is invoked as follows: + + testfloat [<option>...] <function> + +Here square brackets ([]) indicate optional items, while angled brackets +(<>) denote parameters to be filled in. + +The `<function>' argument is a name like `float32_add' or `float64_to_int32'. +The complete list of function names is given in the next section, +_Functions_Tested_by_TestFloat_. It is also possible to test all machine +functions in a single invocation. The various options to TestFloat are +detailed in the section _TestFloat_Options_ later in this document. If +`testfloat' is executed without any arguments, a summary of TestFloat usage +is written. + +TestFloat will ordinarily test a function for all four rounding modes, one +after the other. If the rounding mode is not supposed to have any affect +on the results--for instance, some operations do not require rounding--only +the nearest/even rounding mode is checked. For extended double-precision +operations affected by rounding precision control, TestFloat also tests all +three rounding precision modes, one after the other. Testing can be limited +to a single rounding mode and/or rounding precision with appropriate options +(see _TestFloat_Options_). + +As it executes, TestFloat writes status information to the standard error +output, which should be the screen by default. In order for this status to +be displayed properly, the standard error stream should not be redirected +to a file. The discrepancies TestFloat finds are written to the standard +output stream, which is easily redirected to a file if desired. Ordinarily, +the errors TestFloat reports and the ongoing status information appear +intermixed on the same screen. + +The version of TestFloat for testing SoftFloat is called `testsoftfloat'. +It is invoked the same as `testfloat', + + testsoftfloat [<option>...] <function> + +and operates similarly. + + +------------------------------------------------------------------------------- +Functions Tested by TestFloat + +TestFloat tests all operations required by the IEC/IEEE Standard except for +conversions to and from decimal. The operations are + +-- Conversions among the supported floating-point formats, and also between + integers (32-bit and 64-bit) and any of the floating-point formats. + +-- The usual add, subtract, multiply, divide, and square root operations + for all supported floating-point formats. + +-- For each format, the floating-point remainder operation defined by the + IEC/IEEE Standard. + +-- For each floating-point format, a ``round to integer'' operation that + rounds to the nearest integer value in the same format. (The floating- + point formats can hold integer values, of course.) + +-- Comparisons between two values in the same floating-point format. + +Detailed information about these functions is given below. In the function +names used by TestFloat, single precision is called `float32', double +precision is `float64', extended double precision is `floatx80', and +quadruple precision is `float128'. TestFloat uses the same names for +functions as SoftFloat. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Conversion Functions + +All conversions among the floating-point formats and all conversion between +a floating-point format and 32-bit and 64-bit signed integers can be tested. +The conversion functions are: + + int32_to_float32 int64_to_float32 + int32_to_float64 int64_to_float32 + int32_to_floatx80 int64_to_floatx80 + int32_to_float128 int64_to_float128 + + float32_to_int32 float32_to_int64 + float32_to_int32 float64_to_int64 + floatx80_to_int32 floatx80_to_int64 + float128_to_int32 float128_to_int64 + + float32_to_float64 float32_to_floatx80 float32_to_float128 + float64_to_float32 float64_to_floatx80 float64_to_float128 + floatx80_to_float32 floatx80_to_float64 floatx80_to_float128 + float128_to_float32 float128_to_float64 float128_to_floatx80 + +These conversions all round according to the current rounding mode as +necessary. Conversions from a smaller to a larger floating-point format are +always exact and so require no rounding. Conversions from 32-bit integers +to double precision or to any larger floating-point format are also exact, +and likewise for conversions from 64-bit integers to extended double and +quadruple precisions. + +ISO/ANSI C requires that conversions to integers be rounded toward zero. +Such conversions can be tested with the following functions that ignore any +rounding mode: + + float32_to_int32_round_to_zero float32_to_int64_round_to_zero + float64_to_int32_round_to_zero float64_to_int64_round_to_zero + floatx80_to_int32_round_to_zero floatx80_to_int64_round_to_zero + float128_to_int32_round_to_zero float128_to_int64_round_to_zero + +TestFloat assumes that conversions from floating-point to integer should +raise the invalid exception if the source value cannot be rounded to a +representable integer of the desired size (32 or 64 bits). If such a +conversion overflows, TestFloat expects the largest integer with the same +sign as the operand to be returned. If the floating-point operand is a NaN, +TestFloat allows either the largest postive or largest negative integer to +be returned. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Standard Arithmetic Functions + +The following standard arithmetic functions can be tested: + + float32_add float32_sub float32_mul float32_div float32_sqrt + float64_add float64_sub float64_mul float64_div float64_sqrt + floatx80_add floatx80_sub floatx80_mul floatx80_div floatx80_sqrt + float128_add float128_sub float128_mul float128_div float128_sqrt + +The extended double-precision (`floatx80') functions can be rounded to +reduced precision under rounding precision control. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Remainder and Round-to-Integer Functions + +For each format, TestFloat can test the IEC/IEEE Standard remainder and +round-to-integer functions. The remainder functions are: + + float32_rem + float64_rem + floatx80_rem + float128_rem + +The round-to-integer functions are: + + float32_round_to_int + float64_round_to_int + floatx80_round_to_int + float128_round_to_int + +The remainder functions are always exact and so do not require rounding. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Comparison Functions + +The following floating-point comparison functions can be tested: + + float32_eq float32_le float32_lt + float64_eq float64_le float64_lt + floatx80_eq floatx80_le floatx80_lt + float128_eq float128_le float128_lt + +The abbreviation `eq' stands for ``equal'' (=); `le' stands for ``less than +or equal'' (<=); and `lt' stands for ``less than'' (<). + +The IEC/IEEE Standard specifies that the less-than-or-equal and less-than +functions raise the invalid exception if either input is any kind of NaN. +The equal functions, for their part, are defined not to raise the invalid +exception on quiet NaNs. For completeness, the following additional +functions can be tested if supported: + + float32_eq_signaling float32_le_quiet float32_lt_quiet + float64_eq_signaling float64_le_quiet float64_lt_quiet + floatx80_eq_signaling floatx80_le_quiet floatx80_lt_quiet + float128_eq_signaling float128_le_quiet float128_lt_quiet + +The `signaling' equal functions are identical to the standard functions +except that the invalid exception should be raised for any NaN input. +Likewise, the `quiet' comparison functions should be identical to their +counterparts except that the invalid exception is not raised for quiet NaNs. + +Obviously, no comparison functions ever require rounding. Any rounding mode +is ignored. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + +------------------------------------------------------------------------------- +Interpreting TestFloat Output + +The ``errors'' reported by TestFloat may or may not really represent errors +in the system being tested. For each test case tried, TestFloat performs +the same floating-point operation for the two implementations being compared +and reports any unexpected difference in the results. The two results could +differ for several reasons: + +-- The IEC/IEEE Standard allows for some variation in how conforming + floating-point behaves. Two implementations can occasionally give + different results without either being incorrect. + +-- The trusted floating-point emulation could be faulty. This could be + because there is a bug in the way the enulation is coded, or because a + mistake was made when the code was compiled for the current system. + +-- TestFloat may not work properly, reporting discrepancies that do not + exist. + +-- Lastly, the floating-point being tested could actually be faulty. + +It is the responsibility of the user to determine the causes for the +discrepancies TestFloat reports. Making this determination can require +detailed knowledge about the IEC/IEEE Standard. Assuming TestFloat is +working properly, any differences found will be due to either the first or +last of these reasons. Variations in the IEC/IEEE Standard that could lead +to false error reports are discussed in the section _Variations_Allowed_by_ +_the_IEC/IEEE_Standard_. + +For each error (or apparent error) TestFloat reports, a line of text +is written to the default output. If a line would be longer than 79 +characters, it is divided. The first part of each error line begins in the +leftmost column, and any subsequent ``continuation'' lines are indented with +a tab. + +Each error reported by `testfloat' is of the form: + + <inputs> soft: <output-from-emulation> syst: <output-from-system> + +The `<inputs>' are the inputs to the operation. Each output is shown as a +pair: the result value first, followed by the exception flags. The `soft' +label stands for ``software'' (or ``SoftFloat''), while `syst' stands for +``system,'' the machine's floating-point. + +For example, two typical error lines could be + + 800.7FFF00 87F.000100 soft: 001.000000 ....x syst: 001.000000 ...ux + 081.000004 000.1FFFFF soft: 001.000000 ....x syst: 001.000000 ...ux + +In the first line, the inputs are `800.7FFF00' and `87F.000100'. The +internal emulation result is `001.000000' with flags `....x', and the +system result is the same but with flags `...ux'. All the items composed of +hexadecimal digits and a single period represent floating-point values (here +single precision). These cases were reported as errors because the flag +results differ. + +In addition to the exception flags, there are seven data types that may +be represented. Four are floating-point types: single precision, double +precision, extended double precision, and quadruple precision. The +remaining three types are 32-bit and 64-bit two's-complement integers and +Boolean values (the results of comparison operations). Boolean values are +represented as a single character, either a `0' or a `1'. 32-bit integers +are written as 8 hexadecimal digits in two's-complement form. Thus, +`FFFFFFFF' is -1, and `7FFFFFFF' is the largest positive 32-bit integer. +64-bit integers are the same except with 16 hexadecimal digits. + +Floating-point values are written in a correspondingly primitive form. +Double-precision values are represented by 16 hexadecimal digits that give +the raw bits of the floating-point encoding. A period separates the 3rd and +4th hexadecimal digits to mark the division between the exponent bits and +fraction bits. Some notable double-precision values include: + + 000.0000000000000 +0 + 3FF.0000000000000 1 + 400.0000000000000 2 + 7FF.0000000000000 +infinity + + 800.0000000000000 -0 + BFF.0000000000000 -1 + C00.0000000000000 -2 + FFF.0000000000000 -infinity + + 3FE.FFFFFFFFFFFFF largest representable number preceding +1 + +The following categories are easily distinguished (assuming the `x's are not +all 0): + + 000.xxxxxxxxxxxxx positive subnormal (denormalized) numbers + 7FF.xxxxxxxxxxxxx positive NaNs + 800.xxxxxxxxxxxxx negative subnormal numbers + FFF.xxxxxxxxxxxxx negative NaNs + +Quadruple-precision values are written the same except with 4 hexadecimal +digits for the sign and exponent and 28 for the fraction. Notable values +include: + + 0000.0000000000000000000000000000 +0 + 3FFF.0000000000000000000000000000 1 + 4000.0000000000000000000000000000 2 + 7FFF.0000000000000000000000000000 +infinity + + 8000.0000000000000000000000000000 -0 + BFFF.0000000000000000000000000000 -1 + C000.0000000000000000000000000000 -2 + FFFF.0000000000000000000000000000 -infinity + + 3FFE.FFFFFFFFFFFFFFFFFFFFFFFFFFFF largest representable number + preceding +1 + +Extended double-precision values are a little unusual in that the leading +significand bit is not hidden as with other formats. When correctly +encoded, the leading significand bit of an extended double-precision value +will be 0 if the value is zero or subnormal, and will be 1 otherwise. +Hence, the same values listed above appear in extended double-precision as +follows (note the leading `8' digit in the significands): + + 0000.0000000000000000 +0 + 3FFF.8000000000000000 1 + 4000.8000000000000000 2 + 7FFF.8000000000000000 +infinity + + 8000.0000000000000000 -0 + BFFF.8000000000000000 -1 + C000.8000000000000000 -2 + FFFF.8000000000000000 -infinity + + 3FFE.FFFFFFFFFFFFFFFF largest representable number preceding +1 + +The representation of single-precision values is unusual for a different +reason. Because the subfields of standard single-precision do not fall +on neat 4-bit boundaries, single-precision outputs are slightly perturbed. +These are written as 9 hexadecimal digits, with a period separating the 3rd +and 4th hexadecimal digits. Broken out into bits, the 9 hexademical digits +cover the single-precision subfields as follows: + + x000 .... .... . .... .... .... .... .... .... sign (1 bit) + .... xxxx xxxx . .... .... .... .... .... .... exponent (8 bits) + .... .... .... . 0xxx xxxx xxxx xxxx xxxx xxxx fraction (23 bits) + +As shown in this schematic, the first hexadecimal digit contains only +the sign, and will be either `0' or `8'. The next two digits give the +biased exponent as an 8-bit integer. This is followed by a period and +6 hexadecimal digits of fraction. The most significant hexadecimal digit +of the fraction can be at most a `7'. + +Notable single-precision values include: + + 000.000000 +0 + 07F.000000 1 + 080.000000 2 + 0FF.000000 +infinity + + 800.000000 -0 + 87F.000000 -1 + 880.000000 -2 + 8FF.000000 -infinity + + 07E.7FFFFF largest representable number preceding +1 + +Again, certain categories are easily distinguished (assuming the `x's are +not all 0): + + 000.xxxxxx positive subnormal (denormalized) numbers + 0FF.xxxxxx positive NaNs + 800.xxxxxx negative subnormal numbers + 8FF.xxxxxx negative NaNs + +Lastly, exception flag values are represented by five characters, one +character per flag. Each flag is written as either a letter or a period +(`.') according to whether the flag was set or not by the operation. A +period indicates the flag was not set. The letter used to indicate a set +flag depends on the flag: + + v invalid flag + z division-by-zero flag + o overflow flag + u underflow flag + x inexact flag + +For example, the notation `...ux' indicates that the underflow and inexact +exception flags were set and that the other three flags (invalid, division- +by-zero, and overflow) were not set. The exception flags are always shown +following the value returned as the result of the operation. + +The output from `testsoftfloat' is of the same form, except that the results +are labeled `true' and `soft': + + <inputs> true: <simple-software-result> soft: <SoftFloat-result> + +The ``true'' result is from the simpler, slower software floating-point, +which, although not necessarily correct, is more likely to be right than +the SoftFloat (`soft') result. + + +------------------------------------------------------------------------------- +Variations Allowed by the IEC/IEEE Standard + +The IEC/IEEE Standard admits some variation among conforming +implementations. Because TestFloat expects the two implementations being +compared to deliver bit-for-bit identical results under most circumstances, +this leeway in the standard can result in false errors being reported if +the two implementations do not make the same choices everywhere the standard +provides an option. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Underflow + +The standard specifies that the underflow exception flag is to be raised +when two conditions are met simultaneously: (1) _tininess_ and (2) _loss_ +_of_accuracy_. A result is tiny when its magnitude is nonzero yet smaller +than any normalized floating-point number. The standard allows tininess to +be determined either before or after a result is rounded to the destination +precision. If tininess is detected before rounding, some borderline cases +will be flagged as underflows even though the result after rounding actually +lies within the normal floating-point range. By detecting tininess after +rounding, a system can avoid some unnecessary signaling of underflow. + +Loss of accuracy occurs when the subnormal format is not sufficient +to represent an underflowed result accurately. The standard allows +loss of accuracy to be detected either as an _inexact_result_ or as a +_denormalization_loss_. If loss of accuracy is detected as an inexact +result, the underflow flag is raised whenever an underflowed quantity +cannot be exactly represented in the subnormal format (that is, whenever the +inexact flag is also raised). A denormalization loss, on the other hand, +occurs only when the subnormal format is not able to represent the result +that would have been returned if the destination format had infinite range. +Some underflowed results are inexact but do not suffer a denormalization +loss. By detecting loss of accuracy as a denormalization loss, a system can +once again avoid some unnecessary signaling of underflow. + +The `-tininessbefore' and `-tininessafter' options can be used to control +whether TestFloat expects tininess on underflow to be detected before or +after rounding. (See _TestFloat_Options_ below.) One or the other is +selected as the default when TestFloat is compiled, but these command +options allow the default to be overridden. + +Most (possibly all) systems detect loss of accuracy as an inexact result. +The current version of TestFloat can only test for this case. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +NaNs + +The IEC/IEEE Standard gives the floating-point formats a large number of +NaN encodings and specifies that NaNs are to be returned as results under +certain conditions. However, the standard allows an implementation almost +complete freedom over _which_ NaN to return in each situation. + +By default, TestFloat does not check the bit patterns of NaN results. When +the result of an operation should be a NaN, any NaN is considered as good +as another. This laxness can be overridden with the `-checkNaNs' option. +(See _TestFloat_Options_ below.) In order for this option to be sensible, +TestFloat must have been compiled so that its internal floating-point +implementation (SoftFloat) generates the proper NaN results for the system +being tested. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +Conversions to Integer + +Conversion of a floating-point value to an integer format will fail if the +source value is a NaN or if it is too large. The IEC/IEEE Standard does not +specify what value should be returned as the integer result in these cases. +Moreover, according to the standard, the invalid exception can be raised or +an unspecified alternative mechanism may be used to signal such cases. + +TestFloat assumes that conversions to integer will raise the invalid +exception if the source value cannot be rounded to a representable integer. +When the conversion overflows, TestFloat expects the largest integer with +the same sign as the operand to be returned. If the floating-point operand +is a NaN, TestFloat allows either the largest postive or largest negative +integer to be returned. The current version of TestFloat provides no means +to alter these conventions. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + +------------------------------------------------------------------------------- +TestFloat Options + +The `testfloat' (and `testsoftfloat') program accepts several command +options. If mutually contradictory options are given, the last one has +priority. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-help + +The `-help' option causes a summary of program usage to be written, after +which the program exits. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-list + +The `-list' option causes a list of testable functions to be written, +after which the program exits. Some machines do not implement all of the +functions TestFloat can test, plus it may not be possible to test functions +that are inaccessible from the C language. + +The `testsoftfloat' program does not have this option. All SoftFloat +functions can be tested by `testsoftfloat'. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-level <num> + +The `-level' option sets the level of testing. The argument to `-level' can +be either 1 or 2. The default is level 1. Level 2 performs many more tests +than level 1. Testing at level 2 can take as much as a day (even longer for +`testsoftfloat'), but can reveal bugs not found by level 1. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-errors <num> + +The `-errors' option instructs TestFloat to report no more than the +specified number of errors for any combination of function, rounding mode, +etc. The argument to `-errors' must be a nonnegative decimal number. Once +the specified number of error reports has been generated, TestFloat ends the +current test and begins the next one, if any. The default is `-errors 20'. + +Against intuition, `-errors 0' causes TestFloat to report every error it +finds. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-errorstop + +The `-errorstop' option causes the program to exit after the first function +for which any errors are reported. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-forever + +The `-forever' option causes a single operation to be repeatedly tested. +Only one rounding mode and/or rounding precision can be tested in a single +invocation. If not specified, the rounding mode defaults to nearest/even. +For extended double-precision operations, the rounding precision defaults +to full extended double precision. The testing level is set to 2 by this +option. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-checkNaNs + +The `-checkNaNs' option causes TestFloat to verify the bitwise correctness +of NaN results. In order for this option to be sensible, TestFloat must +have been compiled so that its internal floating-point implementation +(SoftFloat) generates the proper NaN results for the system being tested. + +This option is not available to `testsoftfloat'. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-precision32, -precision64, -precision80 + +For extended double-precision functions affected by rounding precision +control, the `-precision32' option restricts testing to only the cases +in which rounding precision is equivalent to single precision. The other +rounding precision options are not tested. Likewise, the `-precision64' +and `-precision80' options fix the rounding precision equivalent to double +precision or extended double precision, respectively. These options are +ignored for functions not affected by rounding precision control. + +These options are not available if extended double precision is not +supported by the machine or if extended double precision functions cannot be +tested. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-nearesteven, -tozero, -down, -up + +The `-nearesteven' option restricts testing to only the cases in which the +rounding mode is nearest/even. The other rounding mode options are not +tested. Likewise, `-tozero' forces rounding to zero; `-down' forces +rounding down; and `-up' forces rounding up. These options are ignored for +functions that are exact and thus do not round. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +-tininessbefore, -tininessafter + +The `-tininessbefore' option indicates that the system detects tininess +on underflow before rounding. The `-tininessafter' option indicates that +tininess is detected after rounding. TestFloat alters its expectations +accordingly. These options override the default selected when TestFloat was +compiled. Choosing the wrong one of these two options should cause error +reports for some (not all) functions. + +For `testsoftfloat', these options operate more like the rounding precision +and rounding mode options, in that they restrict the tests performed by +`testsoftfloat'. By default, `testsoftfloat' tests both cases for any +function for which there is a difference. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + +------------------------------------------------------------------------------- +Function Sets + +Just as TestFloat can test an operation for all four rounding modes in +sequence, multiple operations can be tested with a single invocation of +TestFloat. Three sets are recognized: `-all1', `-all2', and `-all'. The +set `-all1' comprises all one-operand functions; `-all2' is all two-operand +functions; and `-all' is all functions. A function set can be used in place +of a function name in the TestFloat command line, such as + + testfloat [<option>...] -all + + +------------------------------------------------------------------------------- +Contact Information + +At the time of this writing, the most up-to-date information about +TestFloat and the latest release can be found at the Web page `http:// +HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'. + + |