Berkeley TestFloat Release 3e: testfloat

John R. Hauser
2018 January 20

Overview

The testfloat program tests an implementation of floating-point arithmetic for conformity to the IEEE Standard for Binary Floating-Point Arithmetic. testfloat is part of the Berkeley TestFloat package, a small collection of programs for performing such tests. For general information about TestFloat, see file TestFloat-general.html.

The testfloat program is an all-in-one tool for testing floating-point arithmetic. It generates test operand values, invokes a floating-point operation with the generated operands, and examines the corresponding computed results, reporting unexpected results as likely errors. While the processes of generating inputs and examining results are generic, a particular build of testfloat is limited to testing only the one implementation of floating-point it has been compiled to invoke. For example, while one instance of testfloat might be compiled to execute a computer’s hardware instruction for floating-point addition, a different version might be compiled to call a subroutine called myAddFloat that is linked into the testfloat program. To test a new implementation of floating-point (a new set of machine instructions or a new set of subroutines), a new testfloat must be compiled containing the code needed to invoke the new floating-point.

The default build of testfloat assumes that C types float and double are 32-bit and 64-bit binary floating-point types conforming to the IEEE Standard, and tests the C operations of +, -, *, /, type conversions, etc. This tests the floating-point arithmetic seen by C programs. Depending on the compiler and the options selected during compilation, this may or may not be the same as the computer’s floating-point hardware, if any.

The testfloat program will ordinarily test an operation for all five rounding modes defined by the IEEE Floating-Point Standard, one after the other, plus possibly a sixth mode, round to odd (depending on the options selected when testfloat was compiled). 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 double-extended-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 command-line options.

For more about the operation of testfloat and how to interpret its output, refer to TestFloat-general.html.

Command Syntax

The testfloat program is executed as a command with this syntax:

testfloat [<option>...] <function>

Options

The testfloat 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 operations to be written, after which the program exits. An operation is testable by testfloat if the program knows some way to invoke the operation.

-seed <num>

The -seed option sets the seed for the pseudo-random number generator used for generating test cases. The argument to -seed is a nonnegative integer. Executing the same compiled testfloat program with the same arguments (including the same pseudo-random number seed) should always perform the same sequence of tests, whereas changing the pseudo-random number seed should result in a different sequence of tests. The default seed number is 1.

-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 and thus 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 operation, rounding mode, etc. The argument to -errors must be a nonnegative decimal integer. 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 operation 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 execution. If not specified, the rounding mode defaults to nearest/even. For 80-bit double-extended-precision operations, the rounding precision defaults to full double-extended 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 reference implementation of floating-point (Berkeley SoftFloat) generates the proper NaN results for the system being tested.

-checkInvInts

The -checkInvInts option causes testfloat to verify the bitwise correctness of integer results of invalid operations. In order for this option to be sensible, testfloat must have been compiled so that its internal reference implementation of floating-point (Berkeley SoftFloat) generates the proper integer results for the system being tested.

-checkAll

Enables both -checkNaNs and -checkInvInts.

-precision32, -precision64, -precision80

For 80-bit double-extended-precision operations affected by rounding precision control, the -precision32 option restricts testing to only the cases in which the rounding precision is 32 bits, equivalent to 32-bit single-precision. The other rounding precision choices are not tested. Likewise, -precision64 fixes the rounding precision to 64 bits, equivalent to 64-bit double-precision, and -precision80 fixes the rounding precision to the full 80 bits of the double-extended-precision format. All these options are ignored for operations not affected by rounding precision control.

The precision-control options may not be supported at all if no double-extended-precision operations are testable.

-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax, -rodd

The -rnear_even option restricts testing to only the cases in which the rounding mode is nearest/even. The other rounding mode choices are not tested. Likewise, -rnear_maxMag forces rounding to nearest/maximum magnitude (nearest-away), -rminMag forces rounding to minimum magnitude (toward zero), -rmin forces rounding to minimum (down, toward negative infinity), -rmax forces rounding to maximum (up, toward positive infinity), and -rodd, if supported, forces rounding to odd. These options are ignored for operations that are exact and thus do not round, or that have the rounding mode included in the function name (such as f32_to_i32_r_near_maxMag).

-tininessbefore, -tininessafter

The -tininessbefore option indicates that the floating-point implementation being tested detects tininess on underflow before rounding. The -tininessafter option indicates that tininess is detected after rounding. The testfloat program 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 (but not all) operations.

Function Sets

Just as testfloat can test an operation for all five or six rounding modes in sequence, multiple operations can be tested with a single execution of testfloat. Two sets are recognized: -all1 and -all2. The set -all1 is all one-operand operations, while -all2 is all two-operand operations. A function set is used in place of an operation name in the testfloat command line, such as

testfloat [<option>...] -all1