| |
| <HTML> |
| |
| <HEAD> |
| <TITLE>testfloat_gen</TITLE> |
| </HEAD> |
| |
| <BODY> |
| |
| <H1>Berkeley TestFloat Release 3d: <CODE>testfloat_gen</CODE></H1> |
| |
| <P> |
| John R. Hauser<BR> |
| 2017 August 18<BR> |
| </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> |
| The <CODE>testfloat_gen</CODE> program 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 using |
| 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: |
| <BLOCKQUOTE> |
| <PRE> |
| testfloat_gen [<<I>option</I>>...] <<I>type</I>> |
| testfloat_gen [<<I>option</I>>...] <<I>function</I>> |
| </PRE> |
| </BLOCKQUOTE> |
| Square brackets (<CODE>[ ]</CODE>) denote optional arguments, and |
| <CODE><<I>option</I>></CODE> is a supported option, documented below. |
| A <CODE>testfloat_gen</CODE> command expects either a |
| <CODE><<I>type</I>></CODE> specifying the type and number of outputs or a |
| <CODE><<I>function</I>></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><<I>type</I>></CODE> can be one of the following: |
| <BLOCKQUOTE> |
| <TABLE CELLSPACING=0 CELLPADDING=0> |
| <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>f16 [<<I>num</I>>]</CODE></TD> |
| <TD>one or more <NOBR>16-bit</NOBR> half-precision floating-point values</TD> |
| </TR> |
| <TR> |
| <TD><CODE>f32 [<<I>num</I>>]</CODE></TD> |
| <TD>one or more <NOBR>32-bit</NOBR> single-precision floating-point values</TD> |
| </TR> |
| <TR> |
| <TD><CODE>f64 [<<I>num</I>>]</CODE></TD> |
| <TD>one or more <NOBR>64-bit</NOBR> double-precision floating-point values</TD> |
| </TR> |
| <TR> |
| <TD><CODE>extF80 [<<I>num</I>>] </CODE></TD> |
| <TD>one or more <NOBR>80-bit</NOBR> double-extended-precision floating-point |
| values</TD> |
| </TR> |
| <TR> |
| <TD><CODE>f128 [<<I>num</I>>]</CODE></TD> |
| <TD>one or more <NOBR>128-bit</NOBR> quadruple-precision floating-point |
| values</TD> |
| </TR> |
| </TABLE> |
| </BLOCKQUOTE> |
| Optional <CODE><<I>num</I>></CODE> is one of 1, 2, <NOBR>or 3</NOBR>. |
| If a <CODE><<I>type</I>></CODE> is given without |
| <CODE><<I>num</I>></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><<I>function</I>></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><<I>type</I>></CODE> argument) but also the expected results as |
| determined by <CODE>testfloat_gen</CODE>’s internal floating-point |
| emulation (Berkeley 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 <<I>text</I>></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>-seed <<I>num</I>></CODE></H3> |
| |
| <P> |
| The <CODE>-seed</CODE> option sets the seed for the pseudo-random number |
| generator used for generating test cases. |
| The argument to <CODE>-seed</CODE> is a nonnegative integer. |
| Executing the same <CODE>testfloat_gen</CODE> program with the same arguments |
| (including the same pseudo-random number seed) should always generate the same |
| sequence of test cases, whereas changing the pseudo-random number seed should |
| result in a different sequence of test cases. |
| The default seed number <NOBR>is 1</NOBR>. |
| </P> |
| |
| <H3><CODE>-level <<I>num</I>></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 <<I>num</I>></CODE></H3> |
| |
| <P> |
| Option <CODE>-n</CODE> specifies the number of test cases to generate. |
| For each <CODE><<I>type</I>></CODE> or |
| <CODE><<I>function</I>></CODE> and each testing level (set by |
| <CODE>-level</CODE>), there is a minimum value that <CODE>testfloat_gen</CODE> |
| will accept for <CODE><<I>num</I>></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><<I>function</I>></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, -rodd</CODE></H3> |
| |
| <P> |
| When a <CODE><<I>function</I>></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); |
| <CODE>-rmax</CODE> sets rounding to maximum (up, toward positive infinity); |
| and <CODE>-rodd</CODE>, if supported, sets 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 is to round to |
| nearest/even, same as <CODE>-rnear_even</CODE>. |
| </P> |
| |
| <H3><CODE>-tininessbefore, -tininessafter</CODE></H3> |
| |
| <P> |
| When a <CODE><<I>function</I>></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 after rounding, same as |
| <CODE>-tininessafter</CODE>. |
| </P> |
| |
| <H3><CODE>-notexact, -exact</CODE></H3> |
| |
| <P> |
| When a <CODE><<I>function</I>></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><<I>type</I>></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 |
| <BLOCKQUOTE> |
| <PRE> |
| testfloat_gen f64 2 |
| </PRE> |
| </BLOCKQUOTE> |
| might look like this: |
| <BLOCKQUOTE> |
| <PRE> |
| 3F90EB5825D6851E C3E0080080000000 |
| 41E3C00000000000 C182024F8AE474A8 |
| 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 |
| 3FFFED6A25C534BE 3CA1000000020000 |
| ... |
| </PRE> |
| </BLOCKQUOTE> |
| 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><<I>function</I>></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 |
| <BLOCKQUOTE> |
| <PRE> |
| testfloat_gen f64_add |
| </PRE> |
| </BLOCKQUOTE> |
| could include these lines: |
| <BLOCKQUOTE> |
| <PRE> |
| 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 |
| 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 |
| 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 |
| 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 |
| ... |
| </PRE> |
| </BLOCKQUOTE> |
| 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 CELLSPACING=0 CELLPADDING=0> |
| <TR> |
| <TD>bit 0<CODE> </CODE></TD> |
| <TD><I>inexact</I> exception</TD> |
| </TR> |
| <TR><TD>bit 1</TD><TD><I>underflow</I> exception</TD></TR> |
| <TR><TD>bit 2</TD><TD><I>overflow</I> exception</TD></TR> |
| <TR> |
| <TD>bit 3</TD> |
| <TD><I>infinite</I> exception (“divide by zero”)</TD> |
| </TR> |
| <TR><TD>bit 4</TD><TD><I>invalid</I> exception</TD></TR> |
| </TABLE> |
| </BLOCKQUOTE> |
| </P> |
| |
| |
| </BODY> |
| |
