diff options
| author | John Hauser <jhauser@eecs.berkeley.edu> | 2014-12-17 19:09:39 -0800 |
|---|---|---|
| committer | John Hauser <jhauser@eecs.berkeley.edu> | 2014-12-17 19:09:39 -0800 |
| commit | cec54960bbbfa351cab7dab75eb1418585e4fe64 (patch) | |
| tree | 8c606f0c513bc0ef9582795bd159be8dcffaf565 | |
| parent | 86cdc156a7c1bb471c11b14d65b9d2b48b714935 (diff) | |
| download | berkeley-testfloat-3-cec54960bbbfa351cab7dab75eb1418585e4fe64.zip berkeley-testfloat-3-cec54960bbbfa351cab7dab75eb1418585e4fe64.tar.gz berkeley-testfloat-3-cec54960bbbfa351cab7dab75eb1418585e4fe64.tar.bz2 | |
Finalized documentation for TestFloat Release 3.
| -rw-r--r-- | COPYING.txt | 2 | ||||
| -rw-r--r-- | README.html | 8 | ||||
| -rw-r--r-- | README.txt | 11 | ||||
| -rw-r--r-- | doc/TestFloat-general.html | 507 | ||||
| -rw-r--r-- | doc/TestFloat-history.html | 21 | ||||
| -rw-r--r-- | doc/TestFloat-source.html | 190 | ||||
| -rw-r--r-- | doc/testfloat.html | 32 | ||||
| -rw-r--r-- | doc/testfloat_gen.html | 79 | ||||
| -rw-r--r-- | doc/testfloat_ver.html | 54 | ||||
| -rw-r--r-- | doc/testsoftfloat.html | 22 | ||||
| -rw-r--r-- | doc/timesoftfloat.html | 34 |
11 files changed, 527 insertions, 433 deletions
diff --git a/COPYING.txt b/COPYING.txt index c7d4700..335f14b 100644 --- a/COPYING.txt +++ b/COPYING.txt @@ -2,7 +2,7 @@ License for Berkeley TestFloat Release 3 John R. Hauser -2014 ________ +2014 Dec 17 The following applies to the whole of TestFloat Release 3 as well as to each source file individually. diff --git a/README.html b/README.html index 8831206..b89928f 100644 --- a/README.html +++ b/README.html @@ -11,14 +11,14 @@ <P> John R. Hauser<BR> -2014 ________<BR> +2014 Dec 17<BR> </P> <P> -Berkeley TestFloat is ___. -*** +Berkeley TestFloat is a small collection of programs for testing that an +implementation of binary floating-point conforms to the IEEE Standard for +Floating-Point Arithmetic. TestFloat is distributed in the form of C source code. -Building the TestFloat sources creates ___. </P> <P> @@ -2,13 +2,12 @@ Package Overview for Berkeley TestFloat Release 3 John R. Hauser -2014 ________ +2014 Dec 17 -Berkeley TestFloat is ___. -*** -TestFloat -is distributed in the form of C source code. Building the TestFloat sources -creates ___. +Berkeley TestFloat is a small collection of programs for testing that an +implementation of binary floating-point conforms to the IEEE Standard for +Floating-Point Arithmetic. TestFloat is distributed in the form of C source +code. The TestFloat package is documented in the following files in the "doc" subdirectory: 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 @@ <P> John R. Hauser<BR> -2014 ______<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -<BR> -*** REPLACE APOSTROPHES. -<BR> -*** REPLACE EM DASH. +2014 Dec 17<BR> </P> <H2>Contents</H2> -<P> -*** CHECK.<BR> -*** FIX FORMATTING. -</P> - -<PRE> - 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 -</PRE> +<BLOCKQUOTE> +<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> +<COL WIDTH=25> +<COL WIDTH=*> +<TR><TD COLSPAN=2>1. Introduction</TD></TR> +<TR><TD COLSPAN=2>2. Limitations</TD></TR> +<TR><TD COLSPAN=2>3. Acknowledgments and License</TD></TR> +<TR><TD COLSPAN=2>4. What TestFloat Does</TD></TR> +<TR><TD COLSPAN=2>5. Executing TestFloat</TD></TR> +<TR><TD COLSPAN=2>6. Operations Tested by TestFloat</TD></TR> +<TR><TD></TD><TD>6.1. Conversion Operations</TD></TR> +<TR><TD></TD><TD>6.2. Basic Arithmetic Operations</TD></TR> +<TR><TD></TD><TD>6.3. Fused Multiply-Add Operations</TD></TR> +<TR><TD></TD><TD>6.4. Remainder Operations</TD></TR> +<TR><TD></TD><TD>6.5. Round-to-Integer Operations</TD></TR> +<TR><TD></TD><TD>6.6. Comparison Operations</TD></TR> +<TR><TD COLSPAN=2>7. Interpreting TestFloat Output</TD></TR> +<TR> + <TD COLSPAN=2>8. Variations Allowed by the IEEE Floating-Point Standard</TD> +</TR> +<TR><TD></TD><TD>8.1. Underflow</TD></TR> +<TR><TD></TD><TD>8.2. NaNs</TD></TR> +<TR><TD></TD><TD>8.3. Conversions to Integer</TD></TR> +<TR><TD COLSPAN=2>9. Contact Information</TD></TR> +</TABLE> +</BLOCKQUOTE> <H2>1. Introduction</H2> @@ -89,8 +78,8 @@ Details about the standard are available elsewhere. <P> The current version of TestFloat is <NOBR>Release 3</NOBR>. -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. </P> @@ -119,15 +108,20 @@ bugs can be found through links posted on the TestFloat Web page The TestFloat package was written by me, <NOBR>John R.</NOBR> Hauser. <NOBR>Release 3</NOBR> 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 (<NOBR>Release 3</NOBR> 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: <BLOCKQUOTE> <TABLE> +<COL WIDTH=*> +<COL WIDTH=10> +<COL WIDTH=*> <TR> -<TD><NOBR>Par Lab:</NOBR></TD> +<TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD> +<TD></TD> <TD> 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. </TD> </TR> <TR> -<TD><NOBR>ASPIRE Lab:</NOBR></TD> +<TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD> +<TD></TD> <TD> 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. <P> 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 <CODE>testfloat_ver</CODE> and <CODE>testfloat</CODE>. 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 <A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. </P> <P> For testing SoftFloat itself, the TestFloat package includes a -<CODE>testsoftfloat</CODE> program that compares SoftFloat's floating-point -against <EM>another</EM> software floating-point implementation. +<CODE>testsoftfloat</CODE> program that compares SoftFloat’s +floating-point against <EM>another</EM> 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 <CODE>testfloat_ver</CODE> to be checked for correctness. Assuming a vertical bar (<CODE>|</CODE>) indicates a pipe between programs, the complete process could be written as a single command like so: +<BLOCKQUOTE> <PRE> - testfloat_gen ... <type> | <program-that-invokes-op> | testfloat_ver ... <function> +testfloat_gen ... <type> | <program-that-invokes-op> | testfloat_ver ... <function> </PRE> +</BLOCKQUOTE> 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 <CODE>testfloat_ver</CODE> can be folded into the invoking program to give the following command: +<BLOCKQUOTE> <PRE> - testfloat_gen ... <function> | <program-that-invokes-op-and-compares-results> +testfloat_gen ... <function> | <program-that-invokes-op-and-compares-results> </PRE> +</BLOCKQUOTE> 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; <LI> -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 <LI> comparisons between two values in the same floating-point format. </UL> @@ -451,8 +451,8 @@ is called <CODE>f32</CODE>, <NOBR>64-bit</NOBR> double-precision is <CODE>extF80</CODE>, and <NOBR>128-bit</NOBR> quadruple-precision is <CODE>f128</CODE>. TestFloat generally uses the same names for operations as Berkeley SoftFloat, -except that TestFloat's names never include the <CODE>M</CODE> that SoftFloat -uses to indicate that values are passed through pointers. +except that TestFloat’s names never include the <CODE>M</CODE> that +SoftFloat uses to indicate that values are passed through pointers. </P> <H3>6.1. Conversion Operations</H3> @@ -462,21 +462,23 @@ All conversions among the floating-point formats and all conversions between a floating-point format and <NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR> integers can be tested. The conversion operations are: +<BLOCKQUOTE> <PRE> - 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 </PRE> +</BLOCKQUOTE> Abbreviations <CODE>ui32</CODE> and <CODE>ui64</CODE> indicate <NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR> unsigned integer types, while <CODE>i32</CODE> and <CODE>i64</CODE> indicate their signed counterparts. @@ -495,22 +497,27 @@ operations requires amendment. For <CODE>testfloat</CODE> only, conversions to an integer type have names that explicitly specify the rounding mode and treatment of inexactness. Thus, instead of +<BLOCKQUOTE> <PRE> - <float>_to_<int> +<float>_to_<int> </PRE> +</BLOCKQUOTE> as listed above, operations converting to integer type have names of these forms: +<BLOCKQUOTE> <PRE> - <float>_to_<int>_r_<round> - <float>_to_<int>_rx_<round> +<float>_to_<int>_r_<round> +<float>_to_<int>_rx_<round> </PRE> -The <CODE><round></CODE> component is one of `<CODE>near_even</CODE>', -`<CODE>near_maxMag</CODE>', `<CODE>minMag</CODE>', `<CODE>min</CODE>', or -`<CODE>max</CODE>', choosing the rounding mode. +</BLOCKQUOTE> +The <CODE><round></CODE> component is one of +‘<CODE>near_even</CODE>’, ‘<CODE>near_maxMag</CODE>’, +‘<CODE>minMag</CODE>’, ‘<CODE>min</CODE>’, or +‘<CODE>max</CODE>’, choosing the rounding mode. Any other indication of rounding mode is ignored. -The operations with `<CODE>_r_</CODE>' in their names never raise the -<I>inexact</I> exception, while those with `<CODE>_rx_</CODE>' raise the -<I>inexact</I> exception whenever the result is not exact. +The operations with ‘<CODE>_r_</CODE>’ in their names never raise +the <I>inexact</I> exception, while those with ‘<CODE>_rx_</CODE>’ +raise the <I>inexact</I> exception whenever the result is not exact. </P> <P> @@ -518,7 +525,8 @@ TestFloat assumes that conversions from floating-point to an integer type should raise the <I>invalid</I> 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. <P> The following standard arithmetic operations can be tested: +<BLOCKQUOTE> <PRE> - 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 </PRE> +</BLOCKQUOTE> The double-extended-precision (<CODE>extF80</CODE>) operations can be rounded to reduced precision under rounding precision control. </P> @@ -550,11 +560,13 @@ For all floating-point formats except <NOBR>80-bit</NOBR> 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: +<BLOCKQUOTE> <PRE> - f32_mulAdd - f64_mulAdd - f128_mulAdd +f32_mulAdd +f64_mulAdd +f128_mulAdd </PRE> +</BLOCKQUOTE> </P> <P> @@ -566,29 +578,34 @@ exception even if the third operand is a NaN. <H3>6.4. Remainder Operations</H3> <P> -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: +<BLOCKQUOTE> <PRE> - f32_rem - f64_rem - extF80_rem - f128_rem +f32_rem +f64_rem +extF80_rem +f128_rem </PRE> +</BLOCKQUOTE> The remainder operations are always exact and so require no rounding. </P> <H3>6.5. Round-to-Integer Operations</H3> <P> -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: +<BLOCKQUOTE> <PRE> - f32_roundToInt - f64_roundToInt - extF80_roundToInt - f128_roundToInt +f32_roundToInt +f64_roundToInt +extF80_roundToInt +f128_roundToInt </PRE> +</BLOCKQUOTE> </P> <P> @@ -596,35 +613,40 @@ Just as for conversions to integer types (<NOBR>section 6.1</NOBR> above), the all-in-one <CODE>testfloat</CODE> program is again an exception. For <CODE>testfloat</CODE> only, the round-to-integer operations have names of these forms: +<BLOCKQUOTE> <PRE> - <float>_roundToInt_r_<round> - <float>_roundToInt_x +<float>_roundToInt_r_<round> +<float>_roundToInt_x </PRE> -For the `<CODE>_r_</CODE>' versions, the <I>inexact</I> exception is never -raised, and the <CODE><round></CODE> component specifies the rounding -mode as one of `<CODE>near_even</CODE>', `<CODE>near_maxMag</CODE>', -`<CODE>minMag</CODE>', `<CODE>min</CODE>', or `<CODE>max</CODE>'. +</BLOCKQUOTE> +For the ‘<CODE>_r_</CODE>’ versions, the <I>inexact</I> exception +is never raised, and the <CODE><round></CODE> component specifies the +rounding mode as one of ‘<CODE>near_even</CODE>’, +‘<CODE>near_maxMag</CODE>’, ‘<CODE>minMag</CODE>’, +‘<CODE>min</CODE>’, or ‘<CODE>max</CODE>’. The usual indication of rounding mode is ignored. -In contrast, the `<CODE>_x</CODE>' versions accept the usual indication of -rounding mode and raise the <I>inexact</I> 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 ‘<CODE>_x</CODE>’ versions accept the usual +indication of rounding mode and raise the <I>inexact</I> exception whenever the +result is not exact. +This irregular system follows the IEEE Standard’s precise specification +for the round-to-integer operations. </P> <H3>6.6. Comparison Operations</H3> <P> The following floating-point comparison operations can be tested: +<BLOCKQUOTE> <PRE> - 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 </PRE> -The abbreviation <CODE>eq</CODE> stands for ``equal'' (=), <CODE>le</CODE> -stands for ``less than or equal'' (≤), and <CODE>lt</CODE> stands for -``less than'' (<). +</BLOCKQUOTE> +The abbreviation <CODE>eq</CODE> stands for “equal” (=), +<CODE>le</CODE> stands for “less than or equal” (≤), and +<CODE>lt</CODE> stands for “less than” (<). </P> <P> @@ -635,12 +657,14 @@ The equality comparisons, on the other hand, are defined by default to raise the <I>invalid</I> exception only for signaling NaNs, not for quiet NaNs. For completeness, the following additional operations can be tested if supported: +<BLOCKQUOTE> <PRE> - 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 </PRE> +</BLOCKQUOTE> The <CODE>signaling</CODE> equality comparisons are identical to the standard operations except that the <I>invalid</I> exception should be raised for any NaN input. @@ -658,8 +682,8 @@ Any rounding mode is ignored. <H2>7. Interpreting TestFloat Output</H2> <P> -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: <UL> @@ -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. </P> <P> Each error reported is of the form: +<BLOCKQUOTE> <PRE> - <inputs> => <observed-output> expected: <expected-output> +<inputs> => <observed-output> expected: <expected-output> </PRE> +</BLOCKQUOTE> The <CODE><inputs></CODE> 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. <P> For example, two typical error lines could be +<BLOCKQUOTE> <PRE> - 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 </PRE> +</BLOCKQUOTE> In the first line, the inputs are <CODE>800.7FFF00</CODE> and <CODE>87F.000100</CODE>, and the observed result is <CODE>001.000000</CODE> with flags <CODE>...ux</CODE>. @@ -732,8 +760,9 @@ Four are floating-point types: <NOBR>32-bit</NOBR> single-precision, <NOBR>64-bit</NOBR> double-precision, <NOBR>80-bit</NOBR> double-extended-precision, and <NOBR>128-bit</NOBR> quadruple-precision. The remaining five types are <NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR> -unsigned integers, <NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR> two's-complement -signed integers, and Boolean values (the results of comparison operations). +unsigned integers, <NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR> +two’s-complement signed integers, and Boolean values (the results of +comparison operations). Boolean values are represented as a single character, either a <CODE>0</CODE> or a <CODE>1</CODE>. <NOBR>32-bit</NOBR> 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 <NOBR>64-bit</NOBR> double-precision values include: -<PRE> - 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 -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>000.0000000000000 </CODE></TD> + <TD>+0</TD> +</TR> +<TR><TD><CODE>3FF.0000000000000</CODE></TD><TD> 1</TD></TR> +<TR><TD><CODE>400.0000000000000</CODE></TD><TD> 2</TD></TR> +<TR><TD><CODE>7FF.0000000000000</CODE></TD><TD>+infinity</TD></TR> +<TR><TD> </TD></TR> +<TR><TD><CODE>800.0000000000000</CODE></TD><TD>−0</TD></TR> +<TR><TD><CODE>BFF.0000000000000</CODE></TD><TD>−1</TD></TR> +<TR><TD><CODE>C00.0000000000000</CODE></TD><TD>−2</TD></TR> +<TR><TD><CODE>FFF.0000000000000</CODE></TD><TD>−infinity</TD></TR> +<TR><TD> </TD></TR> +<TR> + <TD><CODE>3FE.FFFFFFFFFFFFF</CODE></TD> + <TD>largest representable number less than +1</TD> +</TR> +</TABLE> +</BLOCKQUOTE> The following categories are easily distinguished (assuming the <CODE>x</CODE>s are not all 0): -<PRE> - 000.xxxxxxxxxxxxx positive subnormal (denormalized) numbers - 7FF.xxxxxxxxxxxxx positive NaNs - 800.xxxxxxxxxxxxx negative subnormal numbers - FFF.xxxxxxxxxxxxx negative NaNs -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>000.xxxxxxxxxxxxx </CODE></TD> + <TD>positive subnormal (denormalized) numbers</TD> +</TR> +<TR><TD><CODE>7FF.xxxxxxxxxxxxx</CODE></TD><TD>positive NaNs</TD></TR> +<TR> + <TD><CODE>800.xxxxxxxxxxxxx</CODE></TD> + <TD>negative subnormal numbers</TD> +</TR> +<TR><TD><CODE>FFF.xxxxxxxxxxxxx</CODE></TD><TD>negative NaNs</TD></TR> +</TABLE> +</BLOCKQUOTE> </P> <P> <NOBR>128-bit</NOBR> 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: -<PRE> - 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 -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD> + <CODE>0000.0000000000000000000000000000 </CODE> + </TD> + <TD>+0</TD> +</TR> +<TR> + <TD><CODE>3FFF.0000000000000000000000000000</CODE></TD> + <TD> 1</TD> +</TR> +<TR> + <TD><CODE>4000.0000000000000000000000000000</CODE></TD> + <TD> 2</TD> +</TR> +<TR> + <TD><CODE>7FFF.0000000000000000000000000000</CODE></TD> + <TD>+infinity</TD> +</TR> +<TR><TD> </TD></TR> +<TR> + <TD><CODE>8000.0000000000000000000000000000</CODE></TD> + <TD>−0</TD> +</TR> +<TR> + <TD><CODE>BFFF.0000000000000000000000000000</CODE></TD> + <TD>−1</TD> +</TR> +<TR> + <TD><CODE>C000.0000000000000000000000000000</CODE></TD> + <TD>−2</TD> +</TR> +<TR> + <TD><CODE>FFFF.0000000000000000000000000000</CODE></TD> + <TD>−infinity</TD> +</TR> +<TR><TD> </TD></TR> +<TR> + <TD><CODE>3FFE.FFFFFFFFFFFFFFFFFFFFFFFFFFFF</CODE></TD> + <TD>largest representable number less than +1</TD> +</TR> +</TABLE> +</BLOCKQUOTE> </P> <P> @@ -801,19 +876,27 @@ and will be 1 otherwise. Hence, the same values listed above appear in <NOBR>80-bit</NOBR> double-extended-precision as follows (note the leading <CODE>8</CODE> digit in the significands): -<PRE> - 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 -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>0000.0000000000000000 </CODE></TD> + <TD>+0</TD> +</TR> +<TR><TD><CODE>3FFF.8000000000000000</CODE></TD><TD> 1</TD></TR> +<TR><TD><CODE>4000.8000000000000000</CODE></TD><TD> 2</TD></TR> +<TR><TD><CODE>7FFF.8000000000000000</CODE></TD><TD>+infinity</TD></TR> +<TR><TD> </TD></TR> +<TR><TD><CODE>8000.0000000000000000</CODE></TD><TD>−0</TD></TR> +<TR><TD><CODE>BFFF.8000000000000000</CODE></TD><TD>−1</TD></TR> +<TR><TD><CODE>C000.8000000000000000</CODE></TD><TD>−2</TD></TR> +<TR><TD><CODE>FFFF.8000000000000000</CODE></TD><TD>−infinity</TD></TR> +<TR><TD> </TD></TR> +<TR> + <TD><CODE>3FFE.FFFFFFFFFFFFFFFF</CODE></TD> + <TD>largest representable number less than +1</TD> +</TR> +</TABLE> +</BLOCKQUOTE> </P> <P> @@ -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 <NOBR>32-bit</NOBR> single-precision subfields as follows: +<BLOCKQUOTE> <PRE> - 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) </PRE> +</BLOCKQUOTE> As shown in this schematic, the first hexadecimal digit contains only the sign, and will be either <CODE>0</CODE> <NOBR>or <CODE>8</CODE></NOBR>. The next two digits give the biased exponent as an <NOBR>8-bit</NOBR> integer. @@ -841,27 +926,37 @@ The most significant hexadecimal digit of the fraction can be at most <P> Notable single-precision values include: -<PRE> - 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 -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR><TD><CODE>000.000000 </CODE></TD><TD>+0</TD></TR> +<TR><TD><CODE>07F.000000</CODE></TD><TD> 1</TD></TR> +<TR><TD><CODE>080.000000</CODE></TD><TD> 2</TD></TR> +<TR><TD><CODE>0FF.000000</CODE></TD><TD>+infinity</TD></TR> +<TR><TD> </TD></TR> +<TR><TD><CODE>800.000000</CODE></TD><TD>−0</TD></TR> +<TR><TD><CODE>87F.000000</CODE></TD><TD>−1</TD></TR> +<TR><TD><CODE>880.000000</CODE></TD><TD>−2</TD></TR> +<TR><TD><CODE>8FF.000000</CODE></TD><TD>−infinity</TD></TR> +<TR><TD> </TD></TR> +<TR> + <TD><CODE>07E.7FFFFF</CODE></TD> + <TD>largest representable number less than +1</TD> +</TR> +</TABLE> +</BLOCKQUOTE> Again, certain categories are easily distinguished (assuming the <CODE>x</CODE>s are not all 0): -<PRE> - 000.xxxxxx positive subnormal (denormalized) numbers - 0FF.xxxxxx positive NaNs - 800.xxxxxx negative subnormal numbers - 8FF.xxxxxx negative NaNs -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>000.xxxxxx </CODE></TD> + <TD>positive subnormal (denormalized) numbers</TD> +</TR> +<TR><TD><CODE>0FF.xxxxxx</CODE></TD><TD>positive NaNs</TD></TR> +<TR><TD><CODE>800.xxxxxx</CODE></TD><TD>negative subnormal numbers</TD></TR> +<TR><TD><CODE>8FF.xxxxxx</CODE></TD><TD>negative NaNs</TD></TR> +</TABLE> +</BLOCKQUOTE> </P> <P> @@ -871,13 +966,21 @@ Each flag is written as either a letter or a period (<CODE>.</CODE>) 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: -<PRE> - v invalid exception - i infinite exception ("divide by zero") - o overflow exception - u underflow exception - x inexact exception -</PRE> +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>v </CODE></TD> + <TD>invalid exception</TD> +</TR> +<TR> + <TD><CODE>i</CODE></TD> + <TD>infinite exception (“divide by zero”)</TD> +</TR> +<TR><TD><CODE>o</CODE></TD><TD>overflow exception</TD></TR> +<TR><TD><CODE>u</CODE></TD><TD>underflow exception</TD></TR> +<TR><TD><CODE>x</CODE></TD><TD>inexact exception</TD></TR> +</TABLE> +</BLOCKQUOTE> For example, the notation <CODE>...ux</CODE> indicates that the <I>underflow</I> and <I>inexact</I> exception flags were set and that the other three flags (<I>invalid</I>, <I>infinite</I>, and <I>overflow</I>) were not diff --git a/doc/TestFloat-history.html b/doc/TestFloat-history.html index daed701..3b9b833 100644 --- a/doc/TestFloat-history.html +++ b/doc/TestFloat-history.html @@ -11,16 +11,9 @@ <P> John R. Hauser<BR> -2014 _____<BR> +2014 Dec 17<BR> </P> -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -</P> <P> Releases of Berkeley TestFloat parallel those of Berkeley SoftFloat, on which @@ -35,7 +28,8 @@ corresponding release of SoftFloat. <UL> <LI> -Complete rewrite, funded by the University of California, Berkeley. +Complete rewrite, funded by the University of California, Berkeley, and +consequently having a different use license than earlier releases. Visible changes included different names for testable functions and options. <LI> @@ -68,8 +62,8 @@ package). <UL> <LI> -Improved wording for the legal restrictions on using TestFloat releases -<NOBR>through 2c</NOBR>. +Improved the wording for the legal restrictions on using TestFloat releases +<NOBR>through 2c</NOBR> (not applicable to <NOBR>Release 3</NOBR> or later). </UL> @@ -121,7 +115,7 @@ random bits for the entire machine word width.) <LI> Created <CODE>testsoftfloat</CODE>, with its own simpler complete software -floating-point (``slowfloat'') for comparison purposes. +floating-point (“slowfloat”) for comparison purposes. <LI> Made some changes to the source file structure, including renaming @@ -147,7 +141,8 @@ to control whether tininess should be detected before or after rounding. <UL> <LI> -Original release. +Original release, based on work done for the International Computer Science +Institute (ICSI) in Berkeley, California. </UL> diff --git a/doc/TestFloat-source.html b/doc/TestFloat-source.html index 9c42e59..6851036 100644 --- a/doc/TestFloat-source.html +++ b/doc/TestFloat-source.html @@ -11,38 +11,33 @@ <P> John R. Hauser<BR> -2014 _____<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. +2014 Dec 17<BR> </P> <H2>Contents</H2> -<P> -*** CHECK.<BR> -*** FIX FORMATTING. -</P> - <BLOCKQUOTE> -1. Introduction<BR> -2. Limitations<BR> -3. Acknowledgments and License<BR> -4. TestFloat Package Directory Structure<BR> -5. Dependence on Berkeley SoftFloat<BR> -6. Issues for Porting TestFloat to a New Target<BR> - 6.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE><BR> - 6.2. Standard Header <CODE><fenv.h></CODE><BR> - 6.3. Macros for Build Options<BR> - 6.4. Specializing the <CODE>testfloat</CODE> Program<BR> - 6.5. Improving the Random Number Functions<BR> -7. Contact Information<BR> +<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> +<COL WIDTH=25> +<COL WIDTH=*> +<TR><TD COLSPAN=2>1. Introduction</TD></TR> +<TR><TD COLSPAN=2>2. Limitations</TD></TR> +<TR><TD COLSPAN=2>3. Acknowledgments and License</TD></TR> +<TR><TD COLSPAN=2>4. TestFloat Package Directory Structure</TD></TR> +<TR><TD COLSPAN=2>5. Dependence on Berkeley SoftFloat</TD></TR> +<TR><TD COLSPAN=2>6. Issues for Porting TestFloat to a New Target</TD></TR> +<TR> + <TD></TD> + <TD>6.1. Standard Headers <CODE><stdbool.h></CODE> and + <CODE><stdint.h></CODE></TD> +</TR> +<TR><TD></TD><TD>6.2. Standard Header <CODE><fenv.h></CODE></TD></TR> +<TR><TD></TD><TD>6.3. Macros for Build Options</TD></TR> +<TR><TD></TD><TD>6.4. Specializing the <CODE>testfloat</CODE> Program</TD></TR> +<TR><TD></TD><TD>6.5. Improving the Random Number Functions</TD></TR> +<TR><TD COLSPAN=2>7. Contact Information</TD></TR> +</TABLE> </BLOCKQUOTE> @@ -112,7 +107,7 @@ strictly required. integer types. If these headers are not supplied with the C compiler, minimal substitutes must be provided. -TestFloat's dependence on these headers is detailed later in +TestFloat’s dependence on these headers is detailed later in <NOBR>section 6.1</NOBR>, <I>Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE></I>. </P> @@ -124,15 +119,20 @@ and <CODE><stdint.h></CODE></I>. The TestFloat package was written by me, <NOBR>John R.</NOBR> Hauser. <NOBR>Release 3</NOBR> 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 (<NOBR>Release 3</NOBR> 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: <BLOCKQUOTE> <TABLE> +<COL WIDTH=*> +<COL WIDTH=10> +<COL WIDTH=*> <TR> -<TD><NOBR>Par Lab:</NOBR></TD> +<TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD> +<TD></TD> <TD> Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery (Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, @@ -140,7 +140,8 @@ NVIDIA, Oracle, and Samsung. </TD> </TR> <TR> -<TD><NOBR>ASPIRE Lab:</NOBR></TD> +<TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD> +<TD></TD> <TD> DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, @@ -199,26 +200,30 @@ Because TestFloat is targeted to multiple platforms, its source code is slightly scattered between target-specific and target-independent directories and files. The supplied directory structure is as follows: +<BLOCKQUOTE> <PRE> - doc - source - subj-C - build - template - Linux-386-GCC - Linux-x86_64-GCC - Win32-MinGW - Win64-MinGW-w64 +doc +source + subj-C +build + template + Linux-386-GCC + Linux-386-SSE2-GCC + Linux-x86_64-GCC + Win32-MinGW + Win32-SSE2-MinGW + Win64-MinGW-w64 </PRE> +</BLOCKQUOTE> The majority of the TestFloat sources are provided in the <CODE>source</CODE> directory. The <NOBR><CODE>subj-C</CODE></NOBR> subdirectory contains the sources that configure the all-in-one <CODE>testfloat</CODE> program to test the C -compiler's implementation of the standard C types <CODE>float</CODE>, +compiler’s implementation of the standard C types <CODE>float</CODE>, <CODE>double</CODE>, and possibly <CODE>long</CODE> <CODE>double</CODE>. -The `<CODE>subj</CODE>' in <NOBR><CODE>subj-C</CODE></NOBR> is an abbreviation -of <I>subject</I>, referring to the floating-point that is the subject of the -test. +The ‘<CODE>subj</CODE>’ in <NOBR><CODE>subj-C</CODE></NOBR> is an +abbreviation of <I>subject</I>, referring to the floating-point that is the +subject of the test. If <CODE>testfloat</CODE> is retargeted to test other floating-point implementations, the corresponding source files would be expected to be in other subdirectories alongside <NOBR><CODE>subj-C</CODE></NOBR>, with names of @@ -231,8 +236,8 @@ Program</I>. <P> The <CODE>build</CODE> directory is intended to contain a subdirectory for each target platform for which builds of the TestFloat programs may be created. -For each build target, the target's subdirectory is where all derived object -files and the completed TestFloat executables are created. +For each build target, the target’s subdirectory is where all derived +object files and the completed TestFloat executables are created. The <CODE>template</CODE> subdirectory is not an actual build target but contains sample files for creating new target directories. </P> @@ -243,18 +248,21 @@ are intended to follow a naming system of <NOBR><CODE><execution-environment>-<compiler></CODE></NOBR>. For the example targets, <NOBR><CODE><execution-environment></CODE></NOBR> is -<NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-x86_64</CODE></NOBR>, -<CODE>Win32</CODE>, or <CODE>Win64</CODE>, and +<NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-386-SSE2</CODE></NOBR>, +<NOBR><CODE>Linux-x86_64</CODE></NOBR>, <CODE>Win32</CODE>, +<NOBR><CODE>Win32-SSE2</CODE></NOBR>, or <CODE>Win64</CODE>, and <NOBR><CODE><compiler></CODE></NOBR> is <CODE>GCC</CODE>, <CODE>MinGW</CODE>, or <NOBR><CODE>MinGW-w64</CODE></NOBR>. </P> <P> As supplied, each target directory contains two files: +<BLOCKQUOTE> <PRE> - Makefile - platform.h +Makefile +platform.h </PRE> +</BLOCKQUOTE> The provided <CODE>Makefile</CODE> is written for GNU <CODE>make</CODE>. A build of TestFloat for the specific target is begun by executing the <CODE>make</CODE> command with the target directory as the current directory. @@ -269,9 +277,10 @@ Every C source file of TestFloat contains a <CODE>#include</CODE> for <CODE>platform.h</CODE>. In many cases, the contents of <CODE>platform.h</CODE> can be as simple as one or two lines of code. -If the target's compiler or library has bugs or other shortcomings, workarounds -for these issues may be possible with target-specific declarations in -<CODE>platform.h</CODE>, without the need to modify the main TestFloat sources. +If the target’s compiler or library has bugs or other shortcomings, +workarounds for these issues may be possible with target-specific declarations +in <CODE>platform.h</CODE>, without the need to modify the main TestFloat +sources. </P> <P> @@ -310,8 +319,8 @@ clients. This list must include <CODE>softfloat.h</CODE> and may also include other header files referenced by <CODE>softfloat.h</CODE>, such as <CODE>softfloat_types.h</CODE>. This macro is used only to establish build dependencies between the SoftFloat -header files and TestFloat's source files, in case the SoftFloat header files -are changed. +header files and TestFloat’s source files, in case the SoftFloat header +files are changed. <DT><CODE>SOFTFLOAT_LIB</CODE> <DD> The full path of the compiled SoftFloat library (usually @@ -336,29 +345,33 @@ For older or nonstandard compilers, substitutes for <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE> may need to be created. TestFloat depends on these names from <CODE><stdbool.h></CODE>: +<BLOCKQUOTE> <PRE> - bool - true - false +bool +true +false </PRE> +</BLOCKQUOTE> and on these names from <CODE><stdint.h></CODE>: +<BLOCKQUOTE> <PRE> - uint16_t - uint32_t - uint64_t - int32_t - int64_t - UINT64_C - INT64_C - uint_least8_t - uint_fast8_t - uint_fast16_t - uint_fast32_t - uint_fast64_t - int_fast16_t - int_fast32_t - int_fast64_t +uint16_t +uint32_t +uint64_t +int32_t +int64_t +UINT64_C +INT64_C +uint_least8_t +uint_fast8_t +uint_fast16_t +uint_fast32_t +uint_fast64_t +int_fast16_t +int_fast32_t +int_fast64_t </PRE> +</BLOCKQUOTE> </P> @@ -408,18 +421,18 @@ Must be defined if the TestFloat programs are to support the <NOBR>128-bit</NOBR> quadruple-precision floating-point format. </DL> </BLOCKQUOTE> -Following the usual custom <NOBR>for C</NOBR>, the content of a macro's +Following the usual custom <NOBR>for C</NOBR>, the content of a macro’s definition is irrelevant; -what matters is a macro's effect on <CODE>#ifdef</CODE> directives. +what matters is a macro’s effect on <CODE>#ifdef</CODE> directives. </P> <P> It is recommended that any definition of macro <CODE>LITTLEENDIAN</CODE> be -made in a build target's <CODE>platform.h</CODE> header file, because +made in a build target’s <CODE>platform.h</CODE> header file, because endianness is expected to be determined inflexibly by the target machine. On the other hand, the <CODE>EXTFLOAT80</CODE> and <CODE>FLOAT128</CODE> macros are not dictated by the target and hence might be better located in the -target's Makefile (or its equivalent). +target’s Makefile (or its equivalent). </P> @@ -427,7 +440,7 @@ target's Makefile (or its equivalent). <P> The supplied sources for the all-in-one <CODE>testfloat</CODE> program cause -<CODE>testfloat</CODE> to test the C compiler's <CODE>float</CODE> and +<CODE>testfloat</CODE> to test the C compiler’s <CODE>float</CODE> and <CODE>double</CODE> types for C operations <CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, etc. The supplied version is also capable of testing C type <CODE>long</CODE> @@ -445,7 +458,7 @@ Indicates that type <CODE>long</CODE> <CODE>double</CODE> is <NOBR>128-bit</NOBR> quadruple-precision floating-point. </DL> </BLOCKQUOTE> -By default, <CODE>testfloat</CODE> assumes that only the IEEE Standard's +By default, <CODE>testfloat</CODE> assumes that only the IEEE Standard’s original four rounding modes (<CODE>near_even</CODE>, <CODE>minMag</CODE>, <CODE>min</CODE>, and <CODE>max</CODE>) are supported by the floating-point being tested. @@ -464,15 +477,18 @@ Indicates that the subject floating-point supports rounding mode <P> To test a new and/or different implementation of floating-point, <CODE>testfloat</CODE> must normally be retargeted to invoke this other -floating-point instead of C's floating-point. +floating-point instead of C’s floating-point. Two source files define the functions that <CODE>testfloat</CODE> uses to invoke floating-point operations for testing: +<BLOCKQUOTE> <PRE> - subjfloat_config.h - subjfloat.c +subjfloat_config.h +subjfloat.c </PRE> -For the default target of testing C's floating-point, these files are contained -in directory <NOBR><CODE>source/subj-C</CODE></NOBR> as discussed earlier. +</BLOCKQUOTE> +For the default target of testing C’s floating-point, these files are +contained in directory <NOBR><CODE>source/subj-C</CODE></NOBR> as discussed +earlier. For a different subject floating-point, it is recommended that appropriate versions of <CODE>subjfloat_config.h</CODE> and <CODE>subjfloat.c</CODE> be stored in a sibling <NOBR><CODE>subj-<target></CODE></NOBR> directory, @@ -531,8 +547,8 @@ UNIX-derived systems), TestFloat can be improved by overriding the given <P> Rather than modifying the supplied file <CODE>random.c</CODE>, it is -recommended instead that a new, alternate file be created and the target's -Makefile be modified to refer to that alternate file in place of +recommended instead that a new, alternate file be created and the +target’s Makefile be modified to refer to that alternate file in place of <CODE>random.c</CODE>. </P> diff --git a/doc/testfloat.html b/doc/testfloat.html index 7779214..4460651 100644 --- a/doc/testfloat.html +++ b/doc/testfloat.html @@ -11,19 +11,7 @@ <P> John R. Hauser<BR> -2014 ______<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -<BR> -*** REPLACE APOSTROPHES. -<BR> -*** REPLACE EM DASH. +2014 Dec 17<BR> </P> @@ -49,7 +37,7 @@ While the processes of generating inputs and examining results are generic, a particular build of <CODE>testfloat</CODE> is limited to testing only the one implementation of floating-point it has been compiled to invoke. For example, while one instance of <CODE>testfloat</CODE> might be compiled to -execute a computer's hardware instruction for floating-point addition, a +execute a computer’s hardware instruction for floating-point addition, a different version might be compiled to call a subroutine called <CODE>myAddFloat</CODE> that is linked into the <CODE>testfloat</CODE> program. To test a new implementation of floating-point (a new set of machine @@ -65,16 +53,16 @@ Standard, and tests the C operations of <CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, type conversions, etc. This tests the floating-point arithmetic seen by C programs. Depending on the compiler and the options selected during compilation, this may -or may not be the same as the computer's floating-point hardware, if any. +or may not be the same as the computer’s floating-point hardware, if any. </P> <P> The <CODE>testfloat</CODE> program will ordinarily test an operation for all rounding modes defined by the IEEE Floating-Point Standard, 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. +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 double-extended-precision operations affected by rounding precision control, <CODE>testfloat</CODE> also tests all three rounding precision modes, one after the other. @@ -93,9 +81,11 @@ output, refer to <P> The <CODE>testfloat</CODE> program is executed as a command with this syntax: +<BLOCKQUOTE> <PRE> - testfloat [<option>...] <function> +testfloat [<option>...] <function> </PRE> +</BLOCKQUOTE> Square brackets (<CODE>[ ]</CODE>) denote optional arguments, <CODE><option></CODE> is a supported option, and <CODE><function></CODE> is the name of either a testable operation or a @@ -249,9 +239,11 @@ The set <CODE>-all1</CODE> comprises all one-operand operations, while <CODE>-all2</CODE> is all two-operand operations. A function set is used in place of an operation name in the <CODE>testfloat</CODE> command line, such as +<BLOCKQUOTE> <PRE> - testfloat [<option>...] -all1 +testfloat [<option>...] -all1 </PRE> +</BLOCKQUOTE> </P> diff --git a/doc/testfloat_gen.html b/doc/testfloat_gen.html index 43e6d20..3cbdf9a 100644 --- a/doc/testfloat_gen.html +++ b/doc/testfloat_gen.html @@ -11,19 +11,7 @@ <P> John R. Hauser<BR> -2014 ______<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -<BR> -*** REPLACE APOSTROPHES. -<BR> -*** REPLACE EM DASH. +2014 Dec 17<BR> </P> @@ -55,8 +43,8 @@ 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 consuming 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>. +The format of <CODE>testfloat_gen</CODE>’s output is raw hexadecimal +text, described in the section below titled <I>Output Format</I>. </P> @@ -65,10 +53,12 @@ described in the section below titled <I>Output Format</I>. <P> The <CODE>testfloat_gen</CODE> program is executed as a command in one of these forms: +<BLOCKQUOTE> <PRE> - testfloat_gen [<option>...] <type> - testfloat_gen [<option>...] <function> +testfloat_gen [<option>...] <type> +testfloat_gen [<option>...] <function> </PRE> +</BLOCKQUOTE> Square brackets (<CODE>[ ]</CODE>) denote optional arguments, and <CODE><option></CODE> is a supported option, documented below. A <CODE>testfloat_gen</CODE> command expects either a <CODE><type></CODE> @@ -81,7 +71,7 @@ usage is written. <P> A <CODE><type></CODE> can be one of the following: <BLOCKQUOTE> -<TABLE> +<TABLE CELLSPACING=0 CELLPADDING=0> <TR> <TD><CODE>ui32</CODE></TD> <TD>unsigned <NOBR>32-bit</NOBR> integers</TD> @@ -139,7 +129,8 @@ If a <CODE><function></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><type></CODE> argument) but also the expected results as determined by -<CODE>testfloat_gen</CODE>'s internal floating-point emulation (SoftFloat). +<CODE>testfloat_gen</CODE>’s internal floating-point emulation +(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: @@ -283,17 +274,21 @@ 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 +testfloat_gen f64 2 </PRE> +</BLOCKQUOTE> might look like this: +<BLOCKQUOTE> <PRE> - 3F90EB5825D6851E C3E0080080000000 - 41E3C00000000000 C182024F8AE474A8 - 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 - 3FFFED6A25C534BE 3CA1000000020000 - ... +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 @@ -310,28 +305,38 @@ 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 +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 - ... +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> -<TR><TD>bit 0</TD><TD> </TD><TD><I>inexact</I> exception</TD></TR> -<TR><TD>bit 1</TD><TD> </TD><TD><I>underflow</I> exception</TD></TR> -<TR><TD>bit 2</TD><TD> </TD><TD><I>overflow</I> exception</TD></TR> -<TR><TD>bit 3</TD><TD> </TD><TD><I>infinite</I> exception ("divide by zero")</TD></TR> -<TR><TD>bit 4</TD><TD> </TD><TD><I>invalid</I> exception</TD></TR> +<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> diff --git a/doc/testfloat_ver.html b/doc/testfloat_ver.html index 4d1540e..2e7e3fe 100644 --- a/doc/testfloat_ver.html +++ b/doc/testfloat_ver.html @@ -11,19 +11,7 @@ <P> John R. Hauser<BR> -2014 ______<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -<BR> -*** REPLACE APOSTROPHES. -<BR> -*** REPLACE EM DASH. +2014 Dec 17<BR> </P> @@ -52,7 +40,7 @@ The test cases to be verified are read by <CODE>testfloat_ver</CODE> from standard input. This input will typically be piped from another program that, for each test case, invokes the floating-point operation and writes out the results. -The format of <CODE>testfloat_ver</CODE>'s input is raw hexadecimal text, +The format of <CODE>testfloat_ver</CODE>’s input is raw hexadecimal text, described in the section below titled <I>Input Format</I>. </P> @@ -71,9 +59,11 @@ its output, refer to <P> The <CODE>testfloat_ver</CODE> program is executed as a command with this syntax: +<BLOCKQUOTE> <PRE> - testfloat_ver [<option>...] <function> +testfloat_ver [<option>...] <function> </PRE> +</BLOCKQUOTE> Square brackets (<CODE>[ ]</CODE>) denote optional arguments, <CODE><option></CODE> is a supported option, and <CODE><function></CODE> is the name of a testable operation. @@ -205,17 +195,21 @@ the exception flags that were raised. These values are all expected to be provided as raw hexadecimal numbers separated on the line by spaces. For example, for the command +<BLOCKQUOTE> <PRE> - testfloat_ver f64_add +testfloat_ver f64_add </PRE> +</BLOCKQUOTE> valid input could include these lines: +<BLOCKQUOTE> <PRE> - 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 - 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 - 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 - 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 - ... +3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 +41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 +7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 +3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 +... </PRE> +</BLOCKQUOTE> On each line above, the first two hexadecimal numbers represent the <NOBR>64-bit</NOBR> floating-point operands, the third hexadecimal number is the <NOBR>64-bit</NOBR> floating-point result of the operation (the sum), and @@ -235,12 +229,18 @@ encoded significand. <P> Exception flags are encoded with one bit per flag as follows: <BLOCKQUOTE> -<TABLE> -<TR><TD>bit 0</TD><TD> </TD><TD><I>inexact</I> exception</TD></TR> -<TR><TD>bit 1</TD><TD> </TD><TD><I>underflow</I> exception</TD></TR> -<TR><TD>bit 2</TD><TD> </TD><TD><I>overflow</I> exception</TD></TR> -<TR><TD>bit 3</TD><TD> </TD><TD><I>infinite</I> exception ("divide by zero")</TD></TR> -<TR><TD>bit 4</TD><TD> </TD><TD><I>invalid</I> exception</TD></TR> +<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> diff --git a/doc/testsoftfloat.html b/doc/testsoftfloat.html index 49215de..306f221 100644 --- a/doc/testsoftfloat.html +++ b/doc/testsoftfloat.html @@ -11,19 +11,7 @@ <P> John R. Hauser<BR> -2014 ______<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -<BR> -*** REPLACE APOSTROPHES. -<BR> -*** REPLACE EM DASH. +2014 Dec 17<BR> </P> @@ -70,9 +58,11 @@ and/or a single rounding precision with appropriate command-line options. <P> The <CODE>testsoftfloat</CODE> program is executed as a command with this syntax: +<BLOCKQUOTE> <PRE> - testsoftfloat [<option>...] <function> +testsoftfloat [<option>...] <function> </PRE> +</BLOCKQUOTE> Square brackets (<CODE>[ ]</CODE>) denote optional arguments, <CODE><option></CODE> is a supported option, and <CODE><function></CODE> is the name of either a testable function or a @@ -208,9 +198,11 @@ The set <CODE>-all1</CODE> comprises all one-operand operations, while <CODE>-all2</CODE> is all two-operand operations. A function set is used in place of a function name in the <CODE>testsoftfloat</CODE> command line, such as +<BLOCKQUOTE> <PRE> - testsoftfloat [<option>...] -all1 +testsoftfloat [<option>...] -all1 </PRE> +</BLOCKQUOTE> </P> <P> diff --git a/doc/timesoftfloat.html b/doc/timesoftfloat.html index b214611..bb4e947 100644 --- a/doc/timesoftfloat.html +++ b/doc/timesoftfloat.html @@ -11,19 +11,7 @@ <P> John R. Hauser<BR> -2014 ______<BR> -</P> - -<P> -*** CONTENT DONE. -</P> - -<P> -*** REPLACE QUOTATION MARKS. -<BR> -*** REPLACE APOSTROPHES. -<BR> -*** REPLACE EM DASH. +2014 Dec 17<BR> </P> @@ -38,14 +26,14 @@ floating-point conforms to the IEEE Standard for Binary Floating-Point Arithmetic. Although <CODE>timesoftfloat</CODE> does not test floating-point correctness like other TestFloat programs, nevertheless <CODE>timesoftfloat</CODE> is a -partner to TestFloat's <CODE>testsoftfloat</CODE> program. +partner to TestFloat’s <CODE>testsoftfloat</CODE> program. For more about TestFloat generally and <CODE>testsoftfloat</CODE> specifically, see file <A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. </P> <P> -Ordinarily, <CODE>timesoftfloat</CODE> will measure a function's speed +Ordinarily, <CODE>timesoftfloat</CODE> will measure a function’s speed separately for each rounding mode defined by the IEEE Floating-Point Standard, one after the other. If an operation is not supposed to require rounding, it will by default be @@ -63,13 +51,13 @@ options. <P> For each function and mode evaluated, <CODE>timesoftfloat</CODE> reports the -measured speed of the function in Mops/s, or ``millions of operations per -second''. +measured speed of the function in Mop/s, or “millions of operations per +second”. The speeds reported by <CODE>timesoftfloat</CODE> may be affected somewhat by other software executing at the same time as <CODE>timesoftfloat</CODE>. Be aware also that the exact execution time of any SoftFloat function depends -partly on the values of arguments and the state of the processor's caches at -the time the function is called. +partly on the values of arguments and the state of the processor’s caches +at the time the function is called. Your actual experience with SoftFloat may differ from the speeds reported by <CODE>timesoftfloat</CODE> for all these reasons. </P> @@ -89,9 +77,11 @@ SoftFloat implementation. <P> The <CODE>timesoftfloat</CODE> program is executed as a command with this syntax: +<BLOCKQUOTE> <PRE> - timesoftfloat [<option>...] <function> +timesoftfloat [<option>...] <function> </PRE> +</BLOCKQUOTE> Square brackets (<CODE>[ ]</CODE>) denote optional arguments, <CODE><option></CODE> is a supported option, and <CODE><function></CODE> is the name of either a testable function or a @@ -181,9 +171,11 @@ The set <CODE>-all1</CODE> comprises all one-operand operations, obviously all operations. A function set is used in place of a function name in the <CODE>timesoftfloat</CODE> command line, such as +<BLOCKQUOTE> <PRE> - timesoftfloat [<option>...] -all1 +timesoftfloat [<option>...] -all1 </PRE> +</BLOCKQUOTE> </P> <P> |