
<HTML>

<HEAD>
<TITLE>testfloat</TITLE>
</HEAD>

<BODY>

<H1>Berkeley TestFloat Release 3: <CODE>testfloat</CODE></H1>

<P>
John R. Hauser<BR>
2014 ______<BR>
</P>

<P>
*** CONTENT DONE.
</P>

<P>
*** REPLACE QUOTATION MARKS.
<BR>
*** REPLACE APOSTROPHES.
<BR>
*** REPLACE EM DASH.
</P>


<H2>Overview</H2>

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

<P>
The <CODE>testfloat</CODE> 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 <CODE>testfloat</CODE> is limited to testing only the one
implementation of floating-point it has been compiled to invoke.
For example, while one instance of <CODE>testfloat</CODE> 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
<CODE>myAddFloat</CODE> that is linked into the <CODE>testfloat</CODE> program.
To test a new implementation of floating-point (a new set of machine
instructions or a new set of subroutines), a new <CODE>testfloat</CODE> must be
compiled containing the code needed to invoke the new floating-point.
</P>

<P>
The default build of <CODE>testfloat</CODE> assumes that C types
<CODE>float</CODE> and <CODE>double</CODE> are <NOBR>32-bit</NOBR> and
<NOBR>64-bit</NOBR> binary floating-point types conforming to the IEEE
Standard, and tests the C operations of <CODE>+</CODE>, <CODE>-</CODE>,
<CODE>*</CODE>, <CODE>/</CODE>, 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.
</P>

<P>
The <CODE>testfloat</CODE> program will ordinarily test an operation for all
rounding modes defined by the IEEE Floating-Point Standard, one after the
other.
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, <CODE>testfloat</CODE> 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.
</P>

<P>
For more about the operation of <CODE>testfloat</CODE> and how to interpret its
output, refer to
<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
</P>


<H2>Command Syntax</H2>

<P>
The <CODE>testfloat</CODE> program is executed as a command with this syntax:
<PRE>
     testfloat [&lt;option&gt;...] &lt;function&gt;
</PRE>
Square brackets (<CODE>[ ]</CODE>) denote optional arguments,
<CODE>&lt;option&gt;</CODE> is a supported option, and
<CODE>&lt;function&gt;</CODE> is the name of either a testable operation or a
function set.
The available options and function sets are documented below.
The <CODE>-list</CODE> option can be used to obtain a list of all testable
operations for a given build of <CODE>testfloat</CODE>.
If <CODE>testfloat</CODE> is executed without any arguments, a summary of usage
is written.
</P>


<H2>Options</H2>

<P>
The <CODE>testfloat</CODE> program accepts several command options.
If mutually contradictory options are given, the last one has priority.
</P>

<H3><CODE>-help</CODE></H3>

<P>
The <CODE>-help</CODE> option causes a summary of program usage to be written,
after which the program exits.
</P>

<H3><CODE>-list</CODE></H3>

<P>
The <CODE>-list</CODE> option causes a list of testable operations to be
written, after which the program exits.
The set of testable operations is just the set of operations that this build of
<CODE>testfloat</CODE> has some way to invoke for testing.
</P>

<H3><CODE>-level &lt;num&gt;</CODE></H3>

<P>
The <CODE>-level</CODE> option sets the level of testing.
The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>.
The default is <NOBR>level 1</NOBR>.
Level 2 performs many more tests than <NOBR>level 1</NOBR> and thus can reveal
bugs not found by <NOBR>level 1</NOBR>.
</P>

<H3><CODE>-errors &lt;num&gt;</CODE></H3>

<P>
The <CODE>-errors</CODE> option instructs <CODE>testfloat</CODE> to report no
more than the specified number of errors for any combination of operation,
rounding mode, etc.
The argument to <CODE>-errors</CODE> must be a nonnegative decimal integer.
Once the specified number of error reports has been generated,
<CODE>testfloat</CODE> ends the current test and begins the next one, if any.
The default is <NOBR><CODE>-errors</CODE> <CODE>20</CODE></NOBR>.
</P>

<P>
Against intuition, <NOBR><CODE>-errors</CODE> <CODE>0</CODE></NOBR> causes
<CODE>testfloat</CODE> to report every error it finds.
</P>

<H3><CODE>-errorstop</CODE></H3>

<P>
The <CODE>-errorstop</CODE> option causes the program to exit after the first
operation for which any errors are reported.
</P>

<H3><CODE>-forever</CODE></H3>

<P>
The <CODE>-forever</CODE> 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 <NOBR>80-bit</NOBR> double-extended-precision operations, the rounding
precision defaults to full double-extended precision.
The testing level is set to 2 by this option.
</P>

<H3><CODE>-checkNaNs</CODE></H3>

<P>
The <CODE>-checkNaNs</CODE> option causes <CODE>testfloat</CODE> to verify the
bitwise correctness of NaN results.
In order for this option to be sensible, <CODE>testfloat</CODE> must have been
compiled so that its internal reference implementation of floating-point
(SoftFloat) generates the proper NaN results for the system being tested.
</P>

<H3><CODE>-precision32, -precision64, -precision80</CODE></H3>

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

<P>
The precision-control options may not be accepted at all if no
double-extended-precision operations are testable.
</P>

<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3>

<P>
The <CODE>-rnear_even</CODE> option restricts testing to only the cases in
which the rounding mode is nearest/even.
The other rounding mode choices are not tested.
Likewise, <CODE>-rnear_maxMag</CODE> forces rounding to nearest/maximum
magnitude (nearest-away), <CODE>-rminMag</CODE> forces rounding to minimum
magnitude (toward zero), <CODE>-rmin</CODE> forces rounding to minimum (down,
toward negative infinity), and <CODE>-rmax</CODE> forces rounding to maximum
(up, toward positive infinity).
These options are ignored for operations that are exact and thus do not round.
</P>

<H3><CODE>-tininessbefore, -tininessafter</CODE></H3>

<P>
The <CODE>-tininessbefore</CODE> option indicates that the floating-point
implementation being tested detects tininess on underflow before rounding.
The <CODE>-tininessafter</CODE> option indicates that tininess is detected
after rounding.
The <CODE>testfloat</CODE> program alters its expectations accordingly.
These options override the default selected when <CODE>testfloat</CODE> was
compiled.
Choosing the wrong one of these two options should cause error reports for some
(but not all) operations.
</P>


<H2>Function Sets</H2>

<P>
Just as <CODE>testfloat</CODE> can test an operation for all five rounding
modes in sequence, multiple operations can be tested with a single execution of
<CODE>testfloat</CODE>.
Two sets are recognized:  <CODE>-all1</CODE> and <CODE>-all2</CODE>.
The set <CODE>-all1</CODE> comprises all one-operand operations, while
<CODE>-all2</CODE> is all two-operand operations.
A function set is used in place of an operation name in the
<CODE>testfloat</CODE> command line, such as
<PRE>
     testfloat [&lt;option&gt;...] -all1
</PRE>
</P>


</BODY>