From cec54960bbbfa351cab7dab75eb1418585e4fe64 Mon Sep 17 00:00:00 2001 From: John Hauser Date: Wed, 17 Dec 2014 19:09:39 -0800 Subject: Finalized documentation for TestFloat Release 3. --- doc/TestFloat-general.html | 507 +++++++++++++++++++++++++++------------------ 1 file changed, 305 insertions(+), 202 deletions(-) (limited to 'doc/TestFloat-general.html') diff --git a/doc/TestFloat-general.html b/doc/TestFloat-general.html index 1618d4a..d72807e 100644 --- a/doc/TestFloat-general.html +++ b/doc/TestFloat-general.html @@ -11,49 +11,38 @@

John R. Hauser
-2014 ______
-

- -

-*** CONTENT DONE. -

- -

-*** REPLACE QUOTATION MARKS. -
-*** REPLACE APOSTROPHES. -
-*** REPLACE EM DASH. +2014 Dec 17

Contents

-

-*** CHECK.
-*** FIX FORMATTING. -

- -
-    Introduction
-    Limitations
-    Acknowledgments and License
-    What TestFloat Does
-    Executing TestFloat
-    Operations Tested by TestFloat
-        Conversion Operations
-        Basic Arithmetic Operations
-        Fused Multiply-Add Operations
-        Remainder Operations
-        Round-to-Integer Operations
-        Comparison Operations
-    Interpreting TestFloat Output
-    Variations Allowed by the IEEE Floating-Point Standard
-        Underflow
-        NaNs
-        Conversions to Integer
-    Contact Information
-
+
+ +++ + + + + + + + + + + + + + + + + + + + +
1. Introduction
2. Limitations
3. Acknowledgments and License
4. What TestFloat Does
5. Executing TestFloat
6. Operations Tested by TestFloat
6.1. Conversion Operations
6.2. Basic Arithmetic Operations
6.3. Fused Multiply-Add Operations
6.4. Remainder Operations
6.5. Round-to-Integer Operations
6.6. Comparison Operations
7. Interpreting TestFloat Output
8. Variations Allowed by the IEEE Floating-Point Standard
8.1. Underflow
8.2. NaNs
8.3. Conversions to Integer
9. Contact Information
+

1. Introduction

@@ -89,8 +78,8 @@ Details about the standard are available elsewhere.

The current version of TestFloat is Release 3. -The set of TestFloat programs as well as the programs' arguments and behavior -have changed some compared to earlier TestFloat releases. +The set of TestFloat programs as well as the programs’ arguments and +behavior have changed some compared to earlier TestFloat releases.

