diff options
Diffstat (limited to 'doc/testsoftfloat.html')
| -rw-r--r-- | doc/testsoftfloat.html | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/testsoftfloat.html b/doc/testsoftfloat.html new file mode 100644 index 0000000..49215de --- /dev/null +++ b/doc/testsoftfloat.html @@ -0,0 +1,229 @@ + +<HTML> + +<HEAD> +<TITLE>testsoftfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>testsoftfloat</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>testsoftfloat</CODE> program tests that a build of the Berkeley +SoftFloat library conforms to the IEEE Standard for Binary Floating-Point +Arithmetic as expected. +Program <CODE>testsoftfloat</CODE> 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 <CODE>testsoftfloat</CODE> and how to interpret its output, see +file +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +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. +</P> + +<P> +The <CODE>testsoftfloat</CODE> program will ordinarily test a function for all +rounding modes defined by the IEEE Floating-Point Standard, one after the +other. +If an operation is not supposed to require rounding, it will by default be +tested only with the rounding mode set to <CODE>near_even</CODE> +(nearest/even). +In the same way, if an operation is affected by the way in which underflow +tininess is detected, <CODE>testsoftfloat</CODE> tests the function with +tininess detected both before rounding and after rounding. +For <NOBR>80-bit</NOBR> double-extended-precision operations affected by +rounding precision control, <CODE>testsoftfloat</CODE> 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. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testsoftfloat</CODE> program is executed as a command with this +syntax: +<PRE> + testsoftfloat [<option>...] <function> +</PRE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, +<CODE><option></CODE> is a supported option, and +<CODE><function></CODE> is the name of either a testable function or a +function set. +The available options and function sets are documented below. +If <CODE>testsoftfloat</CODE> is executed without any arguments, a summary of +usage is written. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testsoftfloat</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>-level <num></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 <num></CODE></H3> + +<P> +The <CODE>-errors</CODE> option instructs <CODE>testsoftfloat</CODE> to report +no more than the specified number of errors for any combination of function, +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>testsoftfloat</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>testsoftfloat</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 +function for which any errors are reported. +</P> + +<H3><CODE>-forever</CODE></H3> + +<P> +The <CODE>-forever</CODE> 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 <NOBR>80-bit</NOBR> double-extended-precision functions, the rounding +precision defaults to full double-extended precision. +The testing level is set to 2 by this option. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +For <NOBR>80-bit</NOBR> double-extended-precision funcions 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> + +<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 restricts testing to only the cases in +which tininess on underflow is detected before rounding. +Likewise, <CODE>-tininessafter</CODE> restricts testing to only the cases in +which tininess on underflow is detected after rounding. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +For functions that round to an integer (conversions to integer types and the +<CODE>roundToInt</CODE> functions), the <CODE>-notexact</CODE> option restricts +testing to only the cases for which the <CODE><I>exact</I></CODE> operand +(specifying whether the <I>inexact</I> exception flag may be raised) is +<CODE>false</CODE>. +Likewise, the <CODE>-exact</CODE> option restricts testing to only the cases +for which the <CODE><I>exact</I></CODE> operand is <CODE>true</CODE>. +</P> + + +<H2>Function Sets</H2> + +<P> +Just as <CODE>testsoftfloat</CODE> can test a function for all five rounding +modes in sequence, multiple functions can be tested with a single execution of +<CODE>testsoftfloat</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 a function name in the +<CODE>testsoftfloat</CODE> command line, such as +<PRE> + testsoftfloat [<option>...] -all1 +</PRE> +</P> + +<P> +For the purpose of deciding the number of operands of an operation, any +<CODE><I>roundingMode</I></CODE> and <CODE><I>exact</I></CODE> arguments are +ignored. +(Such arguments specify the rounding mode and whether the <I>inexact</I> +exception flag may be raised, respectively.) +Thus, functions that convert to integer type and the <CODE>roundToInt</CODE> +functions are included in the set of one-operand operations tested by +<CODE>-all1</CODE>. +</P> + + +</BODY> + |