| 1 |
|
|---|
| 2 | <HTML>
|
|---|
| 3 |
|
|---|
| 4 | <HEAD>
|
|---|
| 5 | <TITLE>testfloat_gen</TITLE>
|
|---|
| 6 | </HEAD>
|
|---|
| 7 |
|
|---|
| 8 | <BODY>
|
|---|
| 9 |
|
|---|
| 10 | <H1>Berkeley TestFloat Release 3e: <CODE>testfloat_gen</CODE></H1>
|
|---|
| 11 |
|
|---|
| 12 | <P>
|
|---|
| 13 | John R. Hauser<BR>
|
|---|
| 14 | 2018 January 20<BR>
|
|---|
| 15 | </P>
|
|---|
| 16 |
|
|---|
| 17 |
|
|---|
| 18 | <H2>Overview</H2>
|
|---|
| 19 |
|
|---|
| 20 | <P>
|
|---|
| 21 | The <CODE>testfloat_gen</CODE> program generates test cases for testing that an
|
|---|
| 22 | implementation of floating-point arithmetic conforms to the IEEE Standard for
|
|---|
| 23 | Binary Floating-Point Arithmetic.
|
|---|
| 24 | <CODE>testfloat_gen</CODE> is part of the Berkeley TestFloat package, a small
|
|---|
| 25 | collection of programs for performing such tests.
|
|---|
| 26 | For general information about TestFloat, see file
|
|---|
| 27 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 28 | </P>
|
|---|
| 29 |
|
|---|
| 30 | <P>
|
|---|
| 31 | A single execution of <CODE>testfloat_gen</CODE> generates test cases for only
|
|---|
| 32 | a single floating-point operation and associated options.
|
|---|
| 33 | The <CODE>testfloat_gen</CODE> program must be repeatedly executed to generate
|
|---|
| 34 | test cases for each operation to be tested.
|
|---|
| 35 | </P>
|
|---|
| 36 |
|
|---|
| 37 | <P>
|
|---|
| 38 | The <CODE>testfloat_gen</CODE> program writes the test cases it generates to
|
|---|
| 39 | standard output.
|
|---|
| 40 | This output can either be captured in a file through redirection, or be piped
|
|---|
| 41 | to another program that exercises a floating-point operation using the test
|
|---|
| 42 | cases as they are supplied.
|
|---|
| 43 | Depending on use, the total output from <CODE>testfloat_gen</CODE> can be
|
|---|
| 44 | large, so piping to another program may be the best choice to avoid using
|
|---|
| 45 | inordinate file space.
|
|---|
| 46 | The format of <CODE>testfloat_gen</CODE>’s output is raw hexadecimal
|
|---|
| 47 | text, described in the section below titled <I>Output Format</I>.
|
|---|
| 48 | </P>
|
|---|
| 49 |
|
|---|
| 50 |
|
|---|
| 51 | <H2>Command Syntax</H2>
|
|---|
| 52 |
|
|---|
| 53 | <P>
|
|---|
| 54 | The <CODE>testfloat_gen</CODE> program is executed as a command in one of these
|
|---|
| 55 | forms:
|
|---|
| 56 | <BLOCKQUOTE>
|
|---|
| 57 | <PRE>
|
|---|
| 58 | testfloat_gen [<<I>option</I>>...] <<I>type</I>>
|
|---|
| 59 | testfloat_gen [<<I>option</I>>...] <<I>function</I>>
|
|---|
| 60 | </PRE>
|
|---|
| 61 | </BLOCKQUOTE>
|
|---|
| 62 | Square brackets (<CODE>[ ]</CODE>) denote optional arguments, and
|
|---|
| 63 | <CODE><<I>option</I>></CODE> is a supported option, documented below.
|
|---|
| 64 | A <CODE>testfloat_gen</CODE> command expects either a
|
|---|
| 65 | <CODE><<I>type</I>></CODE> specifying the type and number of outputs or a
|
|---|
| 66 | <CODE><<I>function</I>></CODE> naming a floating-point operation.
|
|---|
| 67 | If <CODE>testfloat_gen</CODE> is executed without any arguments, a summary of
|
|---|
| 68 | usage is written.
|
|---|
| 69 | </P>
|
|---|
| 70 |
|
|---|
| 71 | <P>
|
|---|
| 72 | A <CODE><<I>type</I>></CODE> can be one of the following:
|
|---|
| 73 | <BLOCKQUOTE>
|
|---|
| 74 | <TABLE CELLSPACING=0 CELLPADDING=0>
|
|---|
| 75 | <TR>
|
|---|
| 76 | <TD><CODE>ui32</CODE></TD>
|
|---|
| 77 | <TD>unsigned <NOBR>32-bit</NOBR> integers</TD>
|
|---|
| 78 | </TR>
|
|---|
| 79 | <TR>
|
|---|
| 80 | <TD><CODE>ui64</CODE></TD>
|
|---|
| 81 | <TD>unsigned <NOBR>64-bit</NOBR> integers</TD>
|
|---|
| 82 | </TR>
|
|---|
| 83 | <TR>
|
|---|
| 84 | <TD><CODE>i32</CODE></TD>
|
|---|
| 85 | <TD>signed <NOBR>32-bit</NOBR> integers</TD>
|
|---|
| 86 | </TR>
|
|---|
| 87 | <TR>
|
|---|
| 88 | <TD><CODE>i64</CODE></TD>
|
|---|
| 89 | <TD>signed <NOBR>64-bit</NOBR> integers</TD>
|
|---|
| 90 | </TR>
|
|---|
| 91 | <TR>
|
|---|
| 92 | <TD><CODE>f16 [<<I>num</I>>]</CODE></TD>
|
|---|
| 93 | <TD>one or more <NOBR>16-bit</NOBR> half-precision floating-point values</TD>
|
|---|
| 94 | </TR>
|
|---|
| 95 | <TR>
|
|---|
| 96 | <TD><CODE>f32 [<<I>num</I>>]</CODE></TD>
|
|---|
| 97 | <TD>one or more <NOBR>32-bit</NOBR> single-precision floating-point values</TD>
|
|---|
| 98 | </TR>
|
|---|
| 99 | <TR>
|
|---|
| 100 | <TD><CODE>f64 [<<I>num</I>>]</CODE></TD>
|
|---|
| 101 | <TD>one or more <NOBR>64-bit</NOBR> double-precision floating-point values</TD>
|
|---|
| 102 | </TR>
|
|---|
| 103 | <TR>
|
|---|
| 104 | <TD><CODE>extF80 [<<I>num</I>>] </CODE></TD>
|
|---|
| 105 | <TD>one or more <NOBR>80-bit</NOBR> double-extended-precision floating-point
|
|---|
| 106 | values</TD>
|
|---|
| 107 | </TR>
|
|---|
| 108 | <TR>
|
|---|
| 109 | <TD><CODE>f128 [<<I>num</I>>]</CODE></TD>
|
|---|
| 110 | <TD>one or more <NOBR>128-bit</NOBR> quadruple-precision floating-point
|
|---|
| 111 | values</TD>
|
|---|
| 112 | </TR>
|
|---|
| 113 | </TABLE>
|
|---|
| 114 | </BLOCKQUOTE>
|
|---|
| 115 | Optional <CODE><<I>num</I>></CODE> is one of 1, 2, <NOBR>or 3</NOBR>.
|
|---|
| 116 | If a <CODE><<I>type</I>></CODE> is given without
|
|---|
| 117 | <CODE><<I>num</I>></CODE> (such as <CODE>ui32</CODE> or
|
|---|
| 118 | <CODE>f64</CODE>), <CODE>testfloat_gen</CODE> outputs a list of values of the
|
|---|
| 119 | specified type, one value per line, appropriate for testing a floating-point
|
|---|
| 120 | operation with exactly one operand of the given type.
|
|---|
| 121 | If a floating-point type and number are given (such as
|
|---|
| 122 | <NOBR><CODE>f32</CODE> <CODE>2</CODE></NOBR> or
|
|---|
| 123 | <NOBR><CODE>extF80</CODE> <CODE>1</CODE></NOBR>), <CODE>testfloat_gen</CODE>
|
|---|
| 124 | outputs the specified number of values per line, appropriate for testing a
|
|---|
| 125 | floating-point operation with that number of operands.
|
|---|
| 126 | Although the exact operation being tested is not specified, the test cases
|
|---|
| 127 | output by <CODE>testfloat_gen</CODE> cover all standard floating-point
|
|---|
| 128 | operations, to the degree explained in
|
|---|
| 129 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 130 | </P>
|
|---|
| 131 |
|
|---|
| 132 | <P>
|
|---|
| 133 | If a <CODE><<I>function</I>></CODE> operation name is given, then each
|
|---|
| 134 | line of output from <CODE>testfloat_gen</CODE> contains not only the operands
|
|---|
| 135 | for that operation (as would be generated by an appropriate
|
|---|
| 136 | <CODE><<I>type</I>></CODE> argument) but also the expected results as
|
|---|
| 137 | determined by <CODE>testfloat_gen</CODE>’s internal floating-point
|
|---|
| 138 | emulation (Berkeley SoftFloat).
|
|---|
| 139 | The available operation names are listed in
|
|---|
| 140 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 141 | In all cases, floating-point operations have two results:
|
|---|
| 142 | first, a value, which may be floating-point, integer, or Boolean, and, second,
|
|---|
| 143 | the floating-point exception flags raised by the operation.
|
|---|
| 144 | If the output from a tested floating-point operation does not match the
|
|---|
| 145 | expected output specified by <CODE>testfloat_gen</CODE>, this may or may not
|
|---|
| 146 | indicate an error in the floating-point operation.
|
|---|
| 147 | For further explanation, see
|
|---|
| 148 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>,
|
|---|
| 149 | especially the section titled <I>Variations Allowed by the IEEE Floating-Point
|
|---|
| 150 | Standard</I>.
|
|---|
| 151 | </P>
|
|---|
| 152 |
|
|---|
| 153 |
|
|---|
| 154 | <H2>Options</H2>
|
|---|
| 155 |
|
|---|
| 156 | <P>
|
|---|
| 157 | The <CODE>testfloat_gen</CODE> program accepts several command options.
|
|---|
| 158 | If mutually contradictory options are given, the last one has priority.
|
|---|
| 159 | </P>
|
|---|
| 160 |
|
|---|
| 161 | <H3><CODE>-help</CODE></H3>
|
|---|
| 162 |
|
|---|
| 163 | <P>
|
|---|
| 164 | The <CODE>-help</CODE> option causes a summary of program usage to be written,
|
|---|
| 165 | after which the program exits.
|
|---|
| 166 | </P>
|
|---|
| 167 |
|
|---|
| 168 | <H3><CODE>-prefix <<I>text</I>></CODE></H3>
|
|---|
| 169 |
|
|---|
| 170 | <P>
|
|---|
| 171 | The <CODE>-prefix</CODE> option causes <CODE>testfloat_gen</CODE> to write the
|
|---|
| 172 | supplied text argument verbatim as the first line of output before any test
|
|---|
| 173 | cases.
|
|---|
| 174 | This can be used, for example, to indicate to a downstream program what kind of
|
|---|
| 175 | test to perform for the test cases that follow.
|
|---|
| 176 | </P>
|
|---|
| 177 |
|
|---|
| 178 | <H3><CODE>-seed <<I>num</I>></CODE></H3>
|
|---|
| 179 |
|
|---|
| 180 | <P>
|
|---|
| 181 | The <CODE>-seed</CODE> option sets the seed for the pseudo-random number
|
|---|
| 182 | generator used for generating test cases.
|
|---|
| 183 | The argument to <CODE>-seed</CODE> is a nonnegative integer.
|
|---|
| 184 | Executing the same <CODE>testfloat_gen</CODE> program with the same arguments
|
|---|
| 185 | (including the same pseudo-random number seed) should always generate the same
|
|---|
| 186 | sequence of test cases, whereas changing the pseudo-random number seed should
|
|---|
| 187 | result in a different sequence of test cases.
|
|---|
| 188 | The default seed number <NOBR>is 1</NOBR>.
|
|---|
| 189 | </P>
|
|---|
| 190 |
|
|---|
| 191 | <H3><CODE>-level <<I>num</I>></CODE></H3>
|
|---|
| 192 |
|
|---|
| 193 | <P>
|
|---|
| 194 | The <CODE>-level</CODE> option sets the level of testing.
|
|---|
| 195 | The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>.
|
|---|
| 196 | The default is <NOBR>level 1</NOBR>.
|
|---|
| 197 | <NOBR>Level 2</NOBR> causes many more test cases to be generated, with better
|
|---|
| 198 | coverage, than <NOBR>level 1</NOBR>.
|
|---|
| 199 | </P>
|
|---|
| 200 |
|
|---|
| 201 | <H3><CODE>-n <<I>num</I>></CODE></H3>
|
|---|
| 202 |
|
|---|
| 203 | <P>
|
|---|
| 204 | Option <CODE>-n</CODE> specifies the number of test cases to generate.
|
|---|
| 205 | For each <CODE><<I>type</I>></CODE> or
|
|---|
| 206 | <CODE><<I>function</I>></CODE> and each testing level (set by
|
|---|
| 207 | <CODE>-level</CODE>), there is a minimum value that <CODE>testfloat_gen</CODE>
|
|---|
| 208 | will accept for <CODE><<I>num</I>></CODE>.
|
|---|
| 209 | If no <CODE>-n</CODE> option is given, the number of test cases generated by
|
|---|
| 210 | <CODE>testfloat_gen</CODE> equals the minimum value acceptable for the
|
|---|
| 211 | <CODE>-n</CODE> argument.
|
|---|
| 212 | Option <CODE>-n</CODE> cannot be used to reduce this number, but can increase
|
|---|
| 213 | it, without changing the testing level.
|
|---|
| 214 | </P>
|
|---|
| 215 |
|
|---|
| 216 | <H3><CODE>-forever</CODE></H3>
|
|---|
| 217 |
|
|---|
| 218 | <P>
|
|---|
| 219 | The <CODE>-forever</CODE> option causes test cases to be generated
|
|---|
| 220 | indefinitely, without limit (until the program is terminated by some external
|
|---|
| 221 | cause).
|
|---|
| 222 | The testing level is set to 2 by this option.
|
|---|
| 223 | </P>
|
|---|
| 224 |
|
|---|
| 225 | <H3><CODE>-precision32, -precision64, -precision80</CODE></H3>
|
|---|
| 226 |
|
|---|
| 227 | <P>
|
|---|
| 228 | When a <CODE><<I>function</I>></CODE> is specified that is an
|
|---|
| 229 | <NOBR>80-bit</NOBR> double-extended-precision operation affected by rounding
|
|---|
| 230 | precision control, the <CODE>-precision32</CODE> option sets the rounding
|
|---|
| 231 | precision to <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR>
|
|---|
| 232 | single-precision.
|
|---|
| 233 | Likewise, <CODE>-precision64</CODE> sets the rounding precision to
|
|---|
| 234 | <NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision, and
|
|---|
| 235 | <CODE>-precision80</CODE> sets the rounding precision to the full
|
|---|
| 236 | <NOBR>80 bits</NOBR> of the double-extended-precision format.
|
|---|
| 237 | All these options are ignored for operations not affected by rounding precision
|
|---|
| 238 | control.
|
|---|
| 239 | When rounding precision is applicable but not specified, the default is the
|
|---|
| 240 | full <NOBR>80 bits</NOBR>, same as <CODE>-precision80</CODE>.
|
|---|
| 241 | </P>
|
|---|
| 242 |
|
|---|
| 243 | <H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax, -rodd</CODE></H3>
|
|---|
| 244 |
|
|---|
| 245 | <P>
|
|---|
| 246 | When a <CODE><<I>function</I>></CODE> is specified that requires
|
|---|
| 247 | rounding, the <CODE>-rnear_even</CODE> option sets the rounding mode to
|
|---|
| 248 | nearest/even;
|
|---|
| 249 | <CODE>-rnear_maxMag</CODE> sets rounding to nearest/maximum magnitude
|
|---|
| 250 | (nearest-away);
|
|---|
| 251 | <CODE>-rminMag</CODE> sets rounding to minimum magnitude (toward zero);
|
|---|
| 252 | <CODE>-rmin</CODE> sets rounding to minimum (down, toward negative infinity);
|
|---|
| 253 | <CODE>-rmax</CODE> sets rounding to maximum (up, toward positive infinity);
|
|---|
| 254 | and <CODE>-rodd</CODE>, if supported, sets rounding to odd.
|
|---|
| 255 | These options are ignored for operations that are exact and thus do not round.
|
|---|
| 256 | When rounding mode is relevant but not specified, the default is to round to
|
|---|
| 257 | nearest/even, same as <CODE>-rnear_even</CODE>.
|
|---|
| 258 | </P>
|
|---|
| 259 |
|
|---|
| 260 | <H3><CODE>-tininessbefore, -tininessafter</CODE></H3>
|
|---|
| 261 |
|
|---|
| 262 | <P>
|
|---|
| 263 | When a <CODE><<I>function</I>></CODE> is specified that requires
|
|---|
| 264 | rounding, the <CODE>-tininessbefore</CODE> option indicates that tininess on
|
|---|
| 265 | underflow will be detected before rounding, while <CODE>-tininessafter</CODE>
|
|---|
| 266 | indicates that tininess on underflow will be detected after rounding.
|
|---|
| 267 | These options are ignored for operations that are exact and thus do not round.
|
|---|
| 268 | When the method of tininess detection matters but is not specified, the default
|
|---|
| 269 | is to detect tininess on underflow after rounding, same as
|
|---|
| 270 | <CODE>-tininessafter</CODE>.
|
|---|
| 271 | </P>
|
|---|
| 272 |
|
|---|
| 273 | <H3><CODE>-notexact, -exact</CODE></H3>
|
|---|
| 274 |
|
|---|
| 275 | <P>
|
|---|
| 276 | When a <CODE><<I>function</I>></CODE> is specified that rounds to an
|
|---|
| 277 | integer (either conversion to an integer type or a <CODE>roundToInt</CODE>
|
|---|
| 278 | operation), the <CODE>-notexact</CODE> option indicates that the <I>inexact</I>
|
|---|
| 279 | exception flag is never raised, while <CODE>-exact</CODE> indicates that the
|
|---|
| 280 | <I>inexact</I> exception flag is to be raised if the result is inexact.
|
|---|
| 281 | For other operations, these options are ignored.
|
|---|
| 282 | If neither option is specified, the default is not to raise the <I>inexact</I>
|
|---|
| 283 | exception flag when rounding to an integer, same as <CODE>-notexact</CODE>.
|
|---|
| 284 | </P>
|
|---|
| 285 |
|
|---|
| 286 |
|
|---|
| 287 | <H2>Output Format</H2>
|
|---|
| 288 |
|
|---|
| 289 | <P>
|
|---|
| 290 | For each test case generated, <CODE>testfloat_gen</CODE> writes a single line
|
|---|
| 291 | of text to standard output.
|
|---|
| 292 | When the <CODE>testfloat_gen</CODE> command is given a
|
|---|
| 293 | <CODE><<I>type</I>></CODE> argument, each test case consists of either
|
|---|
| 294 | one integer value or one, two, or three floating-point values.
|
|---|
| 295 | Each value is written to output as a raw hexadecimal number.
|
|---|
| 296 | When there is more than one value per line, they are separated by spaces.
|
|---|
| 297 | For example, output from executing
|
|---|
| 298 | <BLOCKQUOTE>
|
|---|
| 299 | <PRE>
|
|---|
| 300 | testfloat_gen f64 2
|
|---|
| 301 | </PRE>
|
|---|
| 302 | </BLOCKQUOTE>
|
|---|
| 303 | might look like this:
|
|---|
| 304 | <BLOCKQUOTE>
|
|---|
| 305 | <PRE>
|
|---|
| 306 | 3F90EB5825D6851E C3E0080080000000
|
|---|
| 307 | 41E3C00000000000 C182024F8AE474A8
|
|---|
| 308 | 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80
|
|---|
| 309 | 3FFFED6A25C534BE 3CA1000000020000
|
|---|
| 310 | ...
|
|---|
| 311 | </PRE>
|
|---|
| 312 | </BLOCKQUOTE>
|
|---|
| 313 | with each hexadecimal number being one <NOBR>64-bit</NOBR> floating-point
|
|---|
| 314 | value.
|
|---|
| 315 | Note that, for floating-point values, the sign and exponent are at the
|
|---|
| 316 | most-significant end of the number.
|
|---|
| 317 | Thus, for the first number on the first line above, the leading hexadecimal
|
|---|
| 318 | digits <CODE>3F9</CODE> are the sign and encoded exponent of the
|
|---|
| 319 | <NOBR>64-bit</NOBR> floating-point value, and the remaining digits are the
|
|---|
| 320 | encoded significand.
|
|---|
| 321 | </P>
|
|---|
| 322 |
|
|---|
| 323 | <P>
|
|---|
| 324 | When <CODE>testfloat_gen</CODE> is given a <CODE><<I>function</I>></CODE>
|
|---|
| 325 | operation name, each line of output has not only the operands for the operation
|
|---|
| 326 | but also the expected output, consisting of a result value and the exception
|
|---|
| 327 | flags that are raised.
|
|---|
| 328 | For example, the output from
|
|---|
| 329 | <BLOCKQUOTE>
|
|---|
| 330 | <PRE>
|
|---|
| 331 | testfloat_gen f64_add
|
|---|
| 332 | </PRE>
|
|---|
| 333 | </BLOCKQUOTE>
|
|---|
| 334 | could include these lines:
|
|---|
| 335 | <BLOCKQUOTE>
|
|---|
| 336 | <PRE>
|
|---|
| 337 | 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01
|
|---|
| 338 | 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01
|
|---|
| 339 | 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05
|
|---|
| 340 | 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01
|
|---|
| 341 | ...
|
|---|
| 342 | </PRE>
|
|---|
| 343 | </BLOCKQUOTE>
|
|---|
| 344 | On each line, the first two numbers are the operands for the floating-point
|
|---|
| 345 | addition, and the third and fourth numbers are the expected floating-point
|
|---|
| 346 | result (the sum) and the exception flags raised.
|
|---|
| 347 | Exception flags are encoded with one bit per flag as follows:
|
|---|
| 348 | <BLOCKQUOTE>
|
|---|
| 349 | <TABLE CELLSPACING=0 CELLPADDING=0>
|
|---|
| 350 | <TR>
|
|---|
| 351 | <TD>bit 0<CODE> </CODE></TD>
|
|---|
| 352 | <TD><I>inexact</I> exception</TD>
|
|---|
| 353 | </TR>
|
|---|
| 354 | <TR><TD>bit 1</TD><TD><I>underflow</I> exception</TD></TR>
|
|---|
| 355 | <TR><TD>bit 2</TD><TD><I>overflow</I> exception</TD></TR>
|
|---|
| 356 | <TR>
|
|---|
| 357 | <TD>bit 3</TD>
|
|---|
| 358 | <TD><I>infinite</I> exception (“divide by zero”)</TD>
|
|---|
| 359 | </TR>
|
|---|
| 360 | <TR><TD>bit 4</TD><TD><I>invalid</I> exception</TD></TR>
|
|---|
| 361 | </TABLE>
|
|---|
| 362 | </BLOCKQUOTE>
|
|---|
| 363 | </P>
|
|---|
| 364 |
|
|---|
| 365 |
|
|---|
| 366 | </BODY>
|
|---|
| 367 |
|
|---|
