# Berkeley TestFloat Release 3e: `testfloat_ver`

John R. Hauser
2018 January 20

## Overview

The `testfloat_ver` program accepts test-case results obtained from exercising an implementation of floating-point arithmetic and verifies that those results conform to the IEEE Standard for Binary Floating-Point Arithmetic. `testfloat_ver` 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`.

A single execution of `testfloat_ver` verifies results for only a single floating-point operation and associated options. The `testfloat_ver` program must be repeatedly executed to verify results for each operation to be tested.

The test cases to be verified are read by `testfloat_ver` from standard input. This input will typically be piped from another program that, for each test case, invokes the floating-point operation and writes out the results. The format of `testfloat_ver`’s input is raw hexadecimal text, described in the section below titled Input Format.

For each test case given to it, `testfloat_ver` examines the computed results and reports any unexpected results as likely errors. For more about the operation of `testfloat_ver` and how to interpret its output, refer to `TestFloat-general.html`.

## Command Syntax

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

>     testfloat_ver [<option>...] <function>

Square brackets (`[ ]`) denote optional arguments, `<option>` is a supported option, and `<function>` is the name of a testable operation. The available options are documented below. The testable operation names are listed in `TestFloat-general.html`. If `testfloat_ver` is executed without any arguments, a summary of usage is written.

## Options

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

### `-errors <num>`

The `-errors` option instructs `testfloat_ver` to report no more than the specified number of errors. The argument to `-errors` must be a nonnegative decimal integer. Once the specified number of error reports has been generated, the program exits. The default is `-errors` `20`.

Against intuition, `-errors` `0` causes `testfloat_ver` to continue for any number of errors.

### `-checkNaNs`

The `-checkNaNs` option causes `testfloat_ver` to verify the bitwise correctness of NaN results. In order for this option to be sensible, `testfloat_ver` 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_ver` to verify the bitwise correctness of integer results of invalid operations. In order for this option to be sensible, `testfloat_ver` 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`

When `<function>` is an 80-bit double-extended-precision operation affected by rounding precision control, the `-precision32` option indicates that the rounding precision should be 32 bits, equivalent to 32-bit single-precision. Likewise, `-precision64` indicates that the rounding precision should be 64 bits, equivalent to 64-bit double-precision, and `-precision80` indicates that the rounding precision should be the full 80 bits of the double-extended-precision format. All these options are ignored for operations not affected by rounding precision control. When rounding precision is applicable but not specified, the default assumption is the full 80 bits, same as `-precision80`.

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

When `<function>` is an operation that requires rounding, the `-rnear_even` option indicates that rounding should be to nearest/even, `-rnear_maxMag` indicates rounding to nearest/maximum magnitude (nearest-away), `-rminMag` indicates rounding to minimum magnitude (toward zero), `-rmin` indicates rounding to minimum (down, toward negative infinity), `-rmax` indicates rounding to maximum (up, toward positive infinity), and `-rodd`, if supported, indicates rounding to odd. These options are ignored for operations that are exact and thus do not round. When rounding mode is relevant but not specified, the default assumption is rounding to nearest/even, same as `-rnear_even`.

### `-tininessbefore, -tininessafter`

When `<function>` is an operation that requires rounding, the `-tininessbefore` option indicates that tininess on underflow should be detected before rounding, while `-tininessafter` indicates that tininess on underflow should be detected after rounding. These options are ignored for operations that are exact and thus do not round. When the method of tininess detection matters but is not specified, the default assumption is that tininess should be detected after rounding, same as `-tininessafter`.

### `-notexact, -exact`

When `<function>` is an operation that rounds to an integer (either conversion to an integer type or a `roundToInt` operation), the `-notexact` option indicates that the inexact exception flag should never be raised, while `-exact` indicates that the inexact exception flag should be raised when the result is inexact. For other operations, these options are ignored. If neither option is specified, the default assumption is that the inexact exception flag should not be raised when rounding to an integer, same as `-notexact`.

## Input Format

For a given `<function>` argument, the input format expected by `testfloat_ver` is the same as the output generated by program `testfloat_gen` for the same argument.

Input to `testfloat_ver` is expected to be text, with each line containing the data for one test case. The number of input lines thus equals the number of test cases. A single test case is organized as follows: first are the operands for the operation, next is the result value obtained, and last is a number indicating the exception flags that were raised. These values are all expected to be provided as raw hexadecimal numbers separated on the line by spaces. For example, for the command

>     testfloat_ver f64_add

valid input could include these lines:

>     3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01
>     41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01
>     7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05
>     3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01
>     ...

On each line above, the first two hexadecimal numbers represent the 64-bit floating-point operands, the third hexadecimal number is the 64-bit floating-point result of the operation (the sum), and the last hexadecimal number gives the exception flags that were raised by the operation.

Note that, for floating-point values, the sign and exponent are at the most-significant end of the number. Thus, for the first number on the first line above, the leading hexadecimal digits `3F9` are the sign and encoded exponent of the 64-bit floating-point value, and the remaining digits are the encoded significand.

Exception flags are encoded with one bit per flag as follows:

> bit 0`` | inexact exception
> bit 1 | underflow exception
> bit 2 | overflow exception
> bit 3 | infinite exception (“divide by zero”)
> bit 4 | invalid exception