@@ -119,15 +108,20 @@ bugs can be found through links posted on the TestFloat Web page The TestFloat package was written by me, John R. Hauser. Release 3 of TestFloat is a completely new implementation supplanting earlier releases. -This project was done in the employ of the University of California, Berkeley, -within the Department of Electrical Engineering and Computer Sciences, first -for the Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab. +This project (Release 3 only, not earlier releases) was done in +the employ of the University of California, Berkeley, within the Department of +Electrical Engineering and Computer Sciences, first for the Parallel Computing +Laboratory (Par Lab) and then for the ASPIRE Lab. The work was officially overseen by Prof. Krste Asanovic, with funding provided by these sources:
+++ - + + - + +
Par Lab:Par Lab: Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery (Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, @@ -135,7 +129,8 @@ NVIDIA, Oracle, and Samsung.
ASPIRE Lab:ASPIRE Lab: DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, @@ -191,8 +186,8 @@ ENHANCEMENTS, OR MODIFICATIONS.

TestFloat is designed to test a floating-point implementation by comparing its -behavior with that of TestFloat's own internal floating-point implemented in -software. +behavior with that of TestFloat’s own internal floating-point implemented +in software. For each operation to be tested, the TestFloat programs can generate a large number of test cases, made up of simple pattern tests intermixed with weighted random inputs. @@ -263,19 +258,20 @@ for programs testfloat_ver and testfloat. TestFloat normally compares an implementation of floating-point against the Berkeley SoftFloat software implementation of floating-point, also created by me. -The SoftFloat functions are linked into each TestFloat program's executable. +The SoftFloat functions are linked into each TestFloat program’s +executable. Information about SoftFloat can be found at the Web page http://www.jhauser.us/arithmetic/SoftFloat.html.

For testing SoftFloat itself, the TestFloat package includes a -testsoftfloat program that compares SoftFloat's floating-point -against another software floating-point implementation. +testsoftfloat 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 low. +bug-free, the chance that it would mimic any of SoftFloat’s bugs is low. Consequently, an error in one or the other floating-point version should appear as an unexpected difference between the two implementations. Note that testing SoftFloat should be necessary only when compiling a new @@ -347,9 +343,11 @@ These results can then be piped to testfloat_ver to be checked for correctness. Assuming a vertical bar (|) indicates a pipe between programs, the complete process could be written as a single command like so: +

-     testfloat_gen ... <type> | <program-that-invokes-op> | testfloat_ver ... <function>
+testfloat_gen ... <type> | <program-that-invokes-op> | testfloat_ver ... <function>
+
The program in the middle is not supplied by TestFloat but must be created independently. If for some reason this program cannot take command-line arguments, the @@ -363,9 +361,11 @@ A second method for running TestFloat is similar but has expected results for each case. With this additional information, the job done by testfloat_ver can be folded into the invoking program to give the following command: +
-     testfloat_gen ... <function> | <program-that-invokes-op-and-compares-results>
+testfloat_gen ... <function> | <program-that-invokes-op-and-compares-results>
+
Again, the program that actually invokes the floating-point operation is not supplied by TestFloat but must be created independently. Depending on circumstance, it may be preferable either to let @@ -429,8 +429,8 @@ multiplication, division, and square root operations; for each format, the floating-point remainder operation defined by the IEEE Standard;
  • -for each format, a ``round to integer'' operation that rounds to the nearest -integer value in the same format; and +for each format, a “round to integer” operation that rounds to the +nearest integer value in the same format; and
  • comparisons between two values in the same floating-point format. @@ -451,8 +451,8 @@ is called f32, 64-bit double-precision is extF80, and 128-bit quadruple-precision is f128. TestFloat generally uses the same names for operations as Berkeley SoftFloat, -except that TestFloat's names never include the M that SoftFloat -uses to indicate that values are passed through pointers. +except that TestFloat’s names never include the M that +SoftFloat uses to indicate that values are passed through pointers.

    6.1. Conversion Operations

    @@ -462,21 +462,23 @@ All conversions among the floating-point formats and all conversions between a floating-point format and 32-bit and 64-bit integers can be tested. The conversion operations are: +
    -     ui32_to_f32      ui64_to_f32      i32_to_f32       i64_to_f32
-     ui32_to_f64      ui64_to_f64      i32_to_f64       i64_to_f64
-     ui32_to_extF80   ui64_to_extF80   i32_to_extF80    i64_to_extF80
-     ui32_to_f128     ui64_to_f128     i32_to_f128      i64_to_f128
-
-     f32_to_ui32      f64_to_ui32      extF80_to_ui32   f128_to_ui32
-     f32_to_ui64      f64_to_ui64      extF80_to_ui64   f128_to_ui64
-     f32_to_i32       f64_to_i32       extF80_to_i32    f128_to_i32
-     f32_to_i64       f64_to_i64       extF80_to_i64    f128_to_i64
-
-     f32_to_f64       f64_to_f32       extF80_to_f32    f128_to_f32
-     f32_to_extF80    f64_to_extF80    extF80_to_f64    f128_to_f64
-     f32_to_f128      f64_to_f128      extF80_to_f128   f128_to_extF80
+ui32_to_f32      ui64_to_f32      i32_to_f32       i64_to_f32
+ui32_to_f64      ui64_to_f64      i32_to_f64       i64_to_f64
+ui32_to_extF80   ui64_to_extF80   i32_to_extF80    i64_to_extF80
+ui32_to_f128     ui64_to_f128     i32_to_f128      i64_to_f128
+
+f32_to_ui32      f64_to_ui32      extF80_to_ui32   f128_to_ui32
+f32_to_ui64      f64_to_ui64      extF80_to_ui64   f128_to_ui64
+f32_to_i32       f64_to_i32       extF80_to_i32    f128_to_i32
+f32_to_i64       f64_to_i64       extF80_to_i64    f128_to_i64
+
+f32_to_f64       f64_to_f32       extF80_to_f32    f128_to_f32
+f32_to_extF80    f64_to_extF80    extF80_to_f64    f128_to_f64
+f32_to_f128      f64_to_f128      extF80_to_f128   f128_to_extF80
    +
    Abbreviations ui32 and ui64 indicate 32-bit and 64-bit unsigned integer types, while i32 and i64 indicate their signed counterparts. @@ -495,22 +497,27 @@ operations requires amendment. For testfloat only, conversions to an integer type have names that explicitly specify the rounding mode and treatment of inexactness. Thus, instead of +
    -     <float>_to_<int>
+<float>_to_<int>
    +
    as listed above, operations converting to integer type have names of these forms: +
    -     <float>_to_<int>_r_<round>
-     <float>_to_<int>_rx_<round>
+<float>_to_<int>_r_<round>
+<float>_to_<int>_rx_<round>
    -The <round> component is one of `near_even', -`near_maxMag', `minMag', `min', or -`max', choosing the rounding mode. +
    +The <round> component is one of +‘near_even’, ‘near_maxMag’, +‘minMag’, ‘min’, or +‘max’, choosing the rounding mode. Any other indication of rounding mode is ignored. -The operations with `_r_' in their names never raise the -inexact exception, while those with `_rx_' raise the -inexact exception whenever the result is not exact. +The operations with ‘_r_’ in their names never raise +the inexact exception, while those with ‘_rx_’ +raise the inexact exception whenever the result is not exact.

    @@ -518,7 +525,8 @@ TestFloat assumes that conversions from floating-point to an integer type should raise the invalid exception if the input cannot be rounded to an integer representable by the result format. In such a circumstance, if the result type is an unsigned integer, TestFloat -expects the result of the operation to be the type's largest integer value. +expects the result of the operation to be the type’s largest integer +value. If the result type is a signed integer and conversion overflows, TestFloat expects the result to be the largest-magnitude integer with the same sign as the input. @@ -533,12 +541,14 @@ exception.

    The following standard arithmetic operations can be tested: +

    -     f32_add      f32_sub      f32_mul      f32_div      f32_sqrt
-     f64_add      f64_sub      f64_mul      f64_div      f64_sqrt
-     extF80_add   extF80_sub   extF80_mul   extF80_div   extF80_sqrt
-     f128_add     f128_sub     f128_mul     f128_div     f128_sqrt
+f32_add      f32_sub      f32_mul      f32_div      f32_sqrt
+f64_add      f64_sub      f64_mul      f64_div      f64_sqrt
+extF80_add   extF80_sub   extF80_mul   extF80_div   extF80_sqrt
+f128_add     f128_sub     f128_mul     f128_div     f128_sqrt
    +
    The double-extended-precision (extF80) operations can be rounded to reduced precision under rounding precision control.

    @@ -550,11 +560,13 @@ For all floating-point formats except 80-bit double-extended-precision, TestFloat can test the fused multiply-add operation defined by the 2008 IEEE Floating-Point Standard. The fused multiply-add operations are: +
    -     f32_mulAdd
-     f64_mulAdd
-     f128_mulAdd
+f32_mulAdd
+f64_mulAdd
+f128_mulAdd
    +

    @@ -566,29 +578,34 @@ exception even if the third operand is a NaN.

    6.4. Remainder Operations

    -For each format, TestFloat can test the IEEE Standard's remainder operation. +For each format, TestFloat can test the IEEE Standard’s remainder +operation. These operations are: +

    -     f32_rem
-     f64_rem
-     extF80_rem
-     f128_rem
+f32_rem
+f64_rem
+extF80_rem
+f128_rem
    +
    The remainder operations are always exact and so require no rounding.

    6.5. Round-to-Integer Operations

    -For each format, TestFloat can test the IEEE Standard's round-to-integer +For each format, TestFloat can test the IEEE Standard’s round-to-integer operation. For most TestFloat programs, these operations are: +

    -     f32_roundToInt
-     f64_roundToInt
-     extF80_roundToInt
-     f128_roundToInt
+f32_roundToInt
+f64_roundToInt
+extF80_roundToInt
+f128_roundToInt
    +

    @@ -596,35 +613,40 @@ Just as for conversions to integer types (section 6.1 above), the all-in-one testfloat program is again an exception. For testfloat only, the round-to-integer operations have names of these forms: +

    -     <float>_roundToInt_r_<round>
-     <float>_roundToInt_x
+<float>_roundToInt_r_<round>
+<float>_roundToInt_x
    -For the `_r_' versions, the inexact exception is never -raised, and the <round> component specifies the rounding -mode as one of `near_even', `near_maxMag', -`minMag', `min', or `max'. +
    +For the ‘_r_’ versions, the inexact exception +is never raised, and the <round> component specifies the +rounding mode as one of ‘near_even’, +‘near_maxMag’, ‘minMag’, +‘min’, or ‘max’. The usual indication of rounding mode is ignored. -In contrast, the `_x' versions accept the usual indication of -rounding mode and raise the inexact exception whenever the result is not -exact. -This irregular system follows the IEEE Standard's precise specification for the -round-to-integer operations. +In contrast, the ‘_x’ versions accept the usual +indication of rounding mode and raise the inexact exception whenever the +result is not exact. +This irregular system follows the IEEE Standard’s precise specification +for the round-to-integer operations.

    6.6. Comparison Operations

    The following floating-point comparison operations can be tested: +

    -     f32_eq      f32_le      f32_lt
-     f64_eq      f64_le      f64_lt
-     extF80_eq   extF80_le   extF80_lt
-     f128_eq     f128_le     f128_lt
+f32_eq      f32_le      f32_lt
+f64_eq      f64_le      f64_lt
+extF80_eq   extF80_le   extF80_lt
+f128_eq     f128_le     f128_lt
    -The abbreviation eq stands for ``equal'' (=), le -stands for ``less than or equal'' (≤), and lt stands for -``less than'' (<). +
    +The abbreviation eq stands for “equal” (=), +le stands for “less than or equal” (≤), and +lt stands for “less than” (<).

    @@ -635,12 +657,14 @@ The equality comparisons, on the other hand, are defined by default to raise the invalid exception only for signaling NaNs, not for quiet NaNs. For completeness, the following additional operations can be tested if supported: +

    -     f32_eq_signaling      f32_le_quiet      f32_lt_quiet
-     f64_eq_signaling      f64_le_quiet      f64_lt_quiet
-     extF80_eq_signaling   extF80_le_quiet   extF80_lt_quiet
-     f128_eq_signaling     f128_le_quiet     f128_lt_quiet
+f32_eq_signaling      f32_le_quiet      f32_lt_quiet
+f64_eq_signaling      f64_le_quiet      f64_lt_quiet
+extF80_eq_signaling   extF80_le_quiet   extF80_lt_quiet
+f128_eq_signaling     f128_le_quiet     f128_lt_quiet
    +
    The signaling equality comparisons are identical to the standard operations except that the invalid exception should be raised for any NaN input. @@ -658,8 +682,8 @@ Any rounding mode is ignored.

    7. Interpreting TestFloat Output

    -The ``errors'' reported by TestFloat programs may or may not really represent -errors in the system being tested. +The “errors” reported by TestFloat programs may or may not really +represent errors in the system being tested. For each test case tried, the results from the floating-point implementation being tested could differ from the expected results for several reasons:

      @@ -694,14 +718,16 @@ For each reported error (or apparent error), 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. +subsequent “continuation” lines are indented with a tab.

      Each error reported is of the form: +

      -     <inputs>  => <observed-output>  expected: <expected-output>
+<inputs>  => <observed-output>  expected: <expected-output>
      +
      The <inputs> are the inputs to the operation. Each output (observed and expected) is shown as a pair: the result value first, followed by the exception flags. @@ -709,10 +735,12 @@ first, followed by the exception flags.

      For example, two typical error lines could be +

      -     800.7FFF00  87F.000100  => 001.000000 ...ux  expected: 001.000000 ....x
-     081.000004  000.1FFFFF  => 001.000000 ...ux  expected: 001.000000 ....x
+800.7FFF00  87F.000100  => 001.000000 ...ux  expected: 001.000000 ....x
+081.000004  000.1FFFFF  => 001.000000 ...ux  expected: 001.000000 ....x
      +
      In the first line, the inputs are 800.7FFF00 and 87F.000100, and the observed result is 001.000000 with flags ...ux. @@ -732,8 +760,9 @@ Four are floating-point types: 32-bit single-precision, 64-bit double-precision, 80-bit double-extended-precision, and 128-bit quadruple-precision. The remaining five types are 32-bit and 64-bit -unsigned integers, 32-bit and 64-bit two's-complement -signed integers, and Boolean values (the results of comparison operations). +unsigned integers, 32-bit and 64-bit +two’s-complement signed 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 represented as 8 hexadecimal digits. @@ -749,47 +778,93 @@ 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 64-bit 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 less than +1
-
      +
      + + + + + + + + + + + + + + + + + + +
      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.FFFFFFFFFFFFFlargest representable number less than +1
      +
      The following categories are easily distinguished (assuming the xs are not all 0): -
      -     000.xxxxxxxxxxxxx    positive subnormal (denormalized) numbers
-     7FF.xxxxxxxxxxxxx    positive NaNs
-     800.xxxxxxxxxxxxx    negative subnormal numbers
-     FFF.xxxxxxxxxxxxx    negative NaNs
-
      +
      + + + + + + + + + + + +
      000.xxxxxxxxxxxxx    positive subnormal (denormalized) numbers
      7FF.xxxxxxxxxxxxxpositive NaNs
      800.xxxxxxxxxxxxxnegative subnormal numbers
      FFF.xxxxxxxxxxxxxnegative NaNs
      +

      128-bit 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
-                                              less than +1
-
      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      + 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.FFFFFFFFFFFFFFFFFFFFFFFFFFFFlargest representable number less than +1
      +

      @@ -801,19 +876,27 @@ and will be 1 otherwise. Hence, the same values listed above appear in 80-bit double-extended-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 less than +1
-
      +
      + + + + + + + + + + + + + + + + + + +
      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.FFFFFFFFFFFFFFFFlargest representable number less than +1
      +

      @@ -826,11 +909,13 @@ 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 32-bit single-precision subfields as follows: +

      -     x000 .... ....  .  .... .... .... .... .... ....    sign       (1 bit)
-     .... xxxx xxxx  .  .... .... .... .... .... ....    exponent   (8 bits)
-     .... .... ....  .  0xxx xxxx xxxx xxxx xxxx xxxx    fraction  (23 bits)
+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. @@ -841,27 +926,37 @@ The most significant hexadecimal digit of the fraction can be at most

      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 less than +1
-
      +
      + + + + + + + + + + + + + + + +
      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.7FFFFFlargest representable number less than +1
      +
      Again, certain categories are easily distinguished (assuming the xs are not all 0): -
      -     000.xxxxxx    positive subnormal (denormalized) numbers
-     0FF.xxxxxx    positive NaNs
-     800.xxxxxx    negative subnormal numbers
-     8FF.xxxxxx    negative NaNs
-
      +
      + + + + + + + + +
      000.xxxxxx    positive subnormal (denormalized) numbers
      0FF.xxxxxxpositive NaNs
      800.xxxxxxnegative subnormal numbers
      8FF.xxxxxxnegative NaNs
      +

      @@ -871,13 +966,21 @@ 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 exception
-     i    infinite exception ("divide by zero")
-     o    overflow exception
-     u    underflow exception
-     x    inexact exception
-
      +
      + + + + + + + + + + + + +
      v    invalid exception
      iinfinite exception (“divide by zero”)
      ooverflow exception
      uunderflow exception
      xinexact exception
      +
      For example, the notation ...ux indicates that the underflow and inexact exception flags were set and that the other three flags (invalid, infinite, and overflow) were not -- cgit v1.1