# Berkeley TestFloat Release 3e: `testsoftfloat`

John R. Hauser
2018 January 20

## Overview

The `testsoftfloat` program tests that a build of the Berkeley SoftFloat library conforms to the IEEE Standard for Binary Floating-Point Arithmetic as expected. Program `testsoftfloat` is part of the Berkeley TestFloat package, a small collection of programs for performing such tests. For general information about TestFloat, as well as for basics about the operation of `testsoftfloat` and how to interpret its output, see file `TestFloat-general.html`.

Note that, even if there are no bugs in the source code for SoftFloat (not guaranteed), a build of SoftFloat might still fail due to an issue with the build process, such as an incompatible compiler option or a compiler bug.

The `testsoftfloat` program will ordinarily test a function 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 `testsoftfloat` was compiled). If an operation is not supposed to require rounding, it will by default be tested only with the rounding mode set to `near_even` (nearest/even). In the same way, if an operation is affected by the way in which underflow tininess is detected, `testsoftfloat` tests the function with tininess detected both before rounding and after rounding. For 80-bit double-extended-precision operations affected by rounding precision control, `testsoftfloat` also tests the function for all three rounding precision modes, one after the other. Testing can be limited to a single rounding mode, a single tininess mode, and/or a single rounding precision with appropriate command-line options.

## Command Syntax

The `testsoftfloat` program is executed as a command with this syntax:

>     testsoftfloat [<option>...] <function>

Square brackets (`[ ]`) denote optional arguments, `<option>` is a supported option, and `<function>` is the name of either a testable function or a function set. The available options and function sets are documented below. If `testsoftfloat` is executed without any arguments, a summary of usage is written.

## Options

The `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.

### `-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 `testsoftfloat` 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 `testsoftfloat` 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 integer. Once the specified number of error reports has been generated, `testsoftfloat` ends the current test and begins the next one, if any. The default is `-errors` `20`.

Against intuition, `-errors` `0` causes `testsoftfloat` 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 function 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 functions, the rounding precision defaults to full double-extended precision. The testing level is set to 2 by this option.

### `-precision32, -precision64, -precision80`

For 80-bit double-extended-precision funcions 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.

### `-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.

### `-tininessbefore, -tininessafter`

The `-tininessbefore` option restricts testing to only the cases in which tininess on underflow is detected before rounding. Likewise, `-tininessafter` restricts testing to only the cases in which tininess on underflow is detected after rounding.

### `-notexact, -exact`

For functions that round to an integer (conversions to integer types and the `roundToInt` functions), the `-notexact` option restricts testing to only the cases for which the `exact` operand (specifying whether the inexact exception flag may be raised) is `false`. Likewise, the `-exact` option restricts testing to only the cases for which the `exact` operand is `true`.

## Function Sets

Just as `testsoftfloat` can test a function for all five or six rounding modes in sequence, multiple functions can be tested with a single execution of `testsoftfloat`. 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 a function name in the `testsoftfloat` command line, such as

>     testsoftfloat [<option>...] -all1

For the purpose of deciding the number of operands of an operation, any `roundingMode` and `exact` arguments are ignored. (Such arguments specify the rounding mode and whether the inexact exception flag may be raised, respectively.) Thus, functions that convert to integer type and the `roundToInt` functions are included in the set of one-operand operations tested by `-all1`.