diff options
| author | John Hauser <jhauser@eecs.berkeley.edu> | 2014-11-28 21:07:26 -0800 |
|---|---|---|
| committer | John Hauser <jhauser@eecs.berkeley.edu> | 2014-11-28 21:07:26 -0800 |
| commit | d6feb3fa41c6b7ba1b5444ad147d8623138512c2 (patch) | |
| tree | 09dd66c114bcc759fd86de0279c91a21d356235b /doc | |
| download | berkeley-testfloat-3-d6feb3fa41c6b7ba1b5444ad147d8623138512c2.zip berkeley-testfloat-3-d6feb3fa41c6b7ba1b5444ad147d8623138512c2.tar.gz berkeley-testfloat-3-d6feb3fa41c6b7ba1b5444ad147d8623138512c2.tar.bz2 | |
First draft of RC for Release 3, to start review process.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/TestFloat-general.html | 989 | ||||
| -rw-r--r-- | doc/TestFloat-history.html | 156 | ||||
| -rw-r--r-- | doc/TestFloat-source.html | 546 | ||||
| -rw-r--r-- | doc/testfloat.html | 259 | ||||
| -rw-r--r-- | doc/testfloat_gen.html | 341 | ||||
| -rw-r--r-- | doc/testfloat_ver.html | 250 | ||||
| -rw-r--r-- | doc/testsoftfloat.html | 229 | ||||
| -rw-r--r-- | doc/timesoftfloat.html | 202 |
8 files changed, 2972 insertions, 0 deletions
diff --git a/doc/TestFloat-general.html b/doc/TestFloat-general.html new file mode 100644 index 0000000..1618d4a --- /dev/null +++ b/doc/TestFloat-general.html @@ -0,0 +1,989 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat General Documentation</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: General Documentation</H1> + +<P> +John R. Hauser<BR> +2014 ______<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +<BR> +*** REPLACE APOSTROPHES. +<BR> +*** REPLACE EM DASH. +</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> + + +<H2>1. Introduction</H2> + +<P> +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. +All operations required by the original 1985 version of the IEEE Floating-Point +Standard can be tested, except for conversions to and from decimal. +The following binary formats can be tested: <NOBR>32-bit</NOBR> +single-precision, <NOBR>64-bit</NOBR> double-precision, <NOBR>80-bit</NOBR> +double-extended-precision, and/or <NOBR>128-bit</NOBR> quadruple-precision. +TestFloat cannot test decimal floating-point. +</P> + +<P> +Included in the TestFloat package are the <CODE>testsoftfloat</CODE> and +<CODE>timesoftfloat</CODE> programs for testing the Berkeley SoftFloat software +implementation of floating-point and for measuring its speed. +Information about SoftFloat can be found at the SoftFloat Web page, +<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. +The <CODE>testsoftfloat</CODE> and <CODE>timesoftfloat</CODE> programs are +expected to be of interest only to people compiling the SoftFloat sources. +</P> + +<P> +This document explains how to use the TestFloat programs. +It does not attempt to define or explain much of the IEEE Floating-Point +Standard. +Details about the standard are available elsewhere. +</P> + +<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. +</P> + + +<H2>2. Limitations</H2> + +<P> +TestFloat output is not always easily interpreted. +Detailed knowledge of the IEEE Floating-Point Standard and its vagaries is +needed to use TestFloat responsibly. +</P> + +<P> +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 chance. +Software that purposefully seeks out various kinds of subtle floating-point +bugs can be found through links posted on the TestFloat Web page +(<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></A>). +</P> + + +<H2>3. Acknowledgments and License</H2> + +<P> +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. +The work was officially overseen by Prof. Krste Asanovic, with funding provided +by these sources: +<BLOCKQUOTE> +<TABLE> +<TR> +<TD><NOBR>Par Lab:</NOBR></TD> +<TD> +Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery +(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +</TD> +</TR> +<TR> +<TD><NOBR>ASPIRE Lab:</NOBR></TD> +<TD> +DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from +ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, +Oracle, and Samsung. +</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +The following applies to the whole of TestFloat <NOBR>Release 3</NOBR> as well +as to each source file individually. +</P> + +<P> +Copyright 2011, 2012, 2013, 2014 The Regents of the University of California +(Regents). +All Rights Reserved. +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +</P> + +<P> +Redistributions of source code must retain the above copyright notice, this +list of conditions, and the following two paragraphs of disclaimer. +Redistributions in binary form must reproduce the above copyright notice, this +list of conditions, and the following two paragraphs of disclaimer in the +documentation and/or other materials provided with the distribution. +Neither the name of the Regents nor the names of its contributors may be used +to endorse or promote products derived from this software without specific +prior written permission. +</P> + +<P> +IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, +INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF +THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</P> + +<P> +REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS +PROVIDED "<NOBR>AS IS</NOBR>". +REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, +ENHANCEMENTS, OR MODIFICATIONS. +</P> + + +<H2>4. What TestFloat Does</H2> + +<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. +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. +The cases generated should be adequate for testing carry chain propagations, +plus the rounding of addition, subtraction, multiplication, 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 addition and multiplication, millions of +test cases may be checked. +</P> + +<P> +TestFloat is not remarkably good at testing difficult rounding cases for +division and square root. +It also makes no attempt to find bugs specific to SRT division and the like +(such as the infamous Pentium division bug). +Software that tests for such failures can be found through links on the +TestFloat Web page, +<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></A>. +</P> + +<P> +NOTE!<BR> +It is the responsibility of the user to verify that the discrepancies TestFloat +finds actually represent faults in the implementation 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. +</P> + +<P> +For each operation, TestFloat can test all five rounding modes defined by the +IEEE Floating-Point 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 <I>inexact</I> flag. +TestFloat does not attempt to verify that the floating-point exception flags +are actually implemented as sticky flags. +</P> + +<P> +For the <NOBR>80-bit</NOBR> double-extended-precision format, TestFloat can +test the addition, subtraction, multiplication, division, and square root +operations at all three of the standard rounding precisions. +The rounding precision can be set to <NOBR>32 bits</NOBR>, equivalent to +single-precision, to <NOBR>64 bits</NOBR>, equivalent to double-precision, or +to the full <NOBR>80 bits</NOBR> of the double-extended-precision. +Rounding precision control can be applied only to the double-extended-precision +format and only for the five basic arithmetic operations: addition, +subtraction, multiplication, division, and square root. +Other operations can be tested only at full precision. +</P> + +<P> +As a rule, TestFloat is not particular about the bit patterns of NaNs that +appear as operation 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 <NOBR>section 8</NOBR> below, <I>Variations Allowed by the IEEE +Floating-Point Standard</I>, plus the <CODE>-checkNaNs</CODE> option documented +for programs <CODE>testfloat_ver</CODE> and <CODE>testfloat</CODE>. +</P> + +<P> +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. +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. +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. +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 +TestFloat executable or when compiling SoftFloat for some other reason. +</P> + + +<H2>5. Executing TestFloat</H2> + +<P> +The TestFloat package consists of five programs, all intended to be executed +from a command-line interpreter: +<BLOCKQUOTE> +<TABLE> +<TR> +<TD> +<A HREF="testfloat_gen.html"><CODE>testfloat_gen</CODE></A><CODE> </CODE> +</TD> +<TD> +Generates test cases for a specific floating-point operation. +</TD> +</TR> +<TR> +<TD><A HREF="testfloat_ver.html"><CODE>testfloat_ver</CODE></A></TD> +<TD> +Verifies whether the results from executing a floating-point operation are as +expected. +</TD> +</TR> +<TR> +<TD><A HREF="testfloat.html"><CODE>testfloat</CODE></A></TD> +<TD> +An all-in-one program that generates test cases, executes floating-point +operations, and verifies whether the results match expectations. +</TD> +</TR> +<TR> +<TD> +<A HREF="testsoftfloat.html"><CODE>testsoftfloat</CODE></A><CODE> </CODE> +</TD> +<TD> +Like <CODE>testfloat</CODE>, but for testing SoftFloat. +</TD> +</TR> +<TR> +<TD> +<A HREF="timesoftfloat.html"><CODE>timesoftfloat</CODE></A><CODE> </CODE> +</TD> +<TD> +A program for measuring the speed of SoftFloat (included in the TestFloat +package for convenience). +</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +Each program has its own page of documentation that can be opened through the +links in the table above. +</P> + +<P> +To test a floating-point implementation other than SoftFloat, one of three +different methods can be used. +The first method pipes output from <CODE>testfloat_gen</CODE> to a program +that: +<NOBR>(a) reads</NOBR> the incoming test cases, <NOBR>(b) invokes</NOBR> the +floating-point operation being tested, and <NOBR>(c) writes</NOBR> the +operation results to output. +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: +<PRE> + testfloat_gen ... <type> | <program-that-invokes-op> | testfloat_ver ... <function> +</PRE> +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 +<CODE>-prefix</CODE> option of <CODE>testfloat_gen</CODE> can communicate +parameters through the pipe. +</P> + +<P> +A second method for running TestFloat is similar but has +<CODE>testfloat_gen</CODE> supply not only the test inputs but also the +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: +<PRE> + testfloat_gen ... <function> | <program-that-invokes-op-and-compares-results> +</PRE> +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 +<CODE>testfloat_ver</CODE> check and report suspected errors (first method) or +to include this step in the invoking program (second method). +</P> + +<P> +The third way to use TestFloat is the all-in-one <CODE>testfloat</CODE> +program. +This program can perform all the steps of creating test cases, invoking the +floating-point operation, checking the results, and reporting suspected errors. +However, for this to be possible, <CODE>testfloat</CODE> must be compiled to +contain the method for invoking the floating-point operations to test. +Each build of <CODE>testfloat</CODE> is therefore capable of testing +<EM>only</EM> the floating-point implementation it was built to invoke. +To test a new implementation of floating-point, a new <CODE>testfloat</CODE> +must be created, linked to that specific implementation. +By comparison, the <CODE>testfloat_gen</CODE> and <CODE>testfloat_ver</CODE> +programs are entirely generic; +one instance is usable for testing any floating-point implementation, because +implementation-specific details are segregated in the custom program that +follows <CODE>testfloat_gen</CODE>. +</P> + +<P> +Program <CODE>testsoftfloat</CODE> is another all-in-one program specifically +for testing SoftFloat. +</P> + +<P> +Programs <CODE>testfloat_ver</CODE>, <CODE>testfloat</CODE>, and +<CODE>testsoftfloat</CODE> all report status and error information in a common +way. +As it executes, each of these programs 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. +Any discrepancies that are found are written to the standard output stream, +which is easily redirected to a file if desired. +Unless redirected, reported errors will appear intermixed with the ongoing +status information in the output. +</P> + + +<H2>6. Operations Tested by TestFloat</H2> + +<P> +TestFloat can test all operations required by the original 1985 IEEE +Floating-Point Standard except for conversions to and from decimal. +These operations are: +<UL> +<LI> +conversions among the supported floating-point formats, and also between +integers (<NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR>, signed and unsigned) and +any of the floating-point formats; +<LI> +for each floating-point format, the usual addition, subtraction, +multiplication, division, and square root operations; +<LI> +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 +<LI> +comparisons between two values in the same floating-point format. +</UL> +In addition, TestFloat can also test +<UL> +<LI> +for each floating-point format except <NOBR>80-bit</NOBR> +double-extended-precision, the fused multiply-add operation defined by the 2008 +IEEE Standard. +</UL> +</P> + +<P> +More information about all these operations is given below. +In the operation names used by TestFloat, <NOBR>32-bit</NOBR> single-precision +is called <CODE>f32</CODE>, <NOBR>64-bit</NOBR> double-precision is +<CODE>f64</CODE>, <NOBR>80-bit</NOBR> double-extended-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. +</P> + +<H3>6.1. Conversion Operations</H3> + +<P> +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: +<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 +</PRE> +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. +These conversions all round according to the current rounding mode as relevant. +Conversions from a smaller to a larger floating-point format are always exact +and so require no rounding. +Likewise, conversions from <NOBR>32-bit</NOBR> integers to <NOBR>64-bit</NOBR> +double-precision or to any larger floating-point format are also exact, as are +conversions from <NOBR>64-bit</NOBR> integers to <NOBR>80-bit</NOBR> +double-extended-precision and <NOBR>128-bit</NOBR> quadruple-precision. +</P> + +<P> +For the all-in-one <CODE>testfloat</CODE> program, this list of conversion +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 +<PRE> + <float>_to_<int> +</PRE> +as listed above, operations converting to integer type have names of these +forms: +<PRE> + <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. +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. +</P> + +<P> +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. +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. +Lastly, when a NaN is converted to a signed integer type, TestFloat allows +either the largest postive or largest-magnitude negative integer to be +returned. +Conversions to integer types are expected never to raise the <I>overflow</I> +exception. +</P> + +<H3>6.2. Basic Arithmetic Operations</H3> + +<P> +The following standard arithmetic operations can be tested: +<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 +</PRE> +The double-extended-precision (<CODE>extF80</CODE>) operations can be rounded +to reduced precision under rounding precision control. +</P> + +<H3>6.3. Fused Multiply-Add Operations</H3> + +<P> +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: +<PRE> + f32_mulAdd + f64_mulAdd + f128_mulAdd +</PRE> +</P> + +<P> +If one of the multiplication operands is infinite and the other is zero, +TestFloat expects the fused multiply-add operation to raise the <I>invalid</I> +exception even if the third operand is a NaN. +</P> + +<H3>6.4. Remainder Operations</H3> + +<P> +For each format, TestFloat can test the IEEE Standard's remainder operation. +These operations are: +<PRE> + f32_rem + f64_rem + extF80_rem + f128_rem +</PRE> +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 +operation. +For most TestFloat programs, these operations are: +<PRE> + f32_roundToInt + f64_roundToInt + extF80_roundToInt + f128_roundToInt +</PRE> +</P> + +<P> +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: +<PRE> + <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>'. +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. +</P> + +<H3>6.6. Comparison Operations</H3> + +<P> +The following floating-point comparison operations can be tested: +<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 +</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'' (<). +</P> + +<P> +The IEEE Standard specifies that, by default, the less-than-or-equal and +less-than comparisons raise the <I>invalid</I> exception if either input is any +kind of NaN. +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: +<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 +</PRE> +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. +Similarly, the <CODE>quiet</CODE> comparison operations should be identical to +their counterparts except that the <I>invalid</I> exception is not raised for +quiet NaNs. +</P> + +<P> +Obviously, no comparison operations ever require rounding. +Any rounding mode is ignored. +</P> + + +<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. +For each test case tried, the results from the floating-point implementation +being tested could differ from the expected results for several reasons: +<UL> +<LI> +The IEEE Floating-Point Standard allows for some variation in how conforming +floating-point behaves. +Two implementations can sometimes give different results without either being +incorrect. +<LI> +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. +<LI> +The TestFloat program may not work properly, reporting differences that do not +exist. +<LI> +Lastly, the floating-point being tested could actually be faulty. +</UL> +It is the responsibility of the user to determine the causes for the +discrepancies that are reported. +Making this determination can require detailed knowledge about the IEEE +Standard. +Assuming TestFloat is working properly, any differences found will be due to +either the first or last of the reasons above. +Variations in the IEEE Standard that could lead to false error reports are +discussed in <NOBR>section 8</NOBR>, <I>Variations Allowed by the IEEE +Floating-Point Standard</I>. +</P> + +<P> +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. +</P> + +<P> +Each error reported is of the form: +<PRE> + <inputs> => <observed-output> expected: <expected-output> +</PRE> +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. +</P> + +<P> +For example, two typical error lines could be +<PRE> + 800.7FFF00 87F.000100 => 001.000000 ...ux expected: 001.000000 ....x + 081.000004 000.1FFFFF => 001.000000 ...ux expected: 001.000000 ....x +</PRE> +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>. +The trusted emulation result is the same but with different flags, +<CODE>....x</CODE>. +Items such as <CODE>800.7FFF00</CODE> composed of hexadecimal digits and a +single period represent floating-point values (here <NOBR>32-bit</NOBR> +single-precision). +The two instances above were reported as errors because the exception flag +results differ. +</P> + +<P> +Aside from the exception flags, there are nine data types that may be +represented. +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). +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. +Thus, for a signed <NOBR>32-bit</NOBR> integer, <CODE>FFFFFFFF</CODE> is -1, +and <CODE>7FFFFFFF</CODE> is the largest positive value. +<NOBR>64-bit</NOBR> integers are the same except with 16 hexadecimal digits. +</P> + +<P> +Floating-point values are written in a correspondingly primitive form. +Values of the <NOBR>64-bit</NOBR> double-precision format 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 <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> +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> +</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> +</P> + +<P> +<NOBR>80-bit</NOBR> double-extended-precision values are a little unusual in +that the leading bit of precision is not hidden as with other formats. +When correctly encoded, the leading significand bit of an <NOBR>80-bit</NOBR> +double-extended-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 <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> +</P> + +<P> +The representation of <NOBR>32-bit</NOBR> single-precision values is unusual +for a different reason. +Because the subfields of standard <NOBR>32-bit</NOBR> single-precision do not +fall on neat <NOBR>4-bit</NOBR> 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 <NOBR>32-bit</NOBR> +single-precision subfields as follows: +<PRE> + x000 .... .... . .... .... .... .... .... .... sign (1 bit) + .... xxxx xxxx . .... .... .... .... .... .... exponent (8 bits) + .... .... .... . 0xxx xxxx xxxx xxxx xxxx xxxx fraction (23 bits) +</PRE> +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. +This is followed by a period and 6 hexadecimal digits of fraction. +The most significant hexadecimal digit of the fraction can be at most +<NOBR>a <CODE>7</CODE></NOBR>. +</P> + +<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> +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> +</P> + +<P> +Lastly, exception flag values are represented by five characters, one character +per flag. +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> +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 +set. +The exception flags are always written following the value returned as the +result of the operation. +</P> + + +<H2>8. Variations Allowed by the IEEE Floating-Point Standard</H2> + +<P> +The IEEE Floating-Point 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. +</P> + +<H3>8.1. Underflow</H3> + +<P> +The standard specifies that the <I>underflow</I> exception flag is to be raised +when two conditions are met simultaneously: +<NOBR>(1) <I>tininess</I></NOBR> and <NOBR>(2) <I>loss of accuracy</I></NOBR>. +</P> + +<P> +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. +All the TestFloat programs support options <CODE>-tininessbefore</CODE> and +<CODE>-tininessafter</CODE> to control whether TestFloat expects tininess on +underflow to be detected before or after rounding. +One or the other is selected as the default when TestFloat is compiled, but +these command options allow the default to be overridden. +</P> + +<P> +Loss of accuracy occurs when the subnormal format is not sufficient to +represent an underflowed result accurately. +The original 1985 version of the IEEE Standard allowed loss of accuracy to be +detected either as an <I>inexact result</I> or as a +<I>denormalization loss</I>; +however, few if any systems ever chose the latter. +The latest standard requires that loss of accuracy be detected as an inexact +result, and TestFloat can test only for this case. +</P> + +<H3>8.2. NaNs</H3> + +<P> +The 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 +<EM>which</EM> NaN to return in each situation. +</P> + +<P> +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 <CODE>-checkNaNs</CODE> option of +programs <CODE>testfloat_ver</CODE> and <CODE>testfloat</CODE>. +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. +</P> + +<H3>8.3. Conversions to Integer</H3> + +<P> +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 IEEE Standard does not specify what value should be returned as the integer +result in these cases. +Moreover, according to the standard, the <I>invalid</I> exception can be raised +or an unspecified alternative mechanism may be used to signal such cases. +</P> + +<P> +TestFloat assumes that conversions to integer will raise the <I>invalid</I> +exception if the source value cannot be rounded to a representable integer. +In such cases, TestFloat expects the result value to be the largest-magnitude +positive or negative integer as detailed earlier in <NOBR>section 6.1</NOBR>, +<I>Conversion Operations</I>. +The current version of TestFloat provides no means to alter these expectations. +</P> + + +<H2>9. Contact Information</H2> + +<P> +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 +<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></A>. +</P> + + +</BODY> + diff --git a/doc/TestFloat-history.html b/doc/TestFloat-history.html new file mode 100644 index 0000000..daed701 --- /dev/null +++ b/doc/TestFloat-history.html @@ -0,0 +1,156 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat History</TITLE> +</HEAD> + +<BODY> + +<H1>History of Berkeley TestFloat, to Release 3</H1> + +<P> +John R. Hauser<BR> +2014 _____<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +</P> + +<P> +Releases of Berkeley TestFloat parallel those of Berkeley SoftFloat, on which +TestFloat is based. +Each TestFloat release necessarily incorporates all bug fixes from the +corresponding release of SoftFloat. +</P> + + +<H3>Release 3 (2014 December)</H3> + +<UL> + +<LI> +Complete rewrite, funded by the University of California, Berkeley. +Visible changes included different names for testable functions and options. + +<LI> +Reinstated separate programs for generating test cases +(<CODE>testfloat_ver</CODE>) and verifying test results +(<CODE>testfloat_gen</CODE>), as alternatives to the all-in-one +<CODE>testfloat</CODE> program (which remained supported). + +<LI> +Added support for testing conversions between floating-point and unsigned +integers, both <NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR>. + +<LI> +Added support for testing a fused multiply-add operation, for all testable +floating-point formats except <NOBR>80-bit</NOBR> double-extended-precision. + +<LI> +Added support for testing a fifth rounding mode, <CODE>near_maxMag</CODE> +(round to nearest, with ties to maximum magnitude, away from zero). + +<LI> +Added <CODE>timesoftfloat</CODE> (previously found in the Berkeley SoftFloat +package). + +</UL> + + +<H3>Release 2c (2014 December)</H3> + +<UL> + +<LI> +Improved wording for the legal restrictions on using TestFloat releases +<NOBR>through 2c</NOBR>. + +</UL> + + +<P> +There was never a <NOBR>Release 2b</NOBR>. +</P> + + +<H3>Release 2a (1998 December)</H3> + +<UL> + +<LI> +Added support for testing conversions between floating-point and +<NOBR>64-bit</NOBR> signed integers. + +<LI> +Improved the Makefiles. + +</UL> + + +<H3>Release 2 (1997 June)</H3> + +<UL> + +<LI> +Integrated the generation of test cases and the checking of system results into +a single program. +(Before they were separate programs, normally joined by explicit command-line +pipes.) + +<LI> +Improved the sequence of test cases. + +<LI> +Added support for testing <NOBR>80-bit</NOBR> double-extended-precision and +<NOBR>128-bit</NOBR> quadruple precision. + +<LI> +Made program output more readable, and added new command arguments. + +<LI> +Reduced dependence on the quality of the standard <CODE>rand</CODE> function +for generating test cases. +(Previously naively expected <CODE>rand</CODE> to be able to generate good +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. + +<LI> +Made some changes to the source file structure, including renaming +<CODE>environment.h</CODE> to <CODE>milieu.h</CODE> (to avoid confusion with +environment variables). + +</UL> + + +<H3>Release 1a (1996 July)</H3> + +<UL> + +<LI> +Added the <CODE>-tininessbefore</CODE> and <CODE>-tininessafter</CODE> options +to control whether tininess should be detected before or after rounding. + +</UL> + + +<H3>Release 1 (1996 July)</H3> + +<UL> + +<LI> +Original release. + +</UL> + + +</BODY> + diff --git a/doc/TestFloat-source.html b/doc/TestFloat-source.html new file mode 100644 index 0000000..a875479 --- /dev/null +++ b/doc/TestFloat-source.html @@ -0,0 +1,546 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat Source Documentation</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: Source Documentation</H1> + +<P> +John R. Hauser<BR> +2014 _____<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +</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> +</BLOCKQUOTE> + + +<H2>1. Introduction</H2> + +<P> +This document gives information needed for compiling and/or porting Berkeley +TestFloat, a small collection of programs for testing that an implementation of +binary floating-point conforms to the IEEE Standard for Floating-Point +Arithmetic. +For basic documentation about TestFloat refer to +<A HREF="TestFloat-general.html"><CODE>TestFloat-general.html</CODE></A>. +</P> + +<P> +The source code for TestFloat is intended to be relatively machine-independent. +Most programs in the TestFloat package should be compilable with any +ISO-standard C compiler that also supports <NOBR>64-bit</NOBR> integers. +If the all-in-one <CODE>testfloat</CODE> program will be used to test a new +floating-point implementation, additional effort will likely be required to +retarget that program to invoke the new floating-point operations. +TestFloat has been successfully compiled with the GNU C Compiler +(<CODE>gcc</CODE>) for several platforms. +</P> + +<P> +<NOBR>Release 3</NOBR> of TestFloat is a complete rewrite relative to +<NOBR>Release 2</NOBR> or earlier. +</P> + +<P> +TestFloat depends on Berkeley SoftFloat, which is a software implementation of +binary floating-point that conforms to the IEEE Standard for Floating-Point +Arithmetic. +SoftFloat is not included with the TestFloat sources. +It can be obtained from the Web page +<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. +</P> + + +<H2>2. Limitations</H2> + +<P> +TestFloat assumes the computer has an addressable byte size of either 8 or +<NOBR>16 bits</NOBR>. +(Nearly all computers in use today have <NOBR>8-bit</NOBR> bytes.) +</P> + +<P> +TestFloat is written entirely <NOBR>in C</NOBR>. +The C compiler used must conform at a minimum to the 1989 ANSI standard for the +C language (same as the 1990 ISO standard) and must in addition support basic +arithmetic on <NOBR>64-bit</NOBR> integers. +Earlier releases of TestFloat were capable of testing <NOBR>32-bit</NOBR> +single-precision and <NOBR>64-bit</NOBR> double-precision floating-point +without requiring compiler support for <NOBR>64-bit</NOBR> integers, but this +option is not supported with <NOBR>Release 3</NOBR>. +Since 1999, ISO standards for C have mandated compiler support for +<NOBR>64-bit</NOBR> integers. +A compiler conforming to the 1999 C Standard or later is recommended but not +strictly required. +</P> + +<P> +<NOBR>C Standard</NOBR> header files <CODE><stdbool.h></CODE> and +<CODE><stdint.h></CODE> are required for defining standard Boolean and +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 +<NOBR>section 6.1</NOBR>, <I>Standard Headers <CODE><stdbool.h></CODE> +and <CODE><stdint.h></CODE></I>. +</P> + + +<H2>3. Acknowledgments and License</H2> + +<P> +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. +The work was officially overseen by Prof. Krste Asanovic, with funding provided +by these sources: +<BLOCKQUOTE> +<TABLE> +<TR> +<TD><NOBR>Par Lab:</NOBR></TD> +<TD> +Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery +(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +</TD> +</TR> +<TR> +<TD><NOBR>ASPIRE Lab:</NOBR></TD> +<TD> +DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from +ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, +Oracle, and Samsung. +</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +The following applies to the whole of TestFloat <NOBR>Release 3</NOBR> as well +as to each source file individually. +</P> + +<P> +Copyright 2011, 2012, 2013, 2014 The Regents of the University of California +(Regents). +All Rights Reserved. +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +</P> + +<P> +Redistributions of source code must retain the above copyright notice, this +list of conditions, and the following two paragraphs of disclaimer. +Redistributions in binary form must reproduce the above copyright notice, this +list of conditions, and the following two paragraphs of disclaimer in the +documentation and/or other materials provided with the distribution. +Neither the name of the Regents nor the names of its contributors may be used +to endorse or promote products derived from this software without specific +prior written permission. +</P> + +<P> +IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, +INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF +THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</P> + +<P> +REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS +PROVIDED "<NOBR>AS IS</NOBR>". +REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, +ENHANCEMENTS, OR MODIFICATIONS. +</P> + + +<H2>4. TestFloat Package Directory Structure</H2> + +<P> +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: +<PRE> + doc + source + subj-C + build + template + Win32-MinGW + Linux-386-GCC +</PRE> +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>, +<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. +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 +the form <NOBR><CODE>subj-<target></CODE></NOBR>. +More about retargeting <CODE>testfloat</CODE> is found in +<NOBR>section 6.4</NOBR>, <I>Specializing the <CODE>testfloat</CODE> +Program</I>. +</P> + +<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. +The <CODE>template</CODE> subdirectory is not an actual build target but +contains sample files for creating new target directories. +</P> + +<P> +Ignoring the <CODE>template</CODE> directory, the supplied target directories +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 <CODE>Win32</CODE> +and <CODE>Linux-386</CODE>, and <NOBR><CODE><compiler></CODE></NOBR> is +<CODE>MinGW</CODE> and <CODE>GCC</CODE>, respectively. +</P> + +<P> +As supplied, each target directory contains two files: +<PRE> + Makefile + platform.h +</PRE> +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. +A completely different build tool can be used if an appropriate +<CODE>Makefile</CODE> equivalent is created. +</P> + +<P> +The <CODE>platform.h</CODE> header file exists to provide a location for +additional C declarations specific to the build target. +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. +</P> + +<P> +It may not be necessary to build all of the TestFloat programs. +For testing a floating-point implementation, typically +<CODE>testfloat_gen</CODE> and <CODE>testfloat</CODE> will not both be used, +and <CODE>testfloat_ver</CODE> may not be needed either. +The Makefile (or equivalent) can be modified not to create unneeded programs. +This may be especially relevant for the all-in-one test program +<CODE>testfloat</CODE>, which might not build without special attention. +</P> + + +<H2>5. Dependence on Berkeley SoftFloat</H2> + +<P> +In addition to the distributed sources, TestFloat depends on the existence of a +compatible Berkeley SoftFloat library and the corresponding header file +<CODE>softfloat.h</CODE>. +As mentioned earlier, SoftFloat is a separate package available at Web page +<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. +The SoftFloat library must be compiled before the TestFloat programs can be +built. +In the example Makefiles, the locations of the SoftFloat header files and +pre-compiled library are specified by these macros: +<BLOCKQUOTE> +<DL> +<DT><CODE>SOFTFLOAT_INCLUDE_DIR</CODE> +<DD> +The path of the directory containing <CODE>softfloat.h</CODE>, as well as other +nonstandard header files referenced by <CODE>softfloat.h</CODE>, if any. +<DT><CODE>SOFTFLOAT_H</CODE> +<DD> +A list of the full paths of all SoftFloat header files needed by SoftFloat +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. +<DT><CODE>SOFTFLOAT_LIB</CODE> +<DD> +The full path of the compiled SoftFloat library (usually +<CODE>softfloat.a</CODE>). +</DL> +</BLOCKQUOTE> +</P> + + +<H2>6. Issues for Porting TestFloat to a New Target</H2> + +<H3>6.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE></H3> + +<P> +The TestFloat sources make use of standard headers +<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, which have +been part of the ISO C Standard Library since 1999. +With any recent compiler, these standard headers are likely to be supported, +even if the compiler does not claim complete conformance to the latest ISO C +Standard. +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>: +<PRE> + bool + true + false +</PRE> +and on these names from <CODE><stdint.h></CODE>: +<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 +</PRE> +</P> + + +<H3>6.2. Standard Header <CODE><fenv.h></CODE></H3> + +<P> +Because the supplied all-in-one <CODE>testfloat</CODE> program tests the +floating-point operations of the C language, it uses the facilities provided by +standard C header <CODE><fenv.h></CODE> to access the floating-point +environment of C, in particular to set the rounding mode and to access the +floating-point exception flags. +Like <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, +<CODE><fenv.h></CODE> has been part of the ISO C Standard Library since +1999, but older or nonstandard C compilers may not support it. +</P> + +<P> +Some form of standard header <CODE><fenv.h></CODE> is needed only if the +<CODE>testfloat</CODE> program is wanted <EM>and</EM> the program will not be +retargeted to invoke a floating-point implementation in a way that bypasses the +standard C environment. +Typically, if <CODE>testfloat</CODE> is wanted, it will be retargeted to invoke +a new floating-point implementation directly, making +<CODE><fenv.h></CODE> irrelevant. +For more about retargeting <CODE>testfloat</CODE>, see <NOBR>section 6.4</NOBR> +below, <I>Specializing the <CODE>testfloat</CODE> Program</I>. +</P> + + +<H3>6.3. Macros for Build Options</H3> + +<P> +The TestFloat source files are affected by a few C preprocessor macros: +<BLOCKQUOTE> +<DL> +<DT><CODE>LITTLEENDIAN</CODE> +<DD> +Must be defined for little-endian machines; +must not be defined for big-endian machines. +<DT><CODE>EXTFLOAT80</CODE> +<DD> +Must be defined if the TestFloat programs are to support the +<NOBR>80-bit</NOBR> double-extended-precision floating-point format. +<DT><CODE>FLOAT128</CODE> +<DD> +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 +definition is irrelevant; +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 +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). +</P> + + +<H3>6.4. Specializing the <CODE>testfloat</CODE> Program</H3> + +<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>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> +<CODE>double</CODE> if the sources are compiled with one of these macros +defined: +<BLOCKQUOTE> +<DL> +<DT><CODE>LONG_DOUBLE_IS_EXTFLOAT80</CODE> +<DD> +Indicates that type <CODE>long</CODE> <CODE>double</CODE> is +<NOBR>80-bit</NOBR> double-extended-precision floating-point. +<DT><CODE>LONG_DOUBLE_IS_FLOAT128</CODE> +<DD> +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 +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. +If the fifth rounding mode, <CODE>near_maxMag</CODE>, is also supported, an +additional macro can be defined: +<BLOCKQUOTE> +<DL> +<DT><CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE> +<DD> +Indicates that the subject floating-point supports rounding mode +<CODE>near_maxMag</CODE> (nearest/away). +</DL> +</BLOCKQUOTE> +</P> + +<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. +Two source files define the functions that <CODE>testfloat</CODE> uses to +invoke floating-point operations for testing: +<PRE> + 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. +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, +where <CODE><target></CODE> names the particular target. +</P> + +<P> +Header file <CODE>subjfloat_config.h</CODE> defines a macro of the form +<CODE>SUBJ_*</CODE> for each subject function supported. +For example, if function <CODE>subj_f32_add</CODE> exists to perform +<NOBR>32-bit</NOBR> floating-point addition, then +<CODE>subjfloat_config.h</CODE> should have a definition for macro +<CODE>SUBJ_F32_ADD</CODE>. +The actual function <CODE>subj_f32_add</CODE> is expected to be defined in +<CODE>subjfloat.c</CODE>, along with all other subject functions. +A common header file, <CODE>subjfloat.h</CODE>, (not target-specific) provides +prototype declarations for all possible subject functions that +<CODE>testfloat</CODE> may be compiled to test, whether actually existing or +not. +(There is no penalty for the header to declare prototypes of nonexistent +functions that are never called.) +For a specific build of <CODE>testfloat</CODE>, the <CODE>-list</CODE> option +will list all subject functions that the <CODE>testfloat</CODE> program is able +to invoke and thus test. +</P> + +<P> +In the source code as supplied, macros <CODE>LONG_DOUBLE_IS_EXTFLOAT80</CODE> +and <CODE>LONG_DOUBLE_IS_FLOAT128</CODE> affect only the target-specific source +files in <NOBR><CODE>source/subj-C</CODE></NOBR>, so these macros can be +ignored for any other subject floating-point that does not depend on them. +On the other hand, macro <CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE> always +determines whether the <CODE>testfloat</CODE> program attempts to test rounding +mode <CODE>near_maxMag</CODE>, regardless of the subject floating-point. +</P> + + +<H3>6.5. Improving the Random Number Functions</H3> + +<P> +If you are serious about using TestFloat for testing floating-point, you should +consider replacing the random number functions in <CODE>random.c</CODE>. +The supplied random number functions are built on top of the standard C +<CODE>rand</CODE> function. +Because function <CODE>rand</CODE> is rather poor on some systems, the +functions in <CODE>random.c</CODE> assume very little about the quality of +<CODE>rand</CODE>. +As a result, <CODE>rand</CODE> is called more frequently than it might need to +be, shortening the time before random number sequences repeat, and possibly +wasting time as well. +If <CODE>rand</CODE> is better on a given target platform, or if another, +better random number generator is available (such as <CODE>rand48</CODE> on +most UNIX-derived systems), TestFloat can be improved by overriding the given +<CODE>random.c</CODE> with a target-specific one. +</P> + +<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 +<CODE>random.c</CODE>. +</P> + + +<H2>7. Contact Information</H2> + +<P> +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 +<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></A>. +</P> + + +</BODY> + diff --git a/doc/testfloat.html b/doc/testfloat.html new file mode 100644 index 0000000..7779214 --- /dev/null +++ b/doc/testfloat.html @@ -0,0 +1,259 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>testfloat</CODE></H1> + +<P> +John R. Hauser<BR> +2014 ______<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +<BR> +*** REPLACE APOSTROPHES. +<BR> +*** REPLACE EM DASH. +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>testfloat</CODE> program tests an implementation of floating-point +arithmetic for conformity to the IEEE Standard for Binary Floating-Point +Arithmetic. +<CODE>testfloat</CODE> is part of the Berkeley TestFloat package, a small +collection of programs for performing such tests. +For general information about TestFloat, see file +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +The <CODE>testfloat</CODE> program is an all-in-one tool for testing +floating-point arithmetic. +It generates test operand values, invokes a floating-point operation with the +generated operands, and examines the corresponding computed results, reporting +unexpected results as likely errors. +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 +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 +instructions or a new set of subroutines), a new <CODE>testfloat</CODE> must be +compiled containing the code needed to invoke the new floating-point. +</P> + +<P> +The default build of <CODE>testfloat</CODE> assumes that C types +<CODE>float</CODE> and <CODE>double</CODE> are <NOBR>32-bit</NOBR> and +<NOBR>64-bit</NOBR> binary floating-point types conforming to the IEEE +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. +</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. +For double-extended-precision operations affected by rounding precision +control, <CODE>testfloat</CODE> 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 command-line options. +</P> + +<P> +For more about the operation of <CODE>testfloat</CODE> and how to interpret its +output, refer to +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testfloat</CODE> program is executed as a command with this syntax: +<PRE> + testfloat [<option>...] <function> +</PRE> +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 +function set. +The available options and function sets are documented below. +The <CODE>-list</CODE> option can be used to obtain a list of all testable +operations for a given build of <CODE>testfloat</CODE>. +If <CODE>testfloat</CODE> is executed without any arguments, a summary of usage +is written. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testfloat</CODE> program accepts several command options. +If mutually contradictory options are given, the last one has priority. +</P> + +<H3><CODE>-help</CODE></H3> + +<P> +The <CODE>-help</CODE> option causes a summary of program usage to be written, +after which the program exits. +</P> + +<H3><CODE>-list</CODE></H3> + +<P> +The <CODE>-list</CODE> option causes a list of testable operations to be +written, after which the program exits. +The set of testable operations is just the set of operations that this build of +<CODE>testfloat</CODE> has some way to invoke for testing. +</P> + +<H3><CODE>-level <num></CODE></H3> + +<P> +The <CODE>-level</CODE> option sets the level of testing. +The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>. +The default is <NOBR>level 1</NOBR>. +Level 2 performs many more tests than <NOBR>level 1</NOBR> and thus can reveal +bugs not found by <NOBR>level 1</NOBR>. +</P> + +<H3><CODE>-errors <num></CODE></H3> + +<P> +The <CODE>-errors</CODE> option instructs <CODE>testfloat</CODE> to report no +more than the specified number of errors for any combination of operation, +rounding mode, etc. +The argument to <CODE>-errors</CODE> must be a nonnegative decimal integer. +Once the specified number of error reports has been generated, +<CODE>testfloat</CODE> ends the current test and begins the next one, if any. +The default is <NOBR><CODE>-errors</CODE> <CODE>20</CODE></NOBR>. +</P> + +<P> +Against intuition, <NOBR><CODE>-errors</CODE> <CODE>0</CODE></NOBR> causes +<CODE>testfloat</CODE> to report every error it finds. +</P> + +<H3><CODE>-errorstop</CODE></H3> + +<P> +The <CODE>-errorstop</CODE> option causes the program to exit after the first +operation for which any errors are reported. +</P> + +<H3><CODE>-forever</CODE></H3> + +<P> +The <CODE>-forever</CODE> option causes a single operation to be repeatedly +tested. +Only one rounding mode and/or rounding precision can be tested in a single +execution. +If not specified, the rounding mode defaults to nearest/even. +For <NOBR>80-bit</NOBR> double-extended-precision operations, the rounding +precision defaults to full double-extended precision. +The testing level is set to 2 by this option. +</P> + +<H3><CODE>-checkNaNs</CODE></H3> + +<P> +The <CODE>-checkNaNs</CODE> option causes <CODE>testfloat</CODE> to verify the +bitwise correctness of NaN results. +In order for this option to be sensible, <CODE>testfloat</CODE> must have been +compiled so that its internal reference implementation of floating-point +(SoftFloat) generates the proper NaN results for the system being tested. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +For <NOBR>80-bit</NOBR> double-extended-precision operations affected by +rounding precision control, the <CODE>-precision32</CODE> option restricts +testing to only the cases in which the rounding precision is +<NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> single-precision. +The other rounding precision choices are not tested. +Likewise, <CODE>-precision64</CODE> fixes the rounding precision to +<NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision, and +<CODE>-precision80</CODE> fixes the rounding precision to the full +<NOBR>80 bits</NOBR> of the double-extended-precision format. +All these options are ignored for operations not affected by rounding precision +control. +</P> + +<P> +The precision-control options may not be accepted at all if no +double-extended-precision operations are testable. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3> + +<P> +The <CODE>-rnear_even</CODE> option restricts testing to only the cases in +which the rounding mode is nearest/even. +The other rounding mode choices are not tested. +Likewise, <CODE>-rnear_maxMag</CODE> forces rounding to nearest/maximum +magnitude (nearest-away), <CODE>-rminMag</CODE> forces rounding to minimum +magnitude (toward zero), <CODE>-rmin</CODE> forces rounding to minimum (down, +toward negative infinity), and <CODE>-rmax</CODE> forces rounding to maximum +(up, toward positive infinity). +These options are ignored for operations that are exact and thus do not round. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +The <CODE>-tininessbefore</CODE> option indicates that the floating-point +implementation being tested detects tininess on underflow before rounding. +The <CODE>-tininessafter</CODE> option indicates that tininess is detected +after rounding. +The <CODE>testfloat</CODE> program alters its expectations accordingly. +These options override the default selected when <CODE>testfloat</CODE> was +compiled. +Choosing the wrong one of these two options should cause error reports for some +(but not all) operations. +</P> + + +<H2>Function Sets</H2> + +<P> +Just as <CODE>testfloat</CODE> can test an operation for all five rounding +modes in sequence, multiple operations can be tested with a single execution of +<CODE>testfloat</CODE>. +Two sets are recognized: <CODE>-all1</CODE> and <CODE>-all2</CODE>. +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 +<PRE> + testfloat [<option>...] -all1 +</PRE> +</P> + + +</BODY> + diff --git a/doc/testfloat_gen.html b/doc/testfloat_gen.html new file mode 100644 index 0000000..43e6d20 --- /dev/null +++ b/doc/testfloat_gen.html @@ -0,0 +1,341 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat_gen</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>testfloat_gen</CODE></H1> + +<P> +John R. Hauser<BR> +2014 ______<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +<BR> +*** REPLACE APOSTROPHES. +<BR> +*** REPLACE EM DASH. +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>testfloat_gen</CODE> program generates test cases for testing that an +implementation of floating-point arithmetic conforms to the IEEE Standard for +Binary Floating-Point Arithmetic. +<CODE>testfloat_gen</CODE> is part of the Berkeley TestFloat package, a small +collection of programs for performing such tests. +For general information about TestFloat, see file +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +A single execution of <CODE>testfloat_gen</CODE> generates test cases for only +a single floating-point operation and associated options. +The <CODE>testfloat_gen</CODE> program must be repeatedly executed to generate +test cases for each operation to be tested. +</P> + +<P> +<CODE>testfloat_gen</CODE> writes the test cases it generates to standard +output. +This output can either be captured in a file through redirection, or be piped +to another program that exercises a floating-point operation using the test +cases as they are supplied. +Depending on use, the total output from <CODE>testfloat_gen</CODE> can be +large, so piping to another program may be the best choice to avoid 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>. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testfloat_gen</CODE> program is executed as a command in one of these +forms: +<PRE> + testfloat_gen [<option>...] <type> + testfloat_gen [<option>...] <function> +</PRE> +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> +specifying the type and number of output or a <CODE><function></CODE> +naming a floating-point operation. +If <CODE>testfloat_gen</CODE> is executed without any arguments, a summary of +usage is written. +</P> + +<P> +A <CODE><type></CODE> can be one of the following: +<BLOCKQUOTE> +<TABLE> +<TR> +<TD><CODE>ui32</CODE></TD> +<TD>unsigned <NOBR>32-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>ui64</CODE></TD> +<TD>unsigned <NOBR>64-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>i32</CODE></TD> +<TD>signed <NOBR>32-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>i64</CODE></TD> +<TD>signed <NOBR>64-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>f32 [<num>]</CODE></TD> +<TD>one or more <NOBR>32-bit</NOBR> single-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>f64 [<num>]</CODE></TD> +<TD>one or more <NOBR>64-bit</NOBR> double-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>extF80 [<num>] </CODE></TD> +<TD>one or more <NOBR>80-bit</NOBR> double-extended-precision floating-point +values</TD> +</TR> +<TR> +<TD><CODE>f128 [<num>]</CODE></TD> +<TD>one or more <NOBR>128-bit</NOBR> quadruple-precision floating-point +values</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +Optional <CODE><num></CODE> is one of 1, 2, <NOBR>or 3</NOBR>. +If a <CODE><type></CODE> is given without <CODE><num></CODE> (such +as <CODE>ui32</CODE> or <CODE>f64</CODE>), <CODE>testfloat_gen</CODE> outputs a +list of values of the specified type, one value per line, appropriate for +testing a floating-point operation with exactly one operand of the given type. +If a floating-point type and number are given (such as +<NOBR><CODE>f32</CODE> <CODE>2</CODE></NOBR> or +<NOBR><CODE>extF80</CODE> <CODE>1</CODE></NOBR>), <CODE>testfloat_gen</CODE> +outputs the specified number of values per line, appropriate for testing a +floating-point operation with that number of operands. +Although the exact operation being tested is not specified, the test cases +output by <CODE>testfloat_gen</CODE> cover all standard floating-point +operations, to the degree explained in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +If a <CODE><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). +The available operation names are listed in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +In all cases, floating-point operations have two results: +first, a value, which may be floating-point, integer, or Boolean, and, second, +the floating-point exception flags raised by the operation. +If the output from a tested floating-point operation does not match the +expected output specified by <CODE>testfloat_gen</CODE>, this may or may not +indicate an error in the floating-point operation. +For further explanation, see +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>, +especially the section titled <I>Variations Allowed by the IEEE Floating-Point +Standard</I>. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testfloat_gen</CODE> program accepts several command options. +If mutually contradictory options are given, the last one has priority. +</P> + +<H3><CODE>-help</CODE></H3> + +<P> +The <CODE>-help</CODE> option causes a summary of program usage to be written, +after which the program exits. +</P> + +<H3><CODE>-prefix <text></CODE></H3> + +<P> +The <CODE>-prefix</CODE> option causes <CODE>testfloat_gen</CODE> to write the +supplied text argument verbatim as the first line of output before any test +cases. +This can be used, for example, to indicate to a downstream program what kind of +test to perform for the test cases that follow. +</P> + +<H3><CODE>-level <num></CODE></H3> + +<P> +The <CODE>-level</CODE> option sets the level of testing. +The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>. +The default is <NOBR>level 1</NOBR>. +<NOBR>Level 2</NOBR> causes many more test cases to be generated, with better +coverage, than <NOBR>level 1</NOBR>. +</P> + +<H3><CODE>-n <num></CODE></H3> + +<P> +Option <CODE>-n</CODE> specifies the number of test cases to generate. +For each <CODE><type></CODE> or <CODE><function></CODE> and each +testing level (set by <CODE>-level</CODE>), there is a minimum value that +<CODE>testfloat_gen</CODE> will accept for <CODE><num></CODE>. +If no <CODE>-n</CODE> option is given, the number of test cases generated by +<CODE>testfloat_gen</CODE> equals the minimum value acceptable for the +<CODE>-n</CODE> argument. +Option <CODE>-n</CODE> cannot be used to reduce this number, but can increase +it, without changing the testing level. +</P> + +<H3><CODE>-forever</CODE></H3> + +<P> +The <CODE>-forever</CODE> option causes test cases to be generated +indefinitely, without limit (until the program is terminated by some external +cause). +The testing level is set to 2 by this option. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that is an +<NOBR>80-bit</NOBR> double-extended-precision operation affected by rounding +precision control, the <CODE>-precision32</CODE> option sets the rounding +precision to <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> +single-precision. +Likewise, <CODE>-precision64</CODE> sets the rounding precision to +<NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision, and +<CODE>-precision80</CODE> sets the rounding precision to the full +<NOBR>80 bits</NOBR> of the double-extended-precision format. +All these options are ignored for operations not affected by rounding precision +control. +When rounding precision is applicable but not specified, the default is the +full <NOBR>80 bits</NOBR>, same as <CODE>-precision80</CODE>. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that requires rounding, the +<CODE>-rnear_even</CODE> option sets the rounding mode to nearest/even; +<CODE>-rnear_maxMag</CODE> sets rounding to nearest/maximum magnitude +(nearest-away); +<CODE>-rminMag</CODE> sets rounding to minimum magnitude (toward zero); +<CODE>-rmin</CODE> sets rounding to minimum (down, toward negative infinity); +and <CODE>-rmax</CODE> sets rounding to maximum (up, toward positive infinity). +These options are ignored for operations that are exact and thus do not round. +When rounding mode is relevant but not specified, the default is to round to +nearest/even, same as <CODE>-rnear_even</CODE>. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that requires rounding, the +<CODE>-tininessbefore</CODE> option indicates that tininess on underflow will +be detected before rounding, while <CODE>-tininessafter</CODE> indicates that +tininess on underflow will be detected after rounding. +These options are ignored for operations that are exact and thus do not round. +When the method of tininess detection matters but is not specified, the default +is to detect tininess on underflow before rounding, same as +<CODE>-tininessbefore</CODE>. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +When a <CODE><function></CODE> is specified that rounds to an integer +(either conversion to an integer type or a <CODE>roundToInt</CODE> operation), +the <CODE>-notexact</CODE> option indicates that the <I>inexact</I> exception +flag is never raised, while <CODE>-exact</CODE> indicates that the +<I>inexact</I> exception flag is to be raised if the result is inexact. +For other operations, these options are ignored. +If neither option is specified, the default is not to raise the <I>inexact</I> +exception flag when rounding to an integer, same as <CODE>-notexact</CODE>. +</P> + + +<H2>Output Format</H2> + +<P> +For each test case generated, <CODE>testfloat_gen</CODE> writes a single line +of text to standard output. +When the <CODE>testfloat_gen</CODE> command is given a +<CODE><type></CODE> argument, each test case consists of either one +integer value or one, two, or three floating-point values. +Each value is written to output as a raw hexadecimal number. +When there is more than one value per line, they are separated by spaces. +For example, output from executing +<PRE> + testfloat_gen f64 2 +</PRE> +might look like this: +<PRE> + 3F90EB5825D6851E C3E0080080000000 + 41E3C00000000000 C182024F8AE474A8 + 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 + 3FFFED6A25C534BE 3CA1000000020000 + ... +</PRE> +with each hexadecimal number being one <NOBR>64-bit</NOBR> floating-point +value. +Note that, for floating-point values, the sign and exponent are at the +most-significant end of the number. +Thus, for the first number on the first line above, the leading hexadecimal +digits <CODE>3F9</CODE> are the sign and encoded exponent of the +<NOBR>64-bit</NOBR> floating-point value, and the remaining digits are the +encoded significand. +</P> + +<P> +When <CODE>testfloat_gen</CODE> is given a <CODE><function></CODE> +operation name, each line of output has not only the operands for the operation +but also the expected output, consisting of a result value and the exception +flags that are raised. +For example, the output from +<PRE> + testfloat_gen f64_add +</PRE> +could include these lines: +<PRE> + 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 + 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 + 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 + 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 + ... +</PRE> +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> +</BLOCKQUOTE> +</P> + + +</BODY> + diff --git a/doc/testfloat_ver.html b/doc/testfloat_ver.html new file mode 100644 index 0000000..4d1540e --- /dev/null +++ b/doc/testfloat_ver.html @@ -0,0 +1,250 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat_ver</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>testfloat_ver</CODE></H1> + +<P> +John R. Hauser<BR> +2014 ______<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +<BR> +*** REPLACE APOSTROPHES. +<BR> +*** REPLACE EM DASH. +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>testfloat_ver</CODE> program takes test-case results obtained from +exercising an implementation of floating-point arithmetic and verifies that +those results conform to the IEEE Standard for Binary Floating-Point +Arithmetic. +<CODE>testfloat_ver</CODE> is part of the Berkeley TestFloat package, a small +collection of programs for performing such tests. +For general information about TestFloat, see file +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +A single execution of <CODE>testfloat_ver</CODE> verifies results for only a +single floating-point operation and associated options. +The <CODE>testfloat_ver</CODE> program must be repeatedly executed to verify +results for each operation to be tested. +</P> + +<P> +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, +described in the section below titled <I>Input Format</I>. +</P> + +<P> +For each test case given to it, <CODE>testfloat_ver</CODE> examines the +computed results and reports any unexpected results as likely errors. + +For more about the operation of <CODE>testfloat_ver</CODE> and how to interpret +its output, refer to +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testfloat_ver</CODE> program is executed as a command with this +syntax: +<PRE> + testfloat_ver [<option>...] <function> +</PRE> +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. +The available options are documented below. +The testable operation names are listed in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +If <CODE>testfloat_ver</CODE> is executed without any arguments, a summary of +usage is written. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testfloat_ver</CODE> program accepts several command options. +If mutually contradictory options are given, the last one has priority. +</P> + +<H3><CODE>-help</CODE></H3> + +<P> +The <CODE>-help</CODE> option causes a summary of program usage to be written, +after which the program exits. +</P> + +<H3><CODE>-errors <num></CODE></H3> + +<P> +The <CODE>-errors</CODE> option instructs <CODE>testfloat_ver</CODE> to report +no more than the specified number of errors. +The argument to <CODE>-errors</CODE> must be a nonnegative decimal integer. +Once the specified number of error reports has been generated, the program +exits. +The default is <NOBR><CODE>-errors</CODE> <CODE>20</CODE></NOBR>. +</P> + +<P> +Against intuition, <NOBR><CODE>-errors</CODE> <CODE>0</CODE></NOBR> causes +<CODE>testfloat_ver</CODE> to continue for any number of errors. +</P> + +<H3><CODE>-checkNaNs</CODE></H3> + +<P> +The <CODE>-checkNaNs</CODE> option causes <CODE>testfloat_ver</CODE> to verify +the bitwise correctness of NaN results. +In order for this option to be sensible, <CODE>testfloat_ver</CODE> must have +been compiled so that its internal reference implementation of floating-point +(SoftFloat) generates the proper NaN results for the system being tested. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +When <CODE><function></CODE> is an <NOBR>80-bit</NOBR> +double-extended-precision operation affected by rounding precision control, the +<CODE>-precision32</CODE> option indicates that the rounding precision should +be <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> single-precision. +Likewise, <CODE>-precision64</CODE> indicates that the rounding precision +should be <NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> +double-precision, and <CODE>-precision80</CODE> indicates that the rounding +precision should be the full <NOBR>80 bits</NOBR> of the +double-extended-precision format. +All these options are ignored for operations not affected by rounding precision +control. +When rounding precision is applicable but not specified, the default assumption +is the full <NOBR>80 bits</NOBR>, same as <CODE>-precision80</CODE>. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3> + +<P> +When <CODE><function></CODE> is an operation that requires rounding, the +<CODE>-rnear_even</CODE> option indicates that rounding should be to +nearest/even, <CODE>-rnear_maxMag</CODE> indicates rounding to nearest/maximum +magnitude (nearest-away), <CODE>-rminMag</CODE> indicates rounding to minimum +magnitude (toward zero), <CODE>-rmin</CODE> indicates rounding to minimum +(down, toward negative infinity), and <CODE>-rmax</CODE> indicates rounding to +maximum (up, toward positive infinity). +These options are ignored for operations that are exact and thus do not round. +When rounding mode is relevant but not specified, the default assumption is +rounding to nearest/even, same as <CODE>-rnear_even</CODE>. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +When <CODE><function></CODE> is an operation that requires rounding, the +<CODE>-tininessbefore</CODE> option indicates that tininess on underflow should +be detected before rounding, while <CODE>-tininessafter</CODE> indicates that +tininess on underflow should be detected after rounding. +These options are ignored for operations that are exact and thus do not round. +When the method of tininess detection matters but is not specified, the default +assumption is that tininess should be detected before rounding, same as +<CODE>-tininessbefore</CODE>. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +When <CODE><function></CODE> is an operation that rounds to an integer +(either conversion to an integer type or a <CODE>roundToInt</CODE> operation), +the <CODE>-notexact</CODE> option indicates that the <I>inexact</I> exception +flag should never be raised, while <CODE>-exact</CODE> indicates that the +<I>inexact</I> exception flag should be raised when the result is inexact. +For other operations, these options are ignored. +If neither option is specified, the default assumption is that the +<I>inexact</I> exception flag should not be raised when rounding to an integer, +same as <CODE>-notexact</CODE>. +</P> + + +<H2>Input Format</H2> + +<P> +For a given <CODE><function></CODE> argument, the input format expected +by <CODE>testfloat_ver</CODE> is the same as the output generated by program +<A HREF="testfloat_gen.html"><NOBR><CODE>testfloat_gen</CODE></NOBR></A> for +the same argument. +</P> + +<P> +Input to <CODE>testfloat_ver</CODE> is expected to be text, with each line +containing the data for one test case. +The number of input lines thus equals the number of test cases. +A single test case is organized as follows: first are the operands for the +operation, next is the result value obtained, and last is a number indicating +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 +<PRE> + testfloat_ver f64_add +</PRE> +valid input could include these lines: +<PRE> + 3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 + 41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 + 7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 + 3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 + ... +</PRE> +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 +the last hexadecimal number gives the exception flags that were raised by the +operation. +</P> + +<P> +Note that, for floating-point values, the sign and exponent are at the +most-significant end of the number. +Thus, for the first number on the first line above, the leading hexadecimal +digits <CODE>3F9</CODE> are the sign and encoded exponent of the +<NOBR>64-bit</NOBR> floating-point value, and the remaining digits are the +encoded significand. +</P> + +<P> +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> +</BLOCKQUOTE> +</P> + + +</BODY> + diff --git a/doc/testsoftfloat.html b/doc/testsoftfloat.html new file mode 100644 index 0000000..49215de --- /dev/null +++ b/doc/testsoftfloat.html @@ -0,0 +1,229 @@ + +<HTML> + +<HEAD> +<TITLE>testsoftfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>testsoftfloat</CODE></H1> + +<P> +John R. Hauser<BR> +2014 ______<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +<BR> +*** REPLACE APOSTROPHES. +<BR> +*** REPLACE EM DASH. +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>testsoftfloat</CODE> program tests that a build of the Berkeley +SoftFloat library conforms to the IEEE Standard for Binary Floating-Point +Arithmetic as expected. +Program <CODE>testsoftfloat</CODE> is part of the Berkeley TestFloat package, a +small collection of programs for performing such tests. +For general information about TestFloat, as well as for basics about the +operation of <CODE>testsoftfloat</CODE> and how to interpret its output, see +file +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +Note that, even if there are no bugs in the source code for SoftFloat (not +guaranteed), a build of SoftFloat might still fail due to an issue with the +build process, such as an incompatible compiler option or a compiler bug. +</P> + +<P> +The <CODE>testsoftfloat</CODE> program will ordinarily test a function for all +rounding modes 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 +tested only with the rounding mode set to <CODE>near_even</CODE> +(nearest/even). +In the same way, if an operation is affected by the way in which underflow +tininess is detected, <CODE>testsoftfloat</CODE> tests the function with +tininess detected both before rounding and after rounding. +For <NOBR>80-bit</NOBR> double-extended-precision operations affected by +rounding precision control, <CODE>testsoftfloat</CODE> also tests the function +for all three rounding precision modes, one after the other. +Testing can be limited to a single rounding mode, a single tininess mode, +and/or a single rounding precision with appropriate command-line options. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testsoftfloat</CODE> program is executed as a command with this +syntax: +<PRE> + testsoftfloat [<option>...] <function> +</PRE> +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 +function set. +The available options and function sets are documented below. +If <CODE>testsoftfloat</CODE> is executed without any arguments, a summary of +usage is written. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testsoftfloat</CODE> program accepts several command options. +If mutually contradictory options are given, the last one has priority. +</P> + +<H3><CODE>-help</CODE></H3> + +<P> +The <CODE>-help</CODE> option causes a summary of program usage to be written, +after which the program exits. +</P> + +<H3><CODE>-level <num></CODE></H3> + +<P> +The <CODE>-level</CODE> option sets the level of testing. +The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>. +The default is <NOBR>level 1</NOBR>. +Level 2 performs many more tests than <NOBR>level 1</NOBR> and thus can reveal +bugs not found by <NOBR>level 1</NOBR>. +</P> + +<H3><CODE>-errors <num></CODE></H3> + +<P> +The <CODE>-errors</CODE> option instructs <CODE>testsoftfloat</CODE> to report +no more than the specified number of errors for any combination of function, +rounding mode, etc. +The argument to <CODE>-errors</CODE> must be a nonnegative decimal integer. +Once the specified number of error reports has been generated, +<CODE>testsoftfloat</CODE> ends the current test and begins the next one, if +any. +The default is <NOBR><CODE>-errors</CODE> <CODE>20</CODE></NOBR>. +</P> + +<P> +Against intuition, <NOBR><CODE>-errors</CODE> <CODE>0</CODE></NOBR> causes +<CODE>testsoftfloat</CODE> to report every error it finds. +</P> + +<H3><CODE>-errorstop</CODE></H3> + +<P> +The <CODE>-errorstop</CODE> option causes the program to exit after the first +function for which any errors are reported. +</P> + +<H3><CODE>-forever</CODE></H3> + +<P> +The <CODE>-forever</CODE> option causes a single function to be repeatedly +tested. +Only one rounding mode and/or rounding precision can be tested in a single +execution. +If not specified, the rounding mode defaults to nearest/even. +For <NOBR>80-bit</NOBR> double-extended-precision functions, the rounding +precision defaults to full double-extended precision. +The testing level is set to 2 by this option. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +For <NOBR>80-bit</NOBR> double-extended-precision funcions affected by +rounding precision control, the <CODE>-precision32</CODE> option restricts +testing to only the cases in which the rounding precision is +<NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> single-precision. +The other rounding precision choices are not tested. +Likewise, <CODE>-precision64</CODE> fixes the rounding precision to +<NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision; +and <CODE>-precision80</CODE> fixes the rounding precision to the full +<NOBR>80 bits</NOBR> of the double-extended-precision format. +All these options are ignored for operations not affected by rounding precision +control. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3> + +<P> +The <CODE>-rnear_even</CODE> option restricts testing to only the cases in +which the rounding mode is nearest/even. +The other rounding mode choices are not tested. +Likewise, <CODE>-rnear_maxMag</CODE> forces rounding to nearest/maximum +magnitude (nearest-away), <CODE>-rminMag</CODE> forces rounding to minimum +magnitude (toward zero), <CODE>-rmin</CODE> forces rounding to minimum (down, +toward negative infinity), and <CODE>-rmax</CODE> forces rounding to maximum +(up, toward positive infinity). +These options are ignored for operations that are exact and thus do not round. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +The <CODE>-tininessbefore</CODE> option restricts testing to only the cases in +which tininess on underflow is detected before rounding. +Likewise, <CODE>-tininessafter</CODE> restricts testing to only the cases in +which tininess on underflow is detected after rounding. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +For functions that round to an integer (conversions to integer types and the +<CODE>roundToInt</CODE> functions), the <CODE>-notexact</CODE> option restricts +testing to only the cases for which the <CODE><I>exact</I></CODE> operand +(specifying whether the <I>inexact</I> exception flag may be raised) is +<CODE>false</CODE>. +Likewise, the <CODE>-exact</CODE> option restricts testing to only the cases +for which the <CODE><I>exact</I></CODE> operand is <CODE>true</CODE>. +</P> + + +<H2>Function Sets</H2> + +<P> +Just as <CODE>testsoftfloat</CODE> can test a function for all five rounding +modes in sequence, multiple functions can be tested with a single execution of +<CODE>testsoftfloat</CODE>. +Two sets are recognized: <CODE>-all1</CODE> and <CODE>-all2</CODE>. +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 +<PRE> + testsoftfloat [<option>...] -all1 +</PRE> +</P> + +<P> +For the purpose of deciding the number of operands of an operation, any +<CODE><I>roundingMode</I></CODE> and <CODE><I>exact</I></CODE> arguments are +ignored. +(Such arguments specify the rounding mode and whether the <I>inexact</I> +exception flag may be raised, respectively.) +Thus, functions that convert to integer type and the <CODE>roundToInt</CODE> +functions are included in the set of one-operand operations tested by +<CODE>-all1</CODE>. +</P> + + +</BODY> + diff --git a/doc/timesoftfloat.html b/doc/timesoftfloat.html new file mode 100644 index 0000000..b214611 --- /dev/null +++ b/doc/timesoftfloat.html @@ -0,0 +1,202 @@ + +<HTML> + +<HEAD> +<TITLE>timesoftfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: <CODE>timesoftfloat</CODE></H1> + +<P> +John R. Hauser<BR> +2014 ______<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +<BR> +*** REPLACE APOSTROPHES. +<BR> +*** REPLACE EM DASH. +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>timesoftfloat</CODE> program provides a simple way to evaluate the +speed of the floating-point operations of the Berkeley SoftFloat library. +Program <CODE>timesoftfloat</CODE> is included with the Berkeley TestFloat +package, a small collection of programs for testing that an implementation of +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. +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 +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 +timed only with the rounding mode set to <CODE>near_even</CODE> (nearest/even). +In the same way, if an operation is affected by the way in which underflow +tininess is detected, <CODE>timesoftfloat</CODE> times the function with +tininess detected both before rounding and after rounding. +For <NOBR>80-bit</NOBR> double-extended-precision operations affected by +rounding precision control, <CODE>timesoftfloat</CODE> also times the function +for each of the three rounding precision modes, one after the other. +Evaluation of a function can be limited to a single rounding mode, a single +tininess mode, and/or a single rounding precision with appropriate command-line +options. +</P> + +<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''. +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. +Your actual experience with SoftFloat may differ from the speeds reported by +<CODE>timesoftfloat</CODE> for all these reasons. +</P> + +<P> +Note that the remainder operations (<CODE>f32_rem</CODE>, <CODE>f64_rem</CODE>, +<CODE>extF80_rem</CODE>, and <CODE>f128_rem</CODE>) will be markedly slower +than other operations, particularly for double-extended-precision +(<CODE>extF80_rem</CODE>) and quadruple precision (<CODE>f128_rem</CODE>). +This is inherent to the remainder operation itself and is not a failing of the +SoftFloat implementation. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>timesoftfloat</CODE> program is executed as a command with this +syntax: +<PRE> + timesoftfloat [<option>...] <function> +</PRE> +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 +function set. +The available options and function sets are documented below. +If <CODE>timesoftfloat</CODE> is executed without any arguments, a summary of +usage is written. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>timesoftfloat</CODE> program accepts several command options. +If mutually contradictory options are given, the last one has priority. +</P> + +<H3><CODE>-help</CODE></H3> + +<P> +The <CODE>-help</CODE> option causes a summary of program usage to be written, +after which the program exits. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +For <NOBR>80-bit</NOBR> double-extended-precision funcions affected by +rounding precision control, the <CODE>-precision32</CODE> option restricts +timing of an operation to only the cases in which the rounding precision is +<NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> single-precision. +Other rounding precision choices are not timed. +Likewise, <CODE>-precision64</CODE> fixes the rounding precision to +<NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision; +and <CODE>-precision80</CODE> fixes the rounding precision to the full +<NOBR>80 bits</NOBR> of the double-extended-precision format. +All these options are ignored for operations not affected by rounding precision +control. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax</CODE></H3> + +<P> +The <CODE>-rnear_even</CODE> option restricts timing of an operation to only +the cases in which the rounding mode is nearest/even. +Other rounding mode choices are not timed. +Likewise, <CODE>-rnear_maxMag</CODE> forces rounding to nearest/maximum +magnitude (nearest-away), <CODE>-rminMag</CODE> forces rounding to minimum +magnitude (toward zero), <CODE>-rmin</CODE> forces rounding to minimum (down, +toward negative infinity), and <CODE>-rmax</CODE> forces rounding to maximum +(up, toward positive infinity). +These options are ignored for operations that are exact and thus do not round. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +The <CODE>-tininessbefore</CODE> option restricts timing of an operation to +only the cases in which tininess on underflow is detected before rounding. +Likewise, <CODE>-tininessafter</CODE> restricts measurement to only the cases +in which tininess on underflow is detected after rounding. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +For functions that round to an integer (conversions to integer types and the +<CODE>roundToInt</CODE> functions), the <CODE>-notexact</CODE> option restricts +timing of an operation to only the cases for which the +<CODE><I>exact</I></CODE> operand (specifying whether the <I>inexact</I> +exception flag may be raised) is <CODE>false</CODE>. +Likewise, the <CODE>-exact</CODE> option restricts measurement to only the +cases for which the <CODE><I>exact</I></CODE> operand is <CODE>true</CODE>. +</P> + + +<H2>Function Sets</H2> + +<P> +Just as <CODE>timesoftfloat</CODE> can time a function for all five rounding +modes in sequence, multiple functions can be timed with a single execution of +<CODE>timesoftfloat</CODE>. +Three sets are recognized: +<CODE>-all1</CODE>, <CODE>-all2</CODE>, and <CODE>-all</CODE>. +The set <CODE>-all1</CODE> comprises all one-operand operations, +<CODE>-all2</CODE> is all two-operand operations, and <CODE>-all</CODE> is +obviously all operations. +A function set is used in place of a function name in the +<CODE>timesoftfloat</CODE> command line, such as +<PRE> + timesoftfloat [<option>...] -all1 +</PRE> +</P> + +<P> +For the purpose of deciding the number of operands of an operation, any +<CODE><I>roundingMode</I></CODE> and <CODE><I>exact</I></CODE> arguments are +ignored. +(Such arguments specify the rounding mode and whether the <I>inexact</I> +exception flag may be raised, respectively.) +Thus, functions that convert to integer type and the <CODE>roundToInt</CODE> +functions are included in the set of one-operand operations timed by +<CODE>-all1</CODE>. +</P> + + +</BODY> + |