`testsoftfloat`

John R. Hauser

2017 August 18

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

The `testsoftfloat`

program is executed as a command with this
syntax:

Square brackets (testsoftfloat [<option>...] <function>

`[ ]`

) 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.
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

`-level <`*num*>

The `-level`

option sets the level of testing.
The argument to `-level`

can be either 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`

`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

`-precision32, -precision64, -precision80`

For `-precision32`

option restricts
testing to only the cases in which the rounding precision is
`-precision64`

fixes the rounding precision to
`-precision80`

fixes the rounding precision to the full

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

operand
(specifying whether the *exact**inexact* exception flag may be raised) is
`false`

.
Likewise, the `-exact`

option restricts testing to only the cases
for which the

operand is *exact*`true`

.

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

and *roundingMode*

arguments are
ignored.
(Such arguments specify the rounding mode and whether the *exact**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`

.