| 1 |
|
|---|
| 2 | <HTML>
|
|---|
| 3 |
|
|---|
| 4 | <HEAD>
|
|---|
| 5 | <TITLE>testfloat_ver</TITLE>
|
|---|
| 6 | </HEAD>
|
|---|
| 7 |
|
|---|
| 8 | <BODY>
|
|---|
| 9 |
|
|---|
| 10 | <H1>Berkeley TestFloat Release 3e: <CODE>testfloat_ver</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_ver</CODE> program accepts test-case results obtained from
|
|---|
| 22 | exercising an implementation of floating-point arithmetic and verifies that
|
|---|
| 23 | those results conform to the IEEE Standard for Binary Floating-Point
|
|---|
| 24 | Arithmetic.
|
|---|
| 25 | <CODE>testfloat_ver</CODE> is part of the Berkeley TestFloat package, a small
|
|---|
| 26 | collection of programs for performing such tests.
|
|---|
| 27 | For general information about TestFloat, see file
|
|---|
| 28 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 29 | </P>
|
|---|
| 30 |
|
|---|
| 31 | <P>
|
|---|
| 32 | A single execution of <CODE>testfloat_ver</CODE> verifies results for only a
|
|---|
| 33 | single floating-point operation and associated options.
|
|---|
| 34 | The <CODE>testfloat_ver</CODE> program must be repeatedly executed to verify
|
|---|
| 35 | results for each operation to be tested.
|
|---|
| 36 | </P>
|
|---|
| 37 |
|
|---|
| 38 | <P>
|
|---|
| 39 | The test cases to be verified are read by <CODE>testfloat_ver</CODE> from
|
|---|
| 40 | standard input.
|
|---|
| 41 | This input will typically be piped from another program that, for each test
|
|---|
| 42 | case, invokes the floating-point operation and writes out the results.
|
|---|
| 43 | The format of <CODE>testfloat_ver</CODE>’s input is raw hexadecimal text,
|
|---|
| 44 | described in the section below titled <I>Input Format</I>.
|
|---|
| 45 | </P>
|
|---|
| 46 |
|
|---|
| 47 | <P>
|
|---|
| 48 | For each test case given to it, <CODE>testfloat_ver</CODE> examines the
|
|---|
| 49 | computed results and reports any unexpected results as likely errors.
|
|---|
| 50 |
|
|---|
| 51 | For more about the operation of <CODE>testfloat_ver</CODE> and how to interpret
|
|---|
| 52 | its output, refer to
|
|---|
| 53 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 54 | </P>
|
|---|
| 55 |
|
|---|
| 56 |
|
|---|
| 57 | <H2>Command Syntax</H2>
|
|---|
| 58 |
|
|---|
| 59 | <P>
|
|---|
| 60 | The <CODE>testfloat_ver</CODE> program is executed as a command with this
|
|---|
| 61 | syntax:
|
|---|
| 62 | <BLOCKQUOTE>
|
|---|
| 63 | <PRE>
|
|---|
| 64 | testfloat_ver [<<I>option</I>>...] <<I>function</I>>
|
|---|
| 65 | </PRE>
|
|---|
| 66 | </BLOCKQUOTE>
|
|---|
| 67 | Square brackets (<CODE>[ ]</CODE>) denote optional arguments,
|
|---|
| 68 | <CODE><<I>option</I>></CODE> is a supported option, and
|
|---|
| 69 | <CODE><<I>function</I>></CODE> is the name of a testable operation.
|
|---|
| 70 | The available options are documented below.
|
|---|
| 71 | The testable operation names are listed in
|
|---|
| 72 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 73 | If <CODE>testfloat_ver</CODE> is executed without any arguments, a summary of
|
|---|
| 74 | usage is written.
|
|---|
| 75 | </P>
|
|---|
| 76 |
|
|---|
| 77 |
|
|---|
| 78 | <H2>Options</H2>
|
|---|
| 79 |
|
|---|
| 80 | <P>
|
|---|
| 81 | The <CODE>testfloat_ver</CODE> program accepts several command options.
|
|---|
| 82 | If mutually contradictory options are given, the last one has priority.
|
|---|
| 83 | </P>
|
|---|
| 84 |
|
|---|
| 85 | <H3><CODE>-help</CODE></H3>
|
|---|
| 86 |
|
|---|
| 87 | <P>
|
|---|
| 88 | The <CODE>-help</CODE> option causes a summary of program usage to be written,
|
|---|
| 89 | after which the program exits.
|
|---|
| 90 | </P>
|
|---|
| 91 |
|
|---|
| 92 | <H3><CODE>-errors <<I>num</I>></CODE></H3>
|
|---|
| 93 |
|
|---|
| 94 | <P>
|
|---|
| 95 | The <CODE>-errors</CODE> option instructs <CODE>testfloat_ver</CODE> to report
|
|---|
| 96 | no more than the specified number of errors.
|
|---|
| 97 | The argument to <CODE>-errors</CODE> must be a nonnegative decimal integer.
|
|---|
| 98 | Once the specified number of error reports has been generated, the program
|
|---|
| 99 | exits.
|
|---|
| 100 | The default is <NOBR><CODE>-errors</CODE> <CODE>20</CODE></NOBR>.
|
|---|
| 101 | </P>
|
|---|
| 102 |
|
|---|
| 103 | <P>
|
|---|
| 104 | Against intuition, <NOBR><CODE>-errors</CODE> <CODE>0</CODE></NOBR> causes
|
|---|
| 105 | <CODE>testfloat_ver</CODE> to continue for any number of errors.
|
|---|
| 106 | </P>
|
|---|
| 107 |
|
|---|
| 108 | <H3><CODE>-checkNaNs</CODE></H3>
|
|---|
| 109 |
|
|---|
| 110 | <P>
|
|---|
| 111 | The <CODE>-checkNaNs</CODE> option causes <CODE>testfloat_ver</CODE> to verify
|
|---|
| 112 | the bitwise correctness of NaN results.
|
|---|
| 113 | In order for this option to be sensible, <CODE>testfloat_ver</CODE> must have
|
|---|
| 114 | been compiled so that its internal reference implementation of floating-point
|
|---|
| 115 | (Berkeley SoftFloat) generates the proper NaN results for the system being
|
|---|
| 116 | tested.
|
|---|
| 117 | </P>
|
|---|
| 118 |
|
|---|
| 119 | <H3><CODE>-checkInvInts</CODE></H3>
|
|---|
| 120 |
|
|---|
| 121 | <P>
|
|---|
| 122 | The <CODE>-checkInvInts</CODE> option causes <CODE>testfloat_ver</CODE> to
|
|---|
| 123 | verify the bitwise correctness of integer results of invalid operations.
|
|---|
| 124 | In order for this option to be sensible, <CODE>testfloat_ver</CODE> must have
|
|---|
| 125 | been compiled so that its internal reference implementation of floating-point
|
|---|
| 126 | (Berkeley SoftFloat) generates the proper integer results for the system being
|
|---|
| 127 | tested.
|
|---|
| 128 | </P>
|
|---|
| 129 |
|
|---|
| 130 | <H3><CODE>-checkAll</CODE></H3>
|
|---|
| 131 |
|
|---|
| 132 | <P>
|
|---|
| 133 | Enables both <CODE>-checkNaNs</CODE> and <CODE>-checkInvInts</CODE>.
|
|---|
| 134 | </P>
|
|---|
| 135 |
|
|---|
| 136 | <H3><CODE>-precision32, -precision64, -precision80</CODE></H3>
|
|---|
| 137 |
|
|---|
| 138 | <P>
|
|---|
| 139 | When <CODE><<I>function</I>></CODE> is an <NOBR>80-bit</NOBR>
|
|---|
| 140 | double-extended-precision operation affected by rounding precision control, the
|
|---|
| 141 | <CODE>-precision32</CODE> option indicates that the rounding precision should
|
|---|
| 142 | be <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> single-precision.
|
|---|
| 143 | Likewise, <CODE>-precision64</CODE> indicates that the rounding precision
|
|---|
| 144 | should be <NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR>
|
|---|
| 145 | double-precision, and <CODE>-precision80</CODE> indicates that the rounding
|
|---|
| 146 | precision should be the full <NOBR>80 bits</NOBR> of the
|
|---|
| 147 | double-extended-precision format.
|
|---|
| 148 | All these options are ignored for operations not affected by rounding precision
|
|---|
| 149 | control.
|
|---|
| 150 | When rounding precision is applicable but not specified, the default assumption
|
|---|
| 151 | is the full <NOBR>80 bits</NOBR>, same as <CODE>-precision80</CODE>.
|
|---|
| 152 | </P>
|
|---|
| 153 |
|
|---|
| 154 | <H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax, -rodd</CODE></H3>
|
|---|
| 155 |
|
|---|
| 156 | <P>
|
|---|
| 157 | When <CODE><<I>function</I>></CODE> is an operation that requires
|
|---|
| 158 | rounding, the <CODE>-rnear_even</CODE> option indicates that rounding should be
|
|---|
| 159 | to nearest/even, <CODE>-rnear_maxMag</CODE> indicates rounding to
|
|---|
| 160 | nearest/maximum magnitude (nearest-away), <CODE>-rminMag</CODE> indicates
|
|---|
| 161 | rounding to minimum magnitude (toward zero), <CODE>-rmin</CODE> indicates
|
|---|
| 162 | rounding to minimum (down, toward negative infinity), <CODE>-rmax</CODE>
|
|---|
| 163 | indicates rounding to maximum (up, toward positive infinity), and
|
|---|
| 164 | <CODE>-rodd</CODE>, if supported, indicates rounding to odd.
|
|---|
| 165 | These options are ignored for operations that are exact and thus do not round.
|
|---|
| 166 | When rounding mode is relevant but not specified, the default assumption is
|
|---|
| 167 | rounding to nearest/even, same as <CODE>-rnear_even</CODE>.
|
|---|
| 168 | </P>
|
|---|
| 169 |
|
|---|
| 170 | <H3><CODE>-tininessbefore, -tininessafter</CODE></H3>
|
|---|
| 171 |
|
|---|
| 172 | <P>
|
|---|
| 173 | When <CODE><<I>function</I>></CODE> is an operation that requires
|
|---|
| 174 | rounding, the <CODE>-tininessbefore</CODE> option indicates that tininess on
|
|---|
| 175 | underflow should be detected before rounding, while <CODE>-tininessafter</CODE>
|
|---|
| 176 | indicates that tininess on underflow should be detected after rounding.
|
|---|
| 177 | These options are ignored for operations that are exact and thus do not round.
|
|---|
| 178 | When the method of tininess detection matters but is not specified, the default
|
|---|
| 179 | assumption is that tininess should be detected after rounding, same as
|
|---|
| 180 | <CODE>-tininessafter</CODE>.
|
|---|
| 181 | </P>
|
|---|
| 182 |
|
|---|
| 183 | <H3><CODE>-notexact, -exact</CODE></H3>
|
|---|
| 184 |
|
|---|
| 185 | <P>
|
|---|
| 186 | When <CODE><<I>function</I>></CODE> is an operation that rounds to an
|
|---|
| 187 | integer (either conversion to an integer type or a <CODE>roundToInt</CODE>
|
|---|
| 188 | operation), the <CODE>-notexact</CODE> option indicates that the <I>inexact</I>
|
|---|
| 189 | exception flag should never be raised, while <CODE>-exact</CODE> indicates that
|
|---|
| 190 | the <I>inexact</I> exception flag should be raised when the result is inexact.
|
|---|
| 191 | For other operations, these options are ignored.
|
|---|
| 192 | If neither option is specified, the default assumption is that the
|
|---|
| 193 | <I>inexact</I> exception flag should not be raised when rounding to an integer,
|
|---|
| 194 | same as <CODE>-notexact</CODE>.
|
|---|
| 195 | </P>
|
|---|
| 196 |
|
|---|
| 197 |
|
|---|
| 198 | <H2>Input Format</H2>
|
|---|
| 199 |
|
|---|
| 200 | <P>
|
|---|
| 201 | For a given <CODE><<I>function</I>></CODE> argument, the input format
|
|---|
| 202 | expected by <CODE>testfloat_ver</CODE> is the same as the output generated by
|
|---|
| 203 | program
|
|---|
| 204 | <A HREF="testfloat_gen.html"><NOBR><CODE>testfloat_gen</CODE></NOBR></A> for
|
|---|
| 205 | the same argument.
|
|---|
| 206 | </P>
|
|---|
| 207 |
|
|---|
| 208 | <P>
|
|---|
| 209 | Input to <CODE>testfloat_ver</CODE> is expected to be text, with each line
|
|---|
| 210 | containing the data for one test case.
|
|---|
| 211 | The number of input lines thus equals the number of test cases.
|
|---|
| 212 | A single test case is organized as follows: first are the operands for the
|
|---|
| 213 | operation, next is the result value obtained, and last is a number indicating
|
|---|
| 214 | the exception flags that were raised.
|
|---|
| 215 | These values are all expected to be provided as raw hexadecimal numbers
|
|---|
| 216 | separated on the line by spaces.
|
|---|
| 217 | For example, for the command
|
|---|
| 218 | <BLOCKQUOTE>
|
|---|
| 219 | <PRE>
|
|---|
| 220 | testfloat_ver f64_add
|
|---|
| 221 | </PRE>
|
|---|
| 222 | </BLOCKQUOTE>
|
|---|
| 223 | valid input could include these lines:
|
|---|
| 224 | <BLOCKQUOTE>
|
|---|
| 225 | <PRE>
|
|---|
| 226 | 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01
|
|---|
| 227 | 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01
|
|---|
| 228 | 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05
|
|---|
| 229 | 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01
|
|---|
| 230 | ...
|
|---|
| 231 | </PRE>
|
|---|
| 232 | </BLOCKQUOTE>
|
|---|
| 233 | On each line above, the first two hexadecimal numbers represent the
|
|---|
| 234 | <NOBR>64-bit</NOBR> floating-point operands, the third hexadecimal number is
|
|---|
| 235 | the <NOBR>64-bit</NOBR> floating-point result of the operation (the sum), and
|
|---|
| 236 | the last hexadecimal number gives the exception flags that were raised by the
|
|---|
| 237 | operation.
|
|---|
| 238 | </P>
|
|---|
| 239 |
|
|---|
| 240 | <P>
|
|---|
| 241 | Note that, for floating-point values, the sign and exponent are at the
|
|---|
| 242 | most-significant end of the number.
|
|---|
| 243 | Thus, for the first number on the first line above, the leading hexadecimal
|
|---|
| 244 | digits <CODE>3F9</CODE> are the sign and encoded exponent of the
|
|---|
| 245 | <NOBR>64-bit</NOBR> floating-point value, and the remaining digits are the
|
|---|
| 246 | encoded significand.
|
|---|
| 247 | </P>
|
|---|
| 248 |
|
|---|
| 249 | <P>
|
|---|
| 250 | Exception flags are encoded with one bit per flag as follows:
|
|---|
| 251 | <BLOCKQUOTE>
|
|---|
| 252 | <TABLE CELLSPACING=0 CELLPADDING=0>
|
|---|
| 253 | <TR>
|
|---|
| 254 | <TD>bit 0<CODE> </CODE></TD>
|
|---|
| 255 | <TD><I>inexact</I> exception</TD>
|
|---|
| 256 | </TR>
|
|---|
| 257 | <TR><TD>bit 1</TD><TD><I>underflow</I> exception</TD></TR>
|
|---|
| 258 | <TR><TD>bit 2</TD><TD><I>overflow</I> exception</TD></TR>
|
|---|
| 259 | <TR>
|
|---|
| 260 | <TD>bit 3</TD>
|
|---|
| 261 | <TD><I>infinite</I> exception (“divide by zero”)</TD>
|
|---|
| 262 | </TR>
|
|---|
| 263 | <TR><TD>bit 4</TD><TD><I>invalid</I> exception</TD></TR>
|
|---|
| 264 | </TABLE>
|
|---|
| 265 | </BLOCKQUOTE>
|
|---|
| 266 | </P>
|
|---|
| 267 |
|
|---|
| 268 |
|
|---|
| 269 | </BODY>
|
|---|
| 270 |
|
|---|
