You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
771 lines
34 KiB
771 lines
34 KiB
|
|
TestFloat Release 2a General Documentation |
|
|
|
John R. Hauser |
|
1998 December 16 |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Introduction |
|
|
|
TestFloat is a program for testing that a floating-point implementation |
|
conforms to the IEC/IEEE Standard for Binary Floating-Point Arithmetic. |
|
All standard operations supported by the system can be tested, except for |
|
conversions to and from decimal. Any of the following machine formats can |
|
be tested: single precision, double precision, extended double precision, |
|
and/or quadruple precision. |
|
|
|
TestFloat actually comes in two variants: one is a program for testing |
|
a machine's floating-point, and the other is a program for testing |
|
the SoftFloat software implementation of floating-point. (Information |
|
about SoftFloat can be found at the SoftFloat Web page, `http:// |
|
HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.) The version that |
|
tests SoftFloat is expected to be of interest only to people compiling the |
|
SoftFloat sources. However, because the two versions share much in common, |
|
they are discussed together in all the TestFloat documentation. |
|
|
|
This document explains how to use the TestFloat programs. It does not |
|
attempt to define or explain the IEC/IEEE Standard for floating-point. |
|
Details about the standard are available elsewhere. |
|
|
|
The first release of TestFloat (Release 1) was called _FloatTest_. The old |
|
name has been obsolete for some time. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Limitations |
|
|
|
TestFloat's output is not always easily interpreted. Detailed knowledge |
|
of the IEC/IEEE Standard and its vagaries is needed to use TestFloat |
|
responsibly. |
|
|
|
TestFloat performs relatively simple tests designed to check the fundamental |
|
soundness of the floating-point under test. TestFloat may also at times |
|
manage to find rarer and more subtle bugs, but it will probably only find |
|
such bugs by accident. Software that purposefully seeks out various kinds |
|
of subtle floating-point bugs can be found through links posted on the |
|
TestFloat Web page (`http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/ |
|
TestFloat.html'). |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Contents |
|
|
|
Introduction |
|
Limitations |
|
Contents |
|
Legal Notice |
|
What TestFloat Does |
|
Executing TestFloat |
|
Functions Tested by TestFloat |
|
Conversion Functions |
|
Standard Arithmetic Functions |
|
Remainder and Round-to-Integer Functions |
|
Comparison Functions |
|
Interpreting TestFloat Output |
|
Variations Allowed by the IEC/IEEE Standard |
|
Underflow |
|
NaNs |
|
Conversions to Integer |
|
TestFloat Options |
|
-help |
|
-list |
|
-level <num> |
|
-errors <num> |
|
-errorstop |
|
-forever |
|
-checkNaNs |
|
-precision32, -precision64, -precision80 |
|
-nearesteven, -tozero, -down, -up |
|
-tininessbefore, -tininessafter |
|
Function Sets |
|
Contact Information |
|
|
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Legal Notice |
|
|
|
TestFloat was written by John R. Hauser. |
|
|
|
THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort |
|
has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT |
|
TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO |
|
PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY |
|
AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
What TestFloat Does |
|
|
|
TestFloat tests a system's floating-point by comparing its behavior with |
|
that of TestFloat's own internal floating-point implemented in software. |
|
For each operation tested, TestFloat generates a large number of test cases, |
|
made up of simple pattern tests intermixed with weighted random inputs. |
|
The cases generated should be adequate for testing carry chain propagations, |
|
plus the rounding of adds, subtracts, multiplies, and simple operations like |
|
conversions. TestFloat makes a point of checking all boundary cases of the |
|
arithmetic, including underflows, overflows, invalid operations, subnormal |
|
inputs, zeros (positive and negative), infinities, and NaNs. For the |
|
interesting operations like adds and multiplies, literally millions of test |
|
cases can be checked. |
|
|
|
TestFloat is not remarkably good at testing difficult rounding cases for |
|
divisions and square roots. It also makes no attempt to find bugs specific |
|
to SRT divisions and the like (such as the infamous Pentium divide bug). |
|
Software that tests for such failures can be found through links on the |
|
TestFloat Web page, `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/ |
|
TestFloat.html'. |
|
|
|
NOTE! |
|
It is the responsibility of the user to verify that the discrepancies |
|
TestFloat finds actually represent faults in the system being tested. |
|
Advice to help with this task is provided later in this document. |
|
Furthermore, even if TestFloat finds no fault with a floating-point |
|
implementation, that in no way guarantees that the implementation is bug- |
|
free. |
|
|
|
For each operation, TestFloat can test all four rounding modes required |
|
by the IEC/IEEE Standard. TestFloat verifies not only that the numeric |
|
results of an operation are correct, but also that the proper floating-point |
|
exception flags are raised. All five exception flags are tested, including |
|
the inexact flag. TestFloat does not attempt to verify that the floating- |
|
point exception flags are actually implemented as sticky flags. |
|
|
|
For machines that implement extended double precision with rounding |
|
precision control (such as Intel's 80x86), TestFloat can test the add, |
|
subtract, multiply, divide, and square root functions at all the standard |
|
rounding precisions. The rounding precision can be set equivalent to single |
|
precision, to double precision, or to the full extended double precision. |
|
Rounding precision control can only be applied to the extended double- |
|
precision format and only for the five standard arithmetic operations: add, |
|
subtract, multiply, divide, and square root. Other functions can be tested |
|
only at full precision. |
|
|
|
As a rule, TestFloat is not particular about the bit patterns of NaNs that |
|
appear as function results. Any NaN is considered as good a result as |
|
another. This laxness can be overridden so that TestFloat checks for |
|
particular bit patterns within NaN results. See the sections _Variations_ |
|
_Allowed_by_the_IEC/IEEE_Standard_ and _TestFloat_Options_ for details. |
|
|
|
Not all IEC/IEEE Standard functions are supported by all machines. |
|
TestFloat can only test functions that exist on the machine. But even if |
|
a function is supported by the machine, TestFloat may still not be able |
|
to test the function if it is not accessible through standard ISO C (the |
|
programming language in which TestFloat is written) and if the person who |
|
compiled TestFloat did not provide an alternate means for TestFloat to |
|
invoke the machine function. |
|
|
|
TestFloat compares a machine's floating-point against the SoftFloat software |
|
implementation of floating-point, also written by me. SoftFloat is built |
|
into the TestFloat executable and does not need to be supplied by the user. |
|
If SoftFloat is wanted for some other reason (to compile a new version |
|
of TestFloat, for instance), it can be found separately at the Web page |
|
`http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. |
|
|
|
For testing SoftFloat itself, the TestFloat package includes a program that |
|
compares SoftFloat's floating-point against _another_ software floating- |
|
point implementation. The second software floating-point is simpler and |
|
slower than SoftFloat, and is completely independent of SoftFloat. Although |
|
the second software floating-point cannot be guaranteed to be bug-free, the |
|
chance that it would mimic any of SoftFloat's bugs is remote. Consequently, |
|
an error in one or the other floating-point version should appear as an |
|
unexpected discrepancy between the two implementations. Note that testing |
|
SoftFloat should only be necessary when compiling a new TestFloat executable |
|
or when compiling SoftFloat for some other reason. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Executing TestFloat |
|
|
|
TestFloat is intended to be executed from a command line interpreter. The |
|
`testfloat' program is invoked as follows: |
|
|
|
testfloat [<option>...] <function> |
|
|
|
Here square brackets ([]) indicate optional items, while angled brackets |
|
(<>) denote parameters to be filled in. |
|
|
|
The `<function>' argument is a name like `float32_add' or `float64_to_int32'. |
|
The complete list of function names is given in the next section, |
|
_Functions_Tested_by_TestFloat_. It is also possible to test all machine |
|
functions in a single invocation. The various options to TestFloat are |
|
detailed in the section _TestFloat_Options_ later in this document. If |
|
`testfloat' is executed without any arguments, a summary of TestFloat usage |
|
is written. |
|
|
|
TestFloat will ordinarily test a function for all four rounding modes, one |
|
after the other. If the rounding mode is not supposed to have any affect |
|
on the results--for instance, some operations do not require rounding--only |
|
the nearest/even rounding mode is checked. For extended double-precision |
|
operations affected by rounding precision control, TestFloat also tests all |
|
three rounding precision modes, one after the other. Testing can be limited |
|
to a single rounding mode and/or rounding precision with appropriate options |
|
(see _TestFloat_Options_). |
|
|
|
As it executes, TestFloat writes status information to the standard error |
|
output, which should be the screen by default. In order for this status to |
|
be displayed properly, the standard error stream should not be redirected |
|
to a file. The discrepancies TestFloat finds are written to the standard |
|
output stream, which is easily redirected to a file if desired. Ordinarily, |
|
the errors TestFloat reports and the ongoing status information appear |
|
intermixed on the same screen. |
|
|
|
The version of TestFloat for testing SoftFloat is called `testsoftfloat'. |
|
It is invoked the same as `testfloat', |
|
|
|
testsoftfloat [<option>...] <function> |
|
|
|
and operates similarly. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Functions Tested by TestFloat |
|
|
|
TestFloat tests all operations required by the IEC/IEEE Standard except for |
|
conversions to and from decimal. The operations are |
|
|
|
-- Conversions among the supported floating-point formats, and also between |
|
integers (32-bit and 64-bit) and any of the floating-point formats. |
|
|
|
-- The usual add, subtract, multiply, divide, and square root operations |
|
for all supported floating-point formats. |
|
|
|
-- For each format, the floating-point remainder operation defined by the |
|
IEC/IEEE Standard. |
|
|
|
-- For each floating-point format, a ``round to integer'' operation that |
|
rounds to the nearest integer value in the same format. (The floating- |
|
point formats can hold integer values, of course.) |
|
|
|
-- Comparisons between two values in the same floating-point format. |
|
|
|
Detailed information about these functions is given below. In the function |
|
names used by TestFloat, single precision is called `float32', double |
|
precision is `float64', extended double precision is `floatx80', and |
|
quadruple precision is `float128'. TestFloat uses the same names for |
|
functions as SoftFloat. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
Conversion Functions |
|
|
|
All conversions among the floating-point formats and all conversion between |
|
a floating-point format and 32-bit and 64-bit signed integers can be tested. |
|
The conversion functions are: |
|
|
|
int32_to_float32 int64_to_float32 |
|
int32_to_float64 int64_to_float32 |
|
int32_to_floatx80 int64_to_floatx80 |
|
int32_to_float128 int64_to_float128 |
|
|
|
float32_to_int32 float32_to_int64 |
|
float32_to_int32 float64_to_int64 |
|
floatx80_to_int32 floatx80_to_int64 |
|
float128_to_int32 float128_to_int64 |
|
|
|
float32_to_float64 float32_to_floatx80 float32_to_float128 |
|
float64_to_float32 float64_to_floatx80 float64_to_float128 |
|
floatx80_to_float32 floatx80_to_float64 floatx80_to_float128 |
|
float128_to_float32 float128_to_float64 float128_to_floatx80 |
|
|
|
These conversions all round according to the current rounding mode as |
|
necessary. Conversions from a smaller to a larger floating-point format are |
|
always exact and so require no rounding. Conversions from 32-bit integers |
|
to double precision or to any larger floating-point format are also exact, |
|
and likewise for conversions from 64-bit integers to extended double and |
|
quadruple precisions. |
|
|
|
ISO/ANSI C requires that conversions to integers be rounded toward zero. |
|
Such conversions can be tested with the following functions that ignore any |
|
rounding mode: |
|
|
|
float32_to_int32_round_to_zero float32_to_int64_round_to_zero |
|
float64_to_int32_round_to_zero float64_to_int64_round_to_zero |
|
floatx80_to_int32_round_to_zero floatx80_to_int64_round_to_zero |
|
float128_to_int32_round_to_zero float128_to_int64_round_to_zero |
|
|
|
TestFloat assumes that conversions from floating-point to integer should |
|
raise the invalid exception if the source value cannot be rounded to a |
|
representable integer of the desired size (32 or 64 bits). If such a |
|
conversion overflows, TestFloat expects the largest integer with the same |
|
sign as the operand to be returned. If the floating-point operand is a NaN, |
|
TestFloat allows either the largest positive or largest negative integer to |
|
be returned. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
Standard Arithmetic Functions |
|
|
|
The following standard arithmetic functions can be tested: |
|
|
|
float32_add float32_sub float32_mul float32_div float32_sqrt |
|
float64_add float64_sub float64_mul float64_div float64_sqrt |
|
floatx80_add floatx80_sub floatx80_mul floatx80_div floatx80_sqrt |
|
float128_add float128_sub float128_mul float128_div float128_sqrt |
|
|
|
The extended double-precision (`floatx80') functions can be rounded to |
|
reduced precision under rounding precision control. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
Remainder and Round-to-Integer Functions |
|
|
|
For each format, TestFloat can test the IEC/IEEE Standard remainder and |
|
round-to-integer functions. The remainder functions are: |
|
|
|
float32_rem |
|
float64_rem |
|
floatx80_rem |
|
float128_rem |
|
|
|
The round-to-integer functions are: |
|
|
|
float32_round_to_int |
|
float64_round_to_int |
|
floatx80_round_to_int |
|
float128_round_to_int |
|
|
|
The remainder functions are always exact and so do not require rounding. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
Comparison Functions |
|
|
|
The following floating-point comparison functions can be tested: |
|
|
|
float32_eq float32_le float32_lt |
|
float64_eq float64_le float64_lt |
|
floatx80_eq floatx80_le floatx80_lt |
|
float128_eq float128_le float128_lt |
|
|
|
The abbreviation `eq' stands for ``equal'' (=); `le' stands for ``less than |
|
or equal'' (<=); and `lt' stands for ``less than'' (<). |
|
|
|
The IEC/IEEE Standard specifies that the less-than-or-equal and less-than |
|
functions raise the invalid exception if either input is any kind of NaN. |
|
The equal functions, for their part, are defined not to raise the invalid |
|
exception on quiet NaNs. For completeness, the following additional |
|
functions can be tested if supported: |
|
|
|
float32_eq_signaling float32_le_quiet float32_lt_quiet |
|
float64_eq_signaling float64_le_quiet float64_lt_quiet |
|
floatx80_eq_signaling floatx80_le_quiet floatx80_lt_quiet |
|
float128_eq_signaling float128_le_quiet float128_lt_quiet |
|
|
|
The `signaling' equal functions are identical to the standard functions |
|
except that the invalid exception should be raised for any NaN input. |
|
Likewise, the `quiet' comparison functions should be identical to their |
|
counterparts except that the invalid exception is not raised for quiet NaNs. |
|
|
|
Obviously, no comparison functions ever require rounding. Any rounding mode |
|
is ignored. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Interpreting TestFloat Output |
|
|
|
The ``errors'' reported by TestFloat may or may not really represent errors |
|
in the system being tested. For each test case tried, TestFloat performs |
|
the same floating-point operation for the two implementations being compared |
|
and reports any unexpected difference in the results. The two results could |
|
differ for several reasons: |
|
|
|
-- The IEC/IEEE Standard allows for some variation in how conforming |
|
floating-point behaves. Two implementations can occasionally give |
|
different results without either being incorrect. |
|
|
|
-- The trusted floating-point emulation could be faulty. This could be |
|
because there is a bug in the way the enulation is coded, or because a |
|
mistake was made when the code was compiled for the current system. |
|
|
|
-- TestFloat may not work properly, reporting discrepancies that do not |
|
exist. |
|
|
|
-- Lastly, the floating-point being tested could actually be faulty. |
|
|
|
It is the responsibility of the user to determine the causes for the |
|
discrepancies TestFloat reports. Making this determination can require |
|
detailed knowledge about the IEC/IEEE Standard. Assuming TestFloat is |
|
working properly, any differences found will be due to either the first or |
|
last of these reasons. Variations in the IEC/IEEE Standard that could lead |
|
to false error reports are discussed in the section _Variations_Allowed_by_ |
|
_the_IEC/IEEE_Standard_. |
|
|
|
For each error (or apparent error) TestFloat reports, a line of text |
|
is written to the default output. If a line would be longer than 79 |
|
characters, it is divided. The first part of each error line begins in the |
|
leftmost column, and any subsequent ``continuation'' lines are indented with |
|
a tab. |
|
|
|
Each error reported by `testfloat' is of the form: |
|
|
|
<inputs> soft: <output-from-emulation> syst: <output-from-system> |
|
|
|
The `<inputs>' are the inputs to the operation. Each output is shown as a |
|
pair: the result value first, followed by the exception flags. The `soft' |
|
label stands for ``software'' (or ``SoftFloat''), while `syst' stands for |
|
``system,'' the machine's floating-point. |
|
|
|
For example, two typical error lines could be |
|
|
|
800.7FFF00 87F.000100 soft: 001.000000 ....x syst: 001.000000 ...ux |
|
081.000004 000.1FFFFF soft: 001.000000 ....x syst: 001.000000 ...ux |
|
|
|
In the first line, the inputs are `800.7FFF00' and `87F.000100'. The |
|
internal emulation result is `001.000000' with flags `....x', and the |
|
system result is the same but with flags `...ux'. All the items composed of |
|
hexadecimal digits and a single period represent floating-point values (here |
|
single precision). These cases were reported as errors because the flag |
|
results differ. |
|
|
|
In addition to the exception flags, there are seven data types that may |
|
be represented. Four are floating-point types: single precision, double |
|
precision, extended double precision, and quadruple precision. The |
|
remaining three types are 32-bit and 64-bit two's-complement integers and |
|
Boolean values (the results of comparison operations). Boolean values are |
|
represented as a single character, either a `0' or a `1'. 32-bit integers |
|
are written as 8 hexadecimal digits in two's-complement form. Thus, |
|
`FFFFFFFF' is -1, and `7FFFFFFF' is the largest positive 32-bit integer. |
|
64-bit integers are the same except with 16 hexadecimal digits. |
|
|
|
Floating-point values are written in a correspondingly primitive form. |
|
Double-precision values are represented by 16 hexadecimal digits that give |
|
the raw bits of the floating-point encoding. A period separates the 3rd and |
|
4th hexadecimal digits to mark the division between the exponent bits and |
|
fraction bits. Some notable double-precision values include: |
|
|
|
000.0000000000000 +0 |
|
3FF.0000000000000 1 |
|
400.0000000000000 2 |
|
7FF.0000000000000 +infinity |
|
|
|
800.0000000000000 -0 |
|
BFF.0000000000000 -1 |
|
C00.0000000000000 -2 |
|
FFF.0000000000000 -infinity |
|
|
|
3FE.FFFFFFFFFFFFF largest representable number preceding +1 |
|
|
|
The following categories are easily distinguished (assuming the `x's are not |
|
all 0): |
|
|
|
000.xxxxxxxxxxxxx positive subnormal (denormalized) numbers |
|
7FF.xxxxxxxxxxxxx positive NaNs |
|
800.xxxxxxxxxxxxx negative subnormal numbers |
|
FFF.xxxxxxxxxxxxx negative NaNs |
|
|
|
Quadruple-precision values are written the same except with 4 hexadecimal |
|
digits for the sign and exponent and 28 for the fraction. Notable values |
|
include: |
|
|
|
0000.0000000000000000000000000000 +0 |
|
3FFF.0000000000000000000000000000 1 |
|
4000.0000000000000000000000000000 2 |
|
7FFF.0000000000000000000000000000 +infinity |
|
|
|
8000.0000000000000000000000000000 -0 |
|
BFFF.0000000000000000000000000000 -1 |
|
C000.0000000000000000000000000000 -2 |
|
FFFF.0000000000000000000000000000 -infinity |
|
|
|
3FFE.FFFFFFFFFFFFFFFFFFFFFFFFFFFF largest representable number |
|
preceding +1 |
|
|
|
Extended double-precision values are a little unusual in that the leading |
|
significand bit is not hidden as with other formats. When correctly |
|
encoded, the leading significand bit of an extended double-precision value |
|
will be 0 if the value is zero or subnormal, and will be 1 otherwise. |
|
Hence, the same values listed above appear in extended double-precision as |
|
follows (note the leading `8' digit in the significands): |
|
|
|
0000.0000000000000000 +0 |
|
3FFF.8000000000000000 1 |
|
4000.8000000000000000 2 |
|
7FFF.8000000000000000 +infinity |
|
|
|
8000.0000000000000000 -0 |
|
BFFF.8000000000000000 -1 |
|
C000.8000000000000000 -2 |
|
FFFF.8000000000000000 -infinity |
|
|
|
3FFE.FFFFFFFFFFFFFFFF largest representable number preceding +1 |
|
|
|
The representation of single-precision values is unusual for a different |
|
reason. Because the subfields of standard single-precision do not fall |
|
on neat 4-bit boundaries, single-precision outputs are slightly perturbed. |
|
These are written as 9 hexadecimal digits, with a period separating the 3rd |
|
and 4th hexadecimal digits. Broken out into bits, the 9 hexademical digits |
|
cover the single-precision subfields as follows: |
|
|
|
x000 .... .... . .... .... .... .... .... .... sign (1 bit) |
|
.... xxxx xxxx . .... .... .... .... .... .... exponent (8 bits) |
|
.... .... .... . 0xxx xxxx xxxx xxxx xxxx xxxx fraction (23 bits) |
|
|
|
As shown in this schematic, the first hexadecimal digit contains only |
|
the sign, and will be either `0' or `8'. The next two digits give the |
|
biased exponent as an 8-bit integer. This is followed by a period and |
|
6 hexadecimal digits of fraction. The most significant hexadecimal digit |
|
of the fraction can be at most a `7'. |
|
|
|
Notable single-precision values include: |
|
|
|
000.000000 +0 |
|
07F.000000 1 |
|
080.000000 2 |
|
0FF.000000 +infinity |
|
|
|
800.000000 -0 |
|
87F.000000 -1 |
|
880.000000 -2 |
|
8FF.000000 -infinity |
|
|
|
07E.7FFFFF largest representable number preceding +1 |
|
|
|
Again, certain categories are easily distinguished (assuming the `x's are |
|
not all 0): |
|
|
|
000.xxxxxx positive subnormal (denormalized) numbers |
|
0FF.xxxxxx positive NaNs |
|
800.xxxxxx negative subnormal numbers |
|
8FF.xxxxxx negative NaNs |
|
|
|
Lastly, exception flag values are represented by five characters, one |
|
character per flag. Each flag is written as either a letter or a period |
|
(`.') according to whether the flag was set or not by the operation. A |
|
period indicates the flag was not set. The letter used to indicate a set |
|
flag depends on the flag: |
|
|
|
v invalid flag |
|
z division-by-zero flag |
|
o overflow flag |
|
u underflow flag |
|
x inexact flag |
|
|
|
For example, the notation `...ux' indicates that the underflow and inexact |
|
exception flags were set and that the other three flags (invalid, division- |
|
by-zero, and overflow) were not set. The exception flags are always shown |
|
following the value returned as the result of the operation. |
|
|
|
The output from `testsoftfloat' is of the same form, except that the results |
|
are labeled `true' and `soft': |
|
|
|
<inputs> true: <simple-software-result> soft: <SoftFloat-result> |
|
|
|
The ``true'' result is from the simpler, slower software floating-point, |
|
which, although not necessarily correct, is more likely to be right than |
|
the SoftFloat (`soft') result. |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Variations Allowed by the IEC/IEEE Standard |
|
|
|
The IEC/IEEE Standard admits some variation among conforming |
|
implementations. Because TestFloat expects the two implementations being |
|
compared to deliver bit-for-bit identical results under most circumstances, |
|
this leeway in the standard can result in false errors being reported if |
|
the two implementations do not make the same choices everywhere the standard |
|
provides an option. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
Underflow |
|
|
|
The standard specifies that the underflow exception flag is to be raised |
|
when two conditions are met simultaneously: (1) _tininess_ and (2) _loss_ |
|
_of_accuracy_. A result is tiny when its magnitude is nonzero yet smaller |
|
than any normalized floating-point number. The standard allows tininess to |
|
be determined either before or after a result is rounded to the destination |
|
precision. If tininess is detected before rounding, some borderline cases |
|
will be flagged as underflows even though the result after rounding actually |
|
lies within the normal floating-point range. By detecting tininess after |
|
rounding, a system can avoid some unnecessary signaling of underflow. |
|
|
|
Loss of accuracy occurs when the subnormal format is not sufficient |
|
to represent an underflowed result accurately. The standard allows |
|
loss of accuracy to be detected either as an _inexact_result_ or as a |
|
_denormalization_loss_. If loss of accuracy is detected as an inexact |
|
result, the underflow flag is raised whenever an underflowed quantity |
|
cannot be exactly represented in the subnormal format (that is, whenever the |
|
inexact flag is also raised). A denormalization loss, on the other hand, |
|
occurs only when the subnormal format is not able to represent the result |
|
that would have been returned if the destination format had infinite range. |
|
Some underflowed results are inexact but do not suffer a denormalization |
|
loss. By detecting loss of accuracy as a denormalization loss, a system can |
|
once again avoid some unnecessary signaling of underflow. |
|
|
|
The `-tininessbefore' and `-tininessafter' options can be used to control |
|
whether TestFloat expects tininess on underflow to be detected before or |
|
after rounding. (See _TestFloat_Options_ below.) One or the other is |
|
selected as the default when TestFloat is compiled, but these command |
|
options allow the default to be overridden. |
|
|
|
Most (possibly all) systems detect loss of accuracy as an inexact result. |
|
The current version of TestFloat can only test for this case. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
NaNs |
|
|
|
The IEC/IEEE Standard gives the floating-point formats a large number of |
|
NaN encodings and specifies that NaNs are to be returned as results under |
|
certain conditions. However, the standard allows an implementation almost |
|
complete freedom over _which_ NaN to return in each situation. |
|
|
|
By default, TestFloat does not check the bit patterns of NaN results. When |
|
the result of an operation should be a NaN, any NaN is considered as good |
|
as another. This laxness can be overridden with the `-checkNaNs' option. |
|
(See _TestFloat_Options_ below.) In order for this option to be sensible, |
|
TestFloat must have been compiled so that its internal floating-point |
|
implementation (SoftFloat) generates the proper NaN results for the system |
|
being tested. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
Conversions to Integer |
|
|
|
Conversion of a floating-point value to an integer format will fail if the |
|
source value is a NaN or if it is too large. The IEC/IEEE Standard does not |
|
specify what value should be returned as the integer result in these cases. |
|
Moreover, according to the standard, the invalid exception can be raised or |
|
an unspecified alternative mechanism may be used to signal such cases. |
|
|
|
TestFloat assumes that conversions to integer will raise the invalid |
|
exception if the source value cannot be rounded to a representable integer. |
|
When the conversion overflows, TestFloat expects the largest integer with |
|
the same sign as the operand to be returned. If the floating-point operand |
|
is a NaN, TestFloat allows either the largest positive or largest negative |
|
integer to be returned. The current version of TestFloat provides no means |
|
to alter these conventions. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
TestFloat Options |
|
|
|
The `testfloat' (and `testsoftfloat') program accepts several command |
|
options. If mutually contradictory options are given, the last one has |
|
priority. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-help |
|
|
|
The `-help' option causes a summary of program usage to be written, after |
|
which the program exits. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-list |
|
|
|
The `-list' option causes a list of testable functions to be written, |
|
after which the program exits. Some machines do not implement all of the |
|
functions TestFloat can test, plus it may not be possible to test functions |
|
that are inaccessible from the C language. |
|
|
|
The `testsoftfloat' program does not have this option. All SoftFloat |
|
functions can be tested by `testsoftfloat'. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-level <num> |
|
|
|
The `-level' option sets the level of testing. The argument to `-level' can |
|
be either 1 or 2. The default is level 1. Level 2 performs many more tests |
|
than level 1. Testing at level 2 can take as much as a day (even longer for |
|
`testsoftfloat'), but can reveal bugs not found by level 1. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-errors <num> |
|
|
|
The `-errors' option instructs TestFloat to report no more than the |
|
specified number of errors for any combination of function, rounding mode, |
|
etc. The argument to `-errors' must be a nonnegative decimal number. Once |
|
the specified number of error reports has been generated, TestFloat ends the |
|
current test and begins the next one, if any. The default is `-errors 20'. |
|
|
|
Against intuition, `-errors 0' causes TestFloat to report every error it |
|
finds. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-errorstop |
|
|
|
The `-errorstop' option causes the program to exit after the first function |
|
for which any errors are reported. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-forever |
|
|
|
The `-forever' option causes a single operation to be repeatedly tested. |
|
Only one rounding mode and/or rounding precision can be tested in a single |
|
invocation. If not specified, the rounding mode defaults to nearest/even. |
|
For extended double-precision operations, the rounding precision defaults |
|
to full extended double precision. The testing level is set to 2 by this |
|
option. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-checkNaNs |
|
|
|
The `-checkNaNs' option causes TestFloat to verify the bitwise correctness |
|
of NaN results. In order for this option to be sensible, TestFloat must |
|
have been compiled so that its internal floating-point implementation |
|
(SoftFloat) generates the proper NaN results for the system being tested. |
|
|
|
This option is not available to `testsoftfloat'. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-precision32, -precision64, -precision80 |
|
|
|
For extended double-precision functions affected by rounding precision |
|
control, the `-precision32' option restricts testing to only the cases |
|
in which rounding precision is equivalent to single precision. The other |
|
rounding precision options are not tested. Likewise, the `-precision64' |
|
and `-precision80' options fix the rounding precision equivalent to double |
|
precision or extended double precision, respectively. These options are |
|
ignored for functions not affected by rounding precision control. |
|
|
|
These options are not available if extended double precision is not |
|
supported by the machine or if extended double precision functions cannot be |
|
tested. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-nearesteven, -tozero, -down, -up |
|
|
|
The `-nearesteven' option restricts testing to only the cases in which the |
|
rounding mode is nearest/even. The other rounding mode options are not |
|
tested. Likewise, `-tozero' forces rounding to zero; `-down' forces |
|
rounding down; and `-up' forces rounding up. These options are ignored for |
|
functions that are exact and thus do not round. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
-tininessbefore, -tininessafter |
|
|
|
The `-tininessbefore' option indicates that the system detects tininess |
|
on underflow before rounding. The `-tininessafter' option indicates that |
|
tininess is detected after rounding. TestFloat alters its expectations |
|
accordingly. These options override the default selected when TestFloat was |
|
compiled. Choosing the wrong one of these two options should cause error |
|
reports for some (not all) functions. |
|
|
|
For `testsoftfloat', these options operate more like the rounding precision |
|
and rounding mode options, in that they restrict the tests performed by |
|
`testsoftfloat'. By default, `testsoftfloat' tests both cases for any |
|
function for which there is a difference. |
|
|
|
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Function Sets |
|
|
|
Just as TestFloat can test an operation for all four rounding modes in |
|
sequence, multiple operations can be tested with a single invocation of |
|
TestFloat. Three sets are recognized: `-all1', `-all2', and `-all'. The |
|
set `-all1' comprises all one-operand functions; `-all2' is all two-operand |
|
functions; and `-all' is all functions. A function set can be used in place |
|
of a function name in the TestFloat command line, such as |
|
|
|
testfloat [<option>...] -all |
|
|
|
|
|
------------------------------------------------------------------------------- |
|
Contact Information |
|
|
|
At the time of this writing, the most up-to-date information about |
|
TestFloat and the latest release can be found at the Web page `http:// |
|
HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/TestFloat.html'. |
|
|
|
|
|
|