| 1 |
|
|---|
| 2 | <HTML>
|
|---|
| 3 |
|
|---|
| 4 | <HEAD>
|
|---|
| 5 | <TITLE>testfloat</TITLE>
|
|---|
| 6 | </HEAD>
|
|---|
| 7 |
|
|---|
| 8 | <BODY>
|
|---|
| 9 |
|
|---|
| 10 | <H1>Berkeley TestFloat Release 3e: <CODE>testfloat</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</CODE> program tests an implementation of floating-point
|
|---|
| 22 | arithmetic for conformity to the IEEE Standard for Binary Floating-Point
|
|---|
| 23 | Arithmetic.
|
|---|
| 24 | <CODE>testfloat</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 | The <CODE>testfloat</CODE> program is an all-in-one tool for testing
|
|---|
| 32 | floating-point arithmetic.
|
|---|
| 33 | It generates test operand values, invokes a floating-point operation with the
|
|---|
| 34 | generated operands, and examines the corresponding computed results, reporting
|
|---|
| 35 | unexpected results as likely errors.
|
|---|
| 36 | While the processes of generating inputs and examining results are generic, a
|
|---|
| 37 | particular build of <CODE>testfloat</CODE> is limited to testing only the one
|
|---|
| 38 | implementation of floating-point it has been compiled to invoke.
|
|---|
| 39 | For example, while one instance of <CODE>testfloat</CODE> might be compiled to
|
|---|
| 40 | execute a computer’s hardware instruction for floating-point addition, a
|
|---|
| 41 | different version might be compiled to call a subroutine called
|
|---|
| 42 | <CODE>myAddFloat</CODE> that is linked into the <CODE>testfloat</CODE> program.
|
|---|
| 43 | To test a new implementation of floating-point (a new set of machine
|
|---|
| 44 | instructions or a new set of subroutines), a new <CODE>testfloat</CODE> must be
|
|---|
| 45 | compiled containing the code needed to invoke the new floating-point.
|
|---|
| 46 | </P>
|
|---|
| 47 |
|
|---|
| 48 | <P>
|
|---|
| 49 | The default build of <CODE>testfloat</CODE> assumes that C types
|
|---|
| 50 | <CODE>float</CODE> and <CODE>double</CODE> are <NOBR>32-bit</NOBR> and
|
|---|
| 51 | <NOBR>64-bit</NOBR> binary floating-point types conforming to the IEEE
|
|---|
| 52 | Standard, and tests the C operations of <CODE>+</CODE>, <CODE>-</CODE>,
|
|---|
| 53 | <CODE>*</CODE>, <CODE>/</CODE>, type conversions, etc.
|
|---|
| 54 | This tests the floating-point arithmetic seen by C programs.
|
|---|
| 55 | Depending on the compiler and the options selected during compilation, this may
|
|---|
| 56 | or may not be the same as the computer’s floating-point hardware, if any.
|
|---|
| 57 | </P>
|
|---|
| 58 |
|
|---|
| 59 | <P>
|
|---|
| 60 | The <CODE>testfloat</CODE> program will ordinarily test an operation for all
|
|---|
| 61 | five rounding modes defined by the IEEE Floating-Point Standard, one after the
|
|---|
| 62 | other, plus possibly a sixth mode, <I>round to odd</I> (depending on the
|
|---|
| 63 | options selected when <CODE>testfloat</CODE> was compiled).
|
|---|
| 64 | If the rounding mode is not supposed to have any affect on the
|
|---|
| 65 | results—for instance, some operations do not require rounding—only
|
|---|
| 66 | the nearest/even rounding mode is checked.
|
|---|
| 67 | For double-extended-precision operations affected by rounding precision
|
|---|
| 68 | control, <CODE>testfloat</CODE> also tests all three rounding precision modes,
|
|---|
| 69 | one after the other.
|
|---|
| 70 | Testing can be limited to a single rounding mode and/or rounding precision with
|
|---|
| 71 | appropriate command-line options.
|
|---|
| 72 | </P>
|
|---|
| 73 |
|
|---|
| 74 | <P>
|
|---|
| 75 | For more about the operation of <CODE>testfloat</CODE> and how to interpret its
|
|---|
| 76 | output, refer to
|
|---|
| 77 | <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
|
|---|
| 78 | </P>
|
|---|
| 79 |
|
|---|
| 80 |
|
|---|
| 81 | <H2>Command Syntax</H2>
|
|---|
| 82 |
|
|---|
| 83 | <P>
|
|---|
| 84 | The <CODE>testfloat</CODE> program is executed as a command with this syntax:
|
|---|
| 85 | <BLOCKQUOTE>
|
|---|
| 86 | <PRE>
|
|---|
| 87 | testfloat [<<I>option</I>>...] <<I>function</I>>
|
|---|
| 88 | </PRE>
|
|---|
| 89 | </BLOCKQUOTE>
|
|---|
| 90 | Square brackets (<CODE>[ ]</CODE>) denote optional arguments,
|
|---|
| 91 | <CODE><<I>option</I>></CODE> is a supported option, and
|
|---|
| 92 | <CODE><<I>function</I>></CODE> is the name of either a testable operation
|
|---|
| 93 | or a function set.
|
|---|
| 94 | The available options and function sets are documented below.
|
|---|
| 95 | The <CODE>-list</CODE> option can be used to obtain a list of all testable
|
|---|
| 96 | operations for a given build of <CODE>testfloat</CODE>.
|
|---|
| 97 | If <CODE>testfloat</CODE> is executed without any arguments, a summary of usage
|
|---|
| 98 | is written.
|
|---|
| 99 | </P>
|
|---|
| 100 |
|
|---|
| 101 |
|
|---|
| 102 | <H2>Options</H2>
|
|---|
| 103 |
|
|---|
| 104 | <P>
|
|---|
| 105 | The <CODE>testfloat</CODE> program accepts several command options.
|
|---|
| 106 | If mutually contradictory options are given, the last one has priority.
|
|---|
| 107 | </P>
|
|---|
| 108 |
|
|---|
| 109 | <H3><CODE>-help</CODE></H3>
|
|---|
| 110 |
|
|---|
| 111 | <P>
|
|---|
| 112 | The <CODE>-help</CODE> option causes a summary of program usage to be written,
|
|---|
| 113 | after which the program exits.
|
|---|
| 114 | </P>
|
|---|
| 115 |
|
|---|
| 116 | <H3><CODE>-list</CODE></H3>
|
|---|
| 117 |
|
|---|
| 118 | <P>
|
|---|
| 119 | The <CODE>-list</CODE> option causes a list of testable operations to be
|
|---|
| 120 | written, after which the program exits.
|
|---|
| 121 | An operation is testable by <CODE>testfloat</CODE> if the program knows some
|
|---|
| 122 | way to invoke the operation.
|
|---|
| 123 | </P>
|
|---|
| 124 |
|
|---|
| 125 | <H3><CODE>-seed <<I>num</I>></CODE></H3>
|
|---|
| 126 |
|
|---|
| 127 | <P>
|
|---|
| 128 | The <CODE>-seed</CODE> option sets the seed for the pseudo-random number
|
|---|
| 129 | generator used for generating test cases.
|
|---|
| 130 | The argument to <CODE>-seed</CODE> is a nonnegative integer.
|
|---|
| 131 | Executing the same compiled <CODE>testfloat</CODE> program with the same
|
|---|
| 132 | arguments (including the same pseudo-random number seed) should always perform
|
|---|
| 133 | the same sequence of tests, whereas changing the pseudo-random number seed
|
|---|
| 134 | should result in a different sequence of tests.
|
|---|
| 135 | The default seed number <NOBR>is 1</NOBR>.
|
|---|
| 136 | </P>
|
|---|
| 137 |
|
|---|
| 138 | <H3><CODE>-level <<I>num</I>></CODE></H3>
|
|---|
| 139 |
|
|---|
| 140 | <P>
|
|---|
| 141 | The <CODE>-level</CODE> option sets the level of testing.
|
|---|
| 142 | The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>.
|
|---|
| 143 | The default is <NOBR>level 1</NOBR>.
|
|---|
| 144 | Level 2 performs many more tests than <NOBR>level 1</NOBR> and thus can reveal
|
|---|
| 145 | bugs not found by <NOBR>level 1</NOBR>.
|
|---|
| 146 | </P>
|
|---|
| 147 |
|
|---|
| 148 | <H3><CODE>-errors <<I>num</I>></CODE></H3>
|
|---|
| 149 |
|
|---|
| 150 | <P>
|
|---|
| 151 | The <CODE>-errors</CODE> option instructs <CODE>testfloat</CODE> to report no
|
|---|
| 152 | more than the specified number of errors for any combination of operation,
|
|---|
| 153 | rounding mode, etc.
|
|---|
| 154 | The argument to <CODE>-errors</CODE> must be a nonnegative decimal integer.
|
|---|
| 155 | Once the specified number of error reports has been generated,
|
|---|
| 156 | <CODE>testfloat</CODE> ends the current test and begins the next one, if any.
|
|---|
| 157 | The default is <NOBR><CODE>-errors</CODE> <CODE>20</CODE></NOBR>.
|
|---|
| 158 | </P>
|
|---|
| 159 |
|
|---|
| 160 | <P>
|
|---|
| 161 | Against intuition, <NOBR><CODE>-errors</CODE> <CODE>0</CODE></NOBR> causes
|
|---|
| 162 | <CODE>testfloat</CODE> to report every error it finds.
|
|---|
| 163 | </P>
|
|---|
| 164 |
|
|---|
| 165 | <H3><CODE>-errorstop</CODE></H3>
|
|---|
| 166 |
|
|---|
| 167 | <P>
|
|---|
| 168 | The <CODE>-errorstop</CODE> option causes the program to exit after the first
|
|---|
| 169 | operation for which any errors are reported.
|
|---|
| 170 | </P>
|
|---|
| 171 |
|
|---|
| 172 | <H3><CODE>-forever</CODE></H3>
|
|---|
| 173 |
|
|---|
| 174 | <P>
|
|---|
| 175 | The <CODE>-forever</CODE> option causes a single operation to be repeatedly
|
|---|
| 176 | tested.
|
|---|
| 177 | Only one rounding mode and/or rounding precision can be tested in a single
|
|---|
| 178 | execution.
|
|---|
| 179 | If not specified, the rounding mode defaults to nearest/even.
|
|---|
| 180 | For <NOBR>80-bit</NOBR> double-extended-precision operations, the rounding
|
|---|
| 181 | precision defaults to full double-extended precision.
|
|---|
| 182 | The testing level is set to 2 by this option.
|
|---|
| 183 | </P>
|
|---|
| 184 |
|
|---|
| 185 | <H3><CODE>-checkNaNs</CODE></H3>
|
|---|
| 186 |
|
|---|
| 187 | <P>
|
|---|
| 188 | The <CODE>-checkNaNs</CODE> option causes <CODE>testfloat</CODE> to verify the
|
|---|
| 189 | bitwise correctness of NaN results.
|
|---|
| 190 | In order for this option to be sensible, <CODE>testfloat</CODE> must have been
|
|---|
| 191 | compiled so that its internal reference implementation of floating-point
|
|---|
| 192 | (Berkeley SoftFloat) generates the proper NaN results for the system being
|
|---|
| 193 | tested.
|
|---|
| 194 | </P>
|
|---|
| 195 |
|
|---|
| 196 | <H3><CODE>-checkInvInts</CODE></H3>
|
|---|
| 197 |
|
|---|
| 198 | <P>
|
|---|
| 199 | The <CODE>-checkInvInts</CODE> option causes <CODE>testfloat</CODE> to verify
|
|---|
| 200 | the bitwise correctness of integer results of invalid operations.
|
|---|
| 201 | In order for this option to be sensible, <CODE>testfloat</CODE> must have been
|
|---|
| 202 | compiled so that its internal reference implementation of floating-point
|
|---|
| 203 | (Berkeley SoftFloat) generates the proper integer results for the system being
|
|---|
| 204 | tested.
|
|---|
| 205 | </P>
|
|---|
| 206 |
|
|---|
| 207 | <H3><CODE>-checkAll</CODE></H3>
|
|---|
| 208 |
|
|---|
| 209 | <P>
|
|---|
| 210 | Enables both <CODE>-checkNaNs</CODE> and <CODE>-checkInvInts</CODE>.
|
|---|
| 211 | </P>
|
|---|
| 212 |
|
|---|
| 213 | <H3><CODE>-precision32, -precision64, -precision80</CODE></H3>
|
|---|
| 214 |
|
|---|
| 215 | <P>
|
|---|
| 216 | For <NOBR>80-bit</NOBR> double-extended-precision operations affected by
|
|---|
| 217 | rounding precision control, the <CODE>-precision32</CODE> option restricts
|
|---|
| 218 | testing to only the cases in which the rounding precision is
|
|---|
| 219 | <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> single-precision.
|
|---|
| 220 | The other rounding precision choices are not tested.
|
|---|
| 221 | Likewise, <CODE>-precision64</CODE> fixes the rounding precision to
|
|---|
| 222 | <NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision, and
|
|---|
| 223 | <CODE>-precision80</CODE> fixes the rounding precision to the full
|
|---|
| 224 | <NOBR>80 bits</NOBR> of the double-extended-precision format.
|
|---|
| 225 | All these options are ignored for operations not affected by rounding precision
|
|---|
| 226 | control.
|
|---|
| 227 | </P>
|
|---|
| 228 |
|
|---|
| 229 | <P>
|
|---|
| 230 | The precision-control options may not be supported at all if no
|
|---|
| 231 | double-extended-precision operations are testable.
|
|---|
| 232 | </P>
|
|---|
| 233 |
|
|---|
| 234 | <H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax, -rodd</CODE></H3>
|
|---|
| 235 |
|
|---|
| 236 | <P>
|
|---|
| 237 | The <CODE>-rnear_even</CODE> option restricts testing to only the cases in
|
|---|
| 238 | which the rounding mode is nearest/even.
|
|---|
| 239 | The other rounding mode choices are not tested.
|
|---|
| 240 | Likewise, <CODE>-rnear_maxMag</CODE> forces rounding to nearest/maximum
|
|---|
| 241 | magnitude (nearest-away), <CODE>-rminMag</CODE> forces rounding to minimum
|
|---|
| 242 | magnitude (toward zero), <CODE>-rmin</CODE> forces rounding to minimum (down,
|
|---|
| 243 | toward negative infinity), <CODE>-rmax</CODE> forces rounding to maximum (up,
|
|---|
| 244 | toward positive infinity), and <CODE>-rodd</CODE>, if supported, forces
|
|---|
| 245 | rounding to odd.
|
|---|
| 246 | These options are ignored for operations that are exact and thus do not round,
|
|---|
| 247 | or that have the rounding mode included in the function name (such as
|
|---|
| 248 | <CODE>f32_to_i32_r_near_maxMag</CODE>).
|
|---|
| 249 | </P>
|
|---|
| 250 |
|
|---|
| 251 | <H3><CODE>-tininessbefore, -tininessafter</CODE></H3>
|
|---|
| 252 |
|
|---|
| 253 | <P>
|
|---|
| 254 | The <CODE>-tininessbefore</CODE> option indicates that the floating-point
|
|---|
| 255 | implementation being tested detects tininess on underflow before rounding.
|
|---|
| 256 | The <CODE>-tininessafter</CODE> option indicates that tininess is detected
|
|---|
| 257 | after rounding.
|
|---|
| 258 | The <CODE>testfloat</CODE> program alters its expectations accordingly.
|
|---|
| 259 | These options override the default selected when <CODE>testfloat</CODE> was
|
|---|
| 260 | compiled.
|
|---|
| 261 | Choosing the wrong one of these two options should cause error reports for some
|
|---|
| 262 | (but not all) operations.
|
|---|
| 263 | </P>
|
|---|
| 264 |
|
|---|
| 265 |
|
|---|
| 266 | <H2>Function Sets</H2>
|
|---|
| 267 |
|
|---|
| 268 | <P>
|
|---|
| 269 | Just as <CODE>testfloat</CODE> can test an operation for all five or six
|
|---|
| 270 | rounding modes in sequence, multiple operations can be tested with a single
|
|---|
| 271 | execution of <CODE>testfloat</CODE>.
|
|---|
| 272 | Two sets are recognized: <CODE>-all1</CODE> and <CODE>-all2</CODE>.
|
|---|
| 273 | The set <CODE>-all1</CODE> is all one-operand operations, while
|
|---|
| 274 | <CODE>-all2</CODE> is all two-operand operations.
|
|---|
| 275 | A function set is used in place of an operation name in the
|
|---|
| 276 | <CODE>testfloat</CODE> command line, such as
|
|---|
| 277 | <BLOCKQUOTE>
|
|---|
| 278 | <PRE>
|
|---|
| 279 | testfloat [<<I>option</I>>...] -all1
|
|---|
| 280 | </PRE>
|
|---|
| 281 | </BLOCKQUOTE>
|
|---|
| 282 | </P>
|
|---|
| 283 |
|
|---|
| 284 |
|
|---|
| 285 | </BODY>
|
|---|
| 286 |
|
|---|
