diff options
Diffstat (limited to 'doc/testfloat_gen.html')
| -rw-r--r-- | doc/testfloat_gen.html | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/doc/testfloat_gen.html b/doc/testfloat_gen.html new file mode 100644 index 0000000..43e6d20 --- /dev/null +++ b/doc/testfloat_gen.html @@ -0,0 +1,341 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat_gen</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>testfloat_gen</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_gen</CODE> program generates test cases for testing that an +implementation of floating-point arithmetic conforms to the IEEE Standard for +Binary Floating-Point Arithmetic. +<CODE>testfloat_gen</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> +A single execution of <CODE>testfloat_gen</CODE> generates test cases for only +a single floating-point operation and associated options. +The <CODE>testfloat_gen</CODE> program must be repeatedly executed to generate +test cases for each operation to be tested. +</P> + +<P> +<CODE>testfloat_gen</CODE> writes the test cases it generates to standard +output. +This output can either be captured in a file through redirection, or be piped +to another program that exercises a floating-point operation using the test +cases as they are supplied. +Depending on use, the total output from <CODE>testfloat_gen</CODE> can be +large, so piping to another program may be the best choice to avoid consuming +inordinate file space. +The format of <CODE>testfloat_gen</CODE>'s output is raw hexadecimal text, +described in the section below titled <I>Output Format</I>. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testfloat_gen</CODE> program is executed as a command in one of these +forms: +<PRE> + testfloat_gen [<option>...] <type> + testfloat_gen [<option>...] <function> +</PRE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, and +<CODE><option></CODE> is a supported option, documented below. +A <CODE>testfloat_gen</CODE> command expects either a <CODE><type></CODE> +specifying the type and number of output or a <CODE><function></CODE> +naming a floating-point operation. +If <CODE>testfloat_gen</CODE> is executed without any arguments, a summary of +usage is written. +</P> + +<P> +A <CODE><type></CODE> can be one of the following: +<BLOCKQUOTE> +<TABLE> +<TR> +<TD><CODE>ui32</CODE></TD> +<TD>unsigned <NOBR>32-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>ui64</CODE></TD> +<TD>unsigned <NOBR>64-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>i32</CODE></TD> +<TD>signed <NOBR>32-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>i64</CODE></TD> +<TD>signed <NOBR>64-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>f32 [<num>]</CODE></TD> +<TD>one or more <NOBR>32-bit</NOBR> single-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>f64 [<num>]</CODE></TD> +<TD>one or more <NOBR>64-bit</NOBR> double-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>extF80 [<num>] </CODE></TD> +<TD>one or more <NOBR>80-bit</NOBR> double-extended-precision floating-point +values</TD> +</TR> +<TR> +<TD><CODE>f128 [<num>]</CODE></TD> +<TD>one or more <NOBR>128-bit</NOBR> quadruple-precision floating-point +values</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +Optional <CODE><num></CODE> is one of 1, 2, <NOBR>or 3</NOBR>. +If a <CODE><type></CODE> is given without <CODE><num></CODE> (such +as <CODE>ui32</CODE> or <CODE>f64</CODE>), <CODE>testfloat_gen</CODE> outputs a +list of values of the specified type, one value per line, appropriate for +testing a floating-point operation with exactly one operand of the given type. +If a floating-point type and number are given (such as +<NOBR><CODE>f32</CODE> <CODE>2</CODE></NOBR> or +<NOBR><CODE>extF80</CODE> <CODE>1</CODE></NOBR>), <CODE>testfloat_gen</CODE> +outputs the specified number of values per line, appropriate for testing a +floating-point operation with that number of operands. +Although the exact operation being tested is not specified, the test cases +output by <CODE>testfloat_gen</CODE> cover all standard floating-point +operations, to the degree explained in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +If a <CODE><function></CODE> operation name is given, then each line of +output from <CODE>testfloat_gen</CODE> contains not only the operands for that +operation (as would be generated by an appropriate <CODE><type></CODE> +argument) but also the expected results as determined by +<CODE>testfloat_gen</CODE>'s internal floating-point emulation (SoftFloat). +The available operation names are listed in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +In all cases, floating-point operations have two results: +first, a value, which may be floating-point, integer, or Boolean, and, second, +the floating-point exception flags raised by the operation. +If the output from a tested floating-point operation does not match the +expected output specified by <CODE>testfloat_gen</CODE>, this may or may not +indicate an error in the floating-point operation. +For further explanation, see +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>, +especially the section titled <I>Variations Allowed by the IEEE Floating-Point +Standard</I>. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testfloat_gen</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>-prefix <text></CODE></H3> + +<P> +The <CODE>-prefix</CODE> option causes <CODE>testfloat_gen</CODE> to write the +supplied text argument verbatim as the first line of output before any test +cases. +This can be used, for example, to indicate to a downstream program what kind of +test to perform for the test cases that follow. +</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>. +<NOBR>Level 2</NOBR> causes many more test cases to be generated, with better +coverage, than <NOBR>level 1</NOBR>. +</P> + +<H3><CODE>-n <num></CODE></H3> + +<P> +Option <CODE>-n</CODE> specifies the number of test cases to generate. +For each <CODE><type></CODE> or <CODE><function></CODE> and each +testing level (set by <CODE>-level</CODE>), there is a minimum value that +<CODE>testfloat_gen</CODE> will accept for <CODE><num></CODE>. +If no <CODE>-n</CODE> option is given, the number of test cases generated by +<CODE>testfloat_gen</CODE> equals the minimum value acceptable for the +<CODE>-n</CODE> argument. +Option <CODE>-n</CODE> cannot be used to reduce this number, but can increase +it, without changing the testing level. +</P> + +<H3><CODE>-forever</CODE></H3> + +<P> +The <CODE>-forever</CODE> option causes test cases to be generated +indefinitely, without limit (until the program is terminated by some external +cause). +The testing level is set to 2 by this option. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that is an +<NOBR>80-bit</NOBR> double-extended-precision operation affected by rounding +precision control, the <CODE>-precision32</CODE> option sets the rounding +precision to <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> +single-precision. +Likewise, <CODE>-precision64</CODE> sets the rounding precision to +<NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision, and +<CODE>-precision80</CODE> sets 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. +When rounding precision is applicable but not specified, the default is the +full <NOBR>80 bits</NOBR>, same as <CODE>-precision80</CODE>. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that requires rounding, the +<CODE>-rnear_even</CODE> option sets the rounding mode to nearest/even; +<CODE>-rnear_maxMag</CODE> sets rounding to nearest/maximum magnitude +(nearest-away); +<CODE>-rminMag</CODE> sets rounding to minimum magnitude (toward zero); +<CODE>-rmin</CODE> sets rounding to minimum (down, toward negative infinity); +and <CODE>-rmax</CODE> sets rounding to maximum (up, toward positive infinity). +These options are ignored for operations that are exact and thus do not round. +When rounding mode is relevant but not specified, the default is to round to +nearest/even, same as <CODE>-rnear_even</CODE>. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that requires rounding, the +<CODE>-tininessbefore</CODE> option indicates that tininess on underflow will +be detected before rounding, while <CODE>-tininessafter</CODE> indicates that +tininess on underflow will 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 +is to detect tininess on underflow before rounding, same as +<CODE>-tininessbefore</CODE>. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that rounds to an integer +(either conversion to an integer type or a <CODE>roundToInt</CODE> operation), +the <CODE>-notexact</CODE> option indicates that the <I>inexact</I> exception +flag is never raised, while <CODE>-exact</CODE> indicates that the +<I>inexact</I> exception flag is to be raised if the result is inexact. +For other operations, these options are ignored. +If neither option is specified, the default is not to raise the <I>inexact</I> +exception flag when rounding to an integer, same as <CODE>-notexact</CODE>. +</P> + + +<H2>Output Format</H2> + +<P> +For each test case generated, <CODE>testfloat_gen</CODE> writes a single line +of text to standard output. +When the <CODE>testfloat_gen</CODE> command is given a +<CODE><type></CODE> argument, each test case consists of either one +integer value or one, two, or three floating-point values. +Each value is written to output as a raw hexadecimal number. +When there is more than one value per line, they are separated by spaces. +For example, output from executing +<PRE> + testfloat_gen f64 2 +</PRE> +might look like this: +<PRE> + 3F90EB5825D6851E C3E0080080000000 + 41E3C00000000000 C182024F8AE474A8 + 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 + 3FFFED6A25C534BE 3CA1000000020000 + ... +</PRE> +with each hexadecimal number being one <NOBR>64-bit</NOBR> floating-point +value. +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 <CODE>3F9</CODE> are the sign and encoded exponent of the +<NOBR>64-bit</NOBR> floating-point value, and the remaining digits are the +encoded significand. +</P> + +<P> +When <CODE>testfloat_gen</CODE> is given a <CODE><function></CODE> +operation name, each line of output has not only the operands for the operation +but also the expected output, consisting of a result value and the exception +flags that are raised. +For example, the output from +<PRE> + testfloat_gen f64_add +</PRE> +could include these lines: +<PRE> + 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 + 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 + 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 + 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 + ... +</PRE> +On each line, the first two numbers are the operands for the floating-point +addition, and the third and fourth numbers are the expected floating-point +result (the sum) and the exception flags raised. +Exception flags are encoded with one bit per flag as follows: +<BLOCKQUOTE> +<TABLE> +<TR><TD>bit 0</TD><TD> </TD><TD><I>inexact</I> exception</TD></TR> +<TR><TD>bit 1</TD><TD> </TD><TD><I>underflow</I> exception</TD></TR> +<TR><TD>bit 2</TD><TD> </TD><TD><I>overflow</I> exception</TD></TR> +<TR><TD>bit 3</TD><TD> </TD><TD><I>infinite</I> exception ("divide by zero")</TD></TR> +<TR><TD>bit 4</TD><TD> </TD><TD><I>invalid</I> exception</TD></TR> +</TABLE> +</BLOCKQUOTE> +</P> + + +</BODY> + |