1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
|
<HTML>
<HEAD>
<TITLE>testfloat_gen</TITLE>
</HEAD>
<BODY>
<H1>Berkeley TestFloat Release 3e: <CODE>testfloat_gen</CODE></H1>
<P>
John R. Hauser<BR>
2018 January 20<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>
|
