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 -errors -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 [