diff options
Diffstat (limited to 'src/libs/softfloat-3e/testfloat/doc')
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/TestFloat-general.html | 1148 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/TestFloat-history.html | 272 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/TestFloat-source.html | 639 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/testfloat.html | 286 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/testfloat_gen.html | 367 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/testfloat_ver.html | 270 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/testsoftfloat.html | 236 | ||||
| -rw-r--r-- | src/libs/softfloat-3e/testfloat/doc/timesoftfloat.html | 196 |
8 files changed, 3414 insertions, 0 deletions
diff --git a/src/libs/softfloat-3e/testfloat/doc/TestFloat-general.html b/src/libs/softfloat-3e/testfloat/doc/TestFloat-general.html new file mode 100644 index 00000000..55f67d71 --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/TestFloat-general.html @@ -0,0 +1,1148 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat General Documentation</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: General Documentation</H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</P> + + +<H2>Contents</H2> + +<BLOCKQUOTE> +<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> +<COL WIDTH=25> +<COL WIDTH=*> +<TR><TD COLSPAN=2>1. Introduction</TD></TR> +<TR><TD COLSPAN=2>2. Limitations</TD></TR> +<TR><TD COLSPAN=2>3. Acknowledgments and License</TD></TR> +<TR><TD COLSPAN=2>4. What TestFloat Does</TD></TR> +<TR><TD COLSPAN=2>5. Executing TestFloat</TD></TR> +<TR><TD COLSPAN=2>6. Operations Tested by TestFloat</TD></TR> +<TR><TD></TD><TD>6.1. Conversion Operations</TD></TR> +<TR><TD></TD><TD>6.2. Basic Arithmetic Operations</TD></TR> +<TR><TD></TD><TD>6.3. Fused Multiply-Add Operations</TD></TR> +<TR><TD></TD><TD>6.4. Remainder Operations</TD></TR> +<TR><TD></TD><TD>6.5. Round-to-Integer Operations</TD></TR> +<TR><TD></TD><TD>6.6. Comparison Operations</TD></TR> +<TR><TD COLSPAN=2>7. Interpreting TestFloat Output</TD></TR> +<TR> + <TD COLSPAN=2>8. Variations Allowed by the IEEE Floating-Point Standard</TD> +</TR> +<TR><TD></TD><TD>8.1. Underflow</TD></TR> +<TR><TD></TD><TD>8.2. NaNs</TD></TR> +<TR><TD></TD><TD>8.3. Conversions to Integer</TD></TR> +<TR><TD COLSPAN=2>9. Contact Information</TD></TR> +</TABLE> +</BLOCKQUOTE> + + +<H2>1. Introduction</H2> + +<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. +With the current release, the following binary formats can be tested: +<NOBR>16-bit</NOBR> half-precision, <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"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></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 3e</NOBR>. +This version differs from earlier releases 3b through 3d in only minor ways. +Compared to the original <NOBR>Release 3</NOBR>: +<UL> +<LI> +<NOBR>Release 3b</NOBR> added the ability to test the <NOBR>16-bit</NOBR> +half-precision format. +<LI> +<NOBR>Release 3c</NOBR> added the ability to test a rarely used rounding mode, +<I>round to odd</I>, also known as <I>jamming</I>. +<LI> +<NOBR>Release 3d</NOBR> modified the code for testing C arithmetic to +potentially include testing newer library functions <CODE>sqrtf</CODE>, +<CODE>sqrtl</CODE>, <CODE>fmaf</CODE>, <CODE>fma</CODE>, and <CODE>fmal</CODE>. +</UL> +This release adds a few more small improvements, including modifying the +expected behavior of rounding mode <CODE>odd</CODE> and fixing a minor bug in +the all-in-one <CODE>testfloat</CODE> program. +</P> + +<P> +Compared to Release 2c and earlier, the set of TestFloat programs, as well as +the programs’ arguments and behavior, changed some with +<NOBR>Release 3</NOBR>. +For more about the evolution of TestFloat releases, see +<A HREF="TestFloat-history.html"><NOBR><CODE>TestFloat-history.html</CODE></NOBR></A>. +</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"><NOBR><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></NOBR></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 was a completely new implementation +supplanting earlier releases. +The project to create <NOBR>Release 3</NOBR> (now <NOBR>through 3e</NOBR>) was +done in the employ of the University of California, Berkeley, within the +Department of Electrical Engineering and Computer Sciences, first for the +Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab. +The work was officially overseen by Prof. Krste Asanovic, with funding provided +by these sources: +<BLOCKQUOTE> +<TABLE> +<COL> +<COL WIDTH=10> +<COL> +<TR> +<TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD> +<TD></TD> +<TD> +Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery +(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +</TD> +</TR> +<TR> +<TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD> +<TD></TD> +<TD> +DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from +ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, +Oracle, and Samsung. +</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +The following applies to the whole of TestFloat <NOBR>Release 3e</NOBR> as well +as to each source file individually. +</P> + +<P> +Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the +University of California. +All rights reserved. +</P> + +<P> +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +<OL> + +<LI> +<P> +Redistributions of source code must retain the above copyright notice, this +list of conditions, and the following disclaimer. +</P> + +<LI> +<P> +Redistributions in binary form must reproduce the above copyright notice, this +list of conditions, and the following disclaimer in the documentation and/or +other materials provided with the distribution. +</P> + +<LI> +<P> +Neither the name of the University nor the names of its contributors may be +used to endorse or promote products derived from this software without specific +prior written permission. +</P> + +</OL> +</P> + +<P> +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS”, +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE +DISCLAIMED. +IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</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, +and 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"><NOBR><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></NOBR></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, plus possibly a sixth mode, <I>round to odd</I> +(depending on the options selected when TestFloat was built). +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> and +<CODE>-checkInvInts</CODE> options 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"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></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: +<BLOCKQUOTE> +<PRE> +testfloat_gen ... <<I>type</I>> | <<I>program-that-invokes-op</I>> | testfloat_ver ... <<I>function</I>> +</PRE> +</BLOCKQUOTE> +The program in the middle is not supplied by TestFloat but must be created +independently. +If for some reason this program cannot take command-line arguments, the +<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: +<BLOCKQUOTE> +<PRE> +testfloat_gen ... <<I>function</I>> | <<I>program-that-invokes-op-and-compares-results</I>> +</PRE> +</BLOCKQUOTE> +Again, the program that actually invokes the floating-point operation is not +supplied by TestFloat but must be created independently. +Depending on circumstance, it may be preferable either to let +<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>16-bit</NOBR> half-precision is +called <CODE>f16</CODE>, <NOBR>32-bit</NOBR> single-precision is +<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: +<BLOCKQUOTE> +<PRE> +ui32_to_f16 ui64_to_f16 i32_to_f16 i64_to_f16 +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 + +f16_to_ui32 f32_to_ui32 f64_to_ui32 extF80_to_ui32 f128_to_ui32 +f16_to_ui64 f32_to_ui64 f64_to_ui64 extF80_to_ui64 f128_to_ui64 +f16_to_i32 f32_to_i32 f64_to_i32 extF80_to_i32 f128_to_i32 +f16_to_i64 f32_to_i64 f64_to_i64 extF80_to_i64 f128_to_i64 + +f16_to_f32 f32_to_f16 f64_to_f16 extF80_to_f16 f128_to_f16 +f16_to_f64 f32_to_f64 f64_to_f32 extF80_to_f32 f128_to_f32 +f16_to_extF80 f32_to_extF80 f64_to_extF80 extF80_to_f64 f128_to_f64 +f16_to_f128 f32_to_f128 f64_to_f128 extF80_to_f128 f128_to_extF80 +</PRE> +</BLOCKQUOTE> +Abbreviations <CODE>ui32</CODE> and <CODE>ui64</CODE> indicate +<NOBR>32-bit</NOBR> and <NOBR>64-bit</NOBR> unsigned integer types, while +<CODE>i32</CODE> and <CODE>i64</CODE> indicate their signed counterparts. +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 +<BLOCKQUOTE> +<PRE> +<<I>float</I>>_to_<<I>int</I>> +</PRE> +</BLOCKQUOTE> +as listed above, operations converting to integer type have names of these +forms: +<BLOCKQUOTE> +<PRE> +<<I>float</I>>_to_<<I>int</I>>_r_<<I>round</I>> +<<I>float</I>>_to_<<I>int</I>>_rx_<<I>round</I>> +</PRE> +</BLOCKQUOTE> +The <CODE><<I>round</I>></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 in the result format. +In such a circumstance: +<UL> + +<LI> +<P> +If the result type is an unsigned integer, TestFloat normally expects the +result of the operation to be the type’s largest integer value. +In the case that the input is a negative number (not a NaN), a zero result may +also be accepted. +</P> + +<LI> +<P> +If the result type is a signed integer and the input is a number (not a NaN), +TestFloat expects the result to be the largest-magnitude integer with the same +sign as the input. +When a NaN is converted to a signed integer type, TestFloat allows either the +largest postive or largest-magnitude negative integer to be returned. +</P> + +</UL> +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: +<BLOCKQUOTE> +<PRE> +f16_add f16_sub f16_mul f16_div f16_sqrt +f32_add f32_sub f32_mul f32_div f32_sqrt +f64_add f64_sub f64_mul f64_div f64_sqrt +extF80_add extF80_sub extF80_mul extF80_div extF80_sqrt +f128_add f128_sub f128_mul f128_div f128_sqrt +</PRE> +</BLOCKQUOTE> +The double-extended-precision (<CODE>extF80</CODE>) operations can be rounded +to reduced precision under rounding precision control. +</P> + +<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: +<BLOCKQUOTE> +<PRE> +f16_mulAdd +f32_mulAdd +f64_mulAdd +f128_mulAdd +</PRE> +</BLOCKQUOTE> +</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 quiet NaN. +</P> + +<H3>6.4. Remainder Operations</H3> + +<P> +For each format, TestFloat can test the IEEE Standard’s remainder +operation. +These operations are: +<BLOCKQUOTE> +<PRE> +f16_rem +f32_rem +f64_rem +extF80_rem +f128_rem +</PRE> +</BLOCKQUOTE> +The remainder operations are always exact and so require no rounding. +</P> + +<H3>6.5. Round-to-Integer Operations</H3> + +<P> +For each format, TestFloat can test the IEEE Standard’s round-to-integer +operation. +For most TestFloat programs, these operations are: +<BLOCKQUOTE> +<PRE> +f16_roundToInt +f32_roundToInt +f64_roundToInt +extF80_roundToInt +f128_roundToInt +</PRE> +</BLOCKQUOTE> +</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: +<BLOCKQUOTE> +<PRE> +<<I>float</I>>_roundToInt_r_<<I>round</I>> +<<I>float</I>>_roundToInt_x +</PRE> +</BLOCKQUOTE> +For the ‘<CODE>_r_</CODE>’ versions, the <I>inexact</I> exception +is never raised, and the <CODE><<I>round</I>></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 particular +specification for the round-to-integer operations. +</P> + +<H3>6.6. Comparison Operations</H3> + +<P> +The following floating-point comparison operations can be tested: +<BLOCKQUOTE> +<PRE> +f16_eq f16_le f16_lt +f32_eq f32_le f32_lt +f64_eq f64_le f64_lt +extF80_eq extF80_le extF80_lt +f128_eq f128_le f128_lt +</PRE> +</BLOCKQUOTE> +The abbreviation <CODE>eq</CODE> stands for “equal” (=), +<CODE>le</CODE> stands for “less than or equal” (≤), and +<CODE>lt</CODE> stands for “less than” (<). +</P> + +<P> +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: +<BLOCKQUOTE> +<PRE> +f16_eq_signaling f16_le_quiet f16_lt_quiet +f32_eq_signaling f32_le_quiet f32_lt_quiet +f64_eq_signaling f64_le_quiet f64_lt_quiet +extF80_eq_signaling extF80_le_quiet extF80_lt_quiet +f128_eq_signaling f128_le_quiet f128_lt_quiet +</PRE> +</BLOCKQUOTE> +The <CODE>signaling</CODE> equality comparisons are identical to the standard +operations except that the <I>invalid</I> exception should be raised for any +NaN input. +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 emulation 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: +<BLOCKQUOTE> +<PRE> +<<I>inputs</I>> => <<I>observed-output</I>> expected: <<I>expected-output</I>> +</PRE> +</BLOCKQUOTE> +The <CODE><<I>inputs</I>></CODE> are the inputs to the operation. +Each output (observed or 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 +<BLOCKQUOTE> +<PRE> +-00.7FFF00 -7F.000100 => +01.000000 ...ux expected: +01.000000 ....x ++81.000004 +00.1FFFFF => +01.000000 ...ux expected: +01.000000 ....x +</PRE> +</BLOCKQUOTE> +In the first line, the inputs are <CODE>-00.7FFF00</CODE> and +<CODE>-7F.000100</CODE>, and the observed result is <CODE>+01.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>-00.7FFF00</CODE> composed of a sign character +<NOBR>(<CODE>+</CODE>/<CODE>-</CODE>)</NOBR>, 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 ten data types that may be +represented. +Five are floating-point types: <NOBR>16-bit</NOBR> half-precision, +<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> +(false) or a <CODE>1</CODE> (true). +A <NOBR>32-bit</NOBR> integer is 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 decomposed into their sign, encoded exponent, +and encoded significand. +First is the sign character <NOBR>(<CODE>+</CODE> or <CODE>-</CODE>),</NOBR> +followed by the encoded exponent in hexadecimal, then a period +(<CODE>.</CODE>), and lastly the encoded significand in hexadecimal. +</P> + +<P> +For <NOBR>16-bit</NOBR> half-precision, notable values include: +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR><TD><CODE>+00.000 </CODE></TD><TD>+0</TD></TR> +<TR><TD><CODE>+0F.000</CODE></TD><TD> 1</TD></TR> +<TR><TD><CODE>+10.000</CODE></TD><TD> 2</TD></TR> +<TR><TD><CODE>+1E.3FF</CODE></TD><TD>maximum finite value</TD></TR> +<TR><TD><CODE>+1F.000</CODE></TD><TD>+infinity</TD></TR> +<TR><TD> </TD></TR> +<TR><TD><CODE>-00.000</CODE></TD><TD>−0</TD></TR> +<TR><TD><CODE>-0F.000</CODE></TD><TD>−1</TD></TR> +<TR><TD><CODE>-10.000</CODE></TD><TD>−2</TD></TR> +<TR> + <TD><CODE>-1E.3FF</CODE></TD> + <TD>minimum finite value (largest magnitude, but negative)</TD> +</TR> +<TR><TD><CODE>-1F.000</CODE></TD><TD>−infinity</TD></TR> +</TABLE> +</BLOCKQUOTE> +Certain categories are easily distinguished (assuming the <CODE>x</CODE>s are +not all 0): +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>+00.xxx </CODE></TD> + <TD>positive subnormal numbers</TD> +</TR> +<TR><TD><CODE>+1F.xxx</CODE></TD><TD>positive NaNs</TD></TR> +<TR><TD><CODE>-00.xxx</CODE></TD><TD>negative subnormal numbers</TD></TR> +<TR><TD><CODE>-1F.xxx</CODE></TD><TD>negative NaNs</TD></TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +Likewise for other formats: +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR><TD>32-bit single</TD><TD>64-bit double</TD><TD>128-bit quadruple</TD></TR> +<TR><TD> </TD></TR> +<TR> +<TD><CODE>+00.000000 </CODE></TD> +<TD><CODE>+000.0000000000000 </CODE></TD> +<TD><CODE>+0000.0000000000000000000000000000 </CODE></TD> +<TD>+0</TD> +</TR> +<TR> +<TD><CODE>+7F.000000</CODE></TD> +<TD><CODE>+3FF.0000000000000</CODE></TD> +<TD><CODE>+3FFF.0000000000000000000000000000</CODE></TD> +<TD> 1</TD> +</TR> +<TR> +<TD><CODE>+80.000000</CODE></TD> +<TD><CODE>+400.0000000000000</CODE></TD> +<TD><CODE>+4000.0000000000000000000000000000</CODE></TD> +<TD> 2</TD> +</TR> +<TR> +<TD><CODE>+FE.7FFFFF</CODE></TD> +<TD><CODE>+7FE.FFFFFFFFFFFFF</CODE></TD> +<TD><CODE>+7FFE.FFFFFFFFFFFFFFFFFFFFFFFFFFFF</CODE></TD> +<TD>maximum finite value</TD> +</TR> +<TR> +<TD><CODE>+FF.000000</CODE></TD> +<TD><CODE>+7FF.0000000000000</CODE></TD> +<TD><CODE>+7FFF.0000000000000000000000000000</CODE></TD> +<TD>+infinity</TD> +</TR> +<TR><TD> </TD></TR> +<TR> +<TD><CODE>-00.000000 </CODE></TD> +<TD><CODE>-000.0000000000000 </CODE></TD> +<TD><CODE>-0000.0000000000000000000000000000 </CODE></TD> +<TD>−0</TD> +</TR> +<TR> +<TD><CODE>-7F.000000</CODE></TD> +<TD><CODE>-3FF.0000000000000</CODE></TD> +<TD><CODE>-3FFF.0000000000000000000000000000</CODE></TD> +<TD>−1</TD> +</TR> +<TR> +<TD><CODE>-80.000000</CODE></TD> +<TD><CODE>-400.0000000000000</CODE></TD> +<TD><CODE>-4000.0000000000000000000000000000</CODE></TD> +<TD>−2</TD> +</TR> +<TR> +<TD><CODE>-FE.7FFFFF</CODE></TD> +<TD><CODE>-7FE.FFFFFFFFFFFFF</CODE></TD> +<TD><CODE>-7FFE.FFFFFFFFFFFFFFFFFFFFFFFFFFFF</CODE></TD> +<TD>minimum finite value</TD> +</TR> +<TR> +<TD><CODE>-FF.000000</CODE></TD> +<TD><CODE>-7FF.0000000000000</CODE></TD> +<TD><CODE>-7FFF.0000000000000000000000000000</CODE></TD> +<TD>−infinity</TD> +</TR> +<TR><TD> </TD></TR> +<TR> +<TD><CODE>+00.xxxxxx</CODE></TD> +<TD><CODE>+000.xxxxxxxxxxxxx</CODE></TD> +<TD><CODE>+0000.xxxxxxxxxxxxxxxxxxxxxxxxxxxx</CODE></TD> +<TD>positive subnormals</TD> +</TR> +<TR> +<TD><CODE>+FF.xxxxxx</CODE></TD> +<TD><CODE>+7FF.xxxxxxxxxxxxx</CODE></TD> +<TD><CODE>+7FFF.xxxxxxxxxxxxxxxxxxxxxxxxxxxx</CODE></TD> +<TD>positive NaNs</TD> +</TR> +<TR> +<TD><CODE>-00.xxxxxx</CODE></TD> +<TD><CODE>-000.xxxxxxxxxxxxx</CODE></TD> +<TD><CODE>-0000.xxxxxxxxxxxxxxxxxxxxxxxxxxxx</CODE></TD> +<TD>negative subnormals</TD> +</TR> +<TR> +<TD><CODE>-FF.xxxxxx</CODE></TD> +<TD><CODE>-7FF.xxxxxxxxxxxxx</CODE></TD> +<TD><CODE>-7FFF.xxxxxxxxxxxxxxxxxxxxxxxxxxxx</CODE></TD> +<TD>negative NaNs</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +The <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 canonically 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): +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>+0000.0000000000000000 </CODE></TD> + <TD>+0</TD> +</TR> +<TR><TD><CODE>+3FFF.8000000000000000</CODE></TD><TD> 1</TD></TR> +<TR><TD><CODE>+4000.8000000000000000</CODE></TD><TD> 2</TD></TR> +<TR> + <TD><CODE>+7FFE.FFFFFFFFFFFFFFFF</CODE></TD> + <TD>maximum finite value</TD> +</TR> +<TR><TD><CODE>+7FFF.8000000000000000</CODE></TD><TD>+infinity</TD></TR> +<TR><TD> </TD></TR> +<TR><TD><CODE>-0000.0000000000000000</CODE></TD><TD>−0</TD></TR> +<TR><TD><CODE>-3FFF.8000000000000000</CODE></TD><TD>−1</TD></TR> +<TR><TD><CODE>-4000.8000000000000000</CODE></TD><TD>−2</TD></TR> +<TR> + <TD><CODE>-7FFE.FFFFFFFFFFFFFFFF</CODE></TD> + <TD>minimum finite value</TD> +</TR> +<TR><TD><CODE>-7FFF.8000000000000000</CODE></TD><TD>−infinity</TD></TR> +</TABLE> +</BLOCKQUOTE> +</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: +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD><CODE>v </CODE></TD> + <TD><I>invalid</I> exception</TD> +</TR> +<TR> + <TD><CODE>i</CODE></TD> + <TD><I>infinite</I> exception (“divide by zero”)</TD> +</TR> +<TR><TD><CODE>o</CODE></TD><TD><I>overflow</I> exception</TD></TR> +<TR><TD><CODE>u</CODE></TD><TD><I>underflow</I> exception</TD></TR> +<TR><TD><CODE>x</CODE></TD><TD><I>inexact</I> exception</TD></TR> +</TABLE> +</BLOCKQUOTE> +For example, the notation <CODE>...ux</CODE> indicates that the +<I>underflow</I> and <I>inexact</I> exception flags were set and that the other +three flags (<I>invalid</I>, <I>infinite</I>, and <I>overflow</I>) were not +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 or zero, as detailed earlier in +<NOBR>section 6.1</NOBR>, <I>Conversion Operations</I>. +If option <CODE>-checkInvInts</CODE> is selected with programs +<CODE>testfloat_ver</CODE> and <CODE>testfloat</CODE>, integer results of +invalid operations are checked for an exact match. +In order for this option to be sensible, TestFloat must have been compiled so +that its internal floating-point implementation (SoftFloat) generates the +proper integer results for the system being tested. +</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"><NOBR><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></NOBR></A>. +</P> + + +</BODY> + diff --git a/src/libs/softfloat-3e/testfloat/doc/TestFloat-history.html b/src/libs/softfloat-3e/testfloat/doc/TestFloat-history.html new file mode 100644 index 00000000..1c247de0 --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/TestFloat-history.html @@ -0,0 +1,272 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat History</TITLE> +</HEAD> + +<BODY> + +<H1>History of Berkeley TestFloat, to Release 3e</H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</P> + + +<P> +Releases of Berkeley TestFloat normally 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 3e (2018 January)</H3> + +<UL> + +<LI> +Fixed a problem with the all-in-one <CODE>testfloat</CODE> program whereby +function set <CODE>-all1</CODE> incorrectly also tested the three-operand fused +multiply-add operations. + +<LI> +Modified the expected behavior of rounding mode <CODE>odd</CODE> (jamming) when +rounding to an integer value (either conversion to an integer format or a +‘<CODE>roundToInt</CODE>’ function). +Previously, for those cases only, rounding mode <CODE>odd</CODE> was expected +to act the same as rounding to minimum magnitude. +Now, when rounding to an integer value, the nearest odd integer is expected, +consistent with the round-to-odd result of other operations. + +<LI> +Added options <CODE>-checkInvInts</CODE> and <CODE>-checkAll</CODE> to programs +<CODE>testfloat_ver</CODE> and <CODE>testfloat</CODE>. + +<LI> +Improved the checking of integer results of invalid operations. + +</UL> + + +<H3>Release 3d (2017 August)</H3> + +<UL> + +<LI> +When the all-in-one <CODE>testfloat</CODE> program is compiled to test the C +language’s arithmetic, added the ability to test library functions +<CODE>sqrtf</CODE>, <CODE>sqrtl</CODE>, <CODE>fmaf</CODE>, <CODE>fma</CODE>, +and <CODE>fmal</CODE>, which were added to the <NOBR>C Standard</NOBR> in 1999. + +</UL> + + +<H3>Release 3c (2017 February)</H3> + +<UL> + +<LI> +Added support for testing rounding mode <CODE>odd</CODE> (jamming). + +<LI> +Made support for testing <NOBR>64-bit</NOBR> double-precistion floating-point +be subject to macro <CODE>FLOAT64</CODE> (akin to macros <CODE>FLOAT16</CODE>, +<CODE>EXTFLOAT80</CODE>, and <CODE>FLOAT128</CODE> from before). + +<LI> +Fixed some bugs that caused compilation to fail with certain combinations of +option macro settings. + +<LI> +Corrected the types of two internal variables to be <CODE>sig_atomic_t</CODE> +instead of <CODE>bool</CODE>. + +<LI> +Improved the formatting of some error reports (concerning where lines are +broken when they exceed 79 characters in length). + +</UL> + + +<H3>Release 3b (2016 July)</H3> + +<UL> + +<LI> +Added the ability to test the common <NOBR>16-bit</NOBR> +“half-precision” floating-point format. + +<LI> +Added a <CODE>-seed</CODE> option to programs <CODE>testfloat_gen</CODE>, +<CODE>testfloat</CODE>, and <CODE>testsoftfloat</CODE> for setting the seed for +the pseudo-random number generator used to generate test cases. + +<LI> +Where a specific choice is needed for how tininess is detected on underflow, +changed the default to be the detection of tininess after rounding +(<CODE>-tininessafter</CODE>) instead of before rounding +(<CODE>-tininessbefore</CODE>). + +<LI> +Modified the format of reported discrepancies to show the signs of +floating-point values using <CODE>+</CODE> and <CODE>-</CODE> characters. + +<LI> +Documented the use of the <CODE>INLINE</CODE> macro, and fixed the sources for +the case that function inlining is not supported by the C compiler. + +<LI> +Documented the possible need to define macro <CODE>THREAD_LOCAL</CODE> to match +how the SoftFloat library was built. + +<LI> +Modified the provided Makefiles to allow some options to be overridden from the +<CODE>make</CODE> command. + +</UL> + + +<H3>Release 3a (2015 October)</H3> + +<UL> + +<LI> +Replaced the license text supplied by the University of California, Berkeley, +and fixed some minor build problems. + +</UL> + + +<H3>Release 3 (2015 February)</H3> + +<UL> + +<LI> +Complete rewrite, funded by the University of California, Berkeley, and +consequently having a different use license than earlier releases. +Visible changes included different names for testable functions and command +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 (2015 January)</H3> + +<UL> + +<LI> +Fixed mistakes affecting some <NOBR>64-bit</NOBR> processors. + +<LI> +Made minor updates to the documentation, including improved wording for the +legal restrictions on using TestFloat releases <NOBR>through 2c</NOBR> (not +applicable to <NOBR>Release 3</NOBR> or later). + +</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/src/libs/softfloat-3e/testfloat/doc/TestFloat-source.html b/src/libs/softfloat-3e/testfloat/doc/TestFloat-source.html new file mode 100644 index 00000000..24fb5946 --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/TestFloat-source.html @@ -0,0 +1,639 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat Source Documentation</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: Source Documentation</H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</P> + + +<H2>Contents</H2> + +<BLOCKQUOTE> +<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> +<COL WIDTH=25> +<COL WIDTH=*> +<TR><TD COLSPAN=2>1. Introduction</TD></TR> +<TR><TD COLSPAN=2>2. Limitations</TD></TR> +<TR><TD COLSPAN=2>3. Acknowledgments and License</TD></TR> +<TR><TD COLSPAN=2>4. TestFloat Package Directory Structure</TD></TR> +<TR><TD COLSPAN=2>5. Dependence on Berkeley SoftFloat</TD></TR> +<TR><TD COLSPAN=2>6. Issues for Porting TestFloat to a New Target</TD></TR> +<TR> + <TD></TD> + <TD>6.1. Standard Headers <CODE><stdbool.h></CODE> and + <CODE><stdint.h></CODE></TD> +</TR> +<TR><TD></TD><TD>6.2. Standard Header <CODE><fenv.h></CODE></TD></TR> +<TR><TD></TD><TD>6.3. Macros for Build Options</TD></TR> +<TR><TD></TD><TD>6.4. Specializing the <CODE>testfloat</CODE> Program</TD></TR> +<TR><TD></TD><TD>6.5. Improving the Random Number Functions</TD></TR> +<TR><TD COLSPAN=2>7. Contact Information</TD></TR> +</TABLE> +</BLOCKQUOTE> + + +<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"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></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 was a complete rewrite relative to +<NOBR>Release 2c</NOBR> or earlier. +The current version of TestFloat is <NOBR>Release 3e</NOBR>. +</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"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></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 starting 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 was a completely new implementation +supplanting earlier releases. +The project to create <NOBR>Release 3</NOBR> (now <NOBR>through 3e</NOBR>) was +done in the employ of the University of California, Berkeley, within the +Department of Electrical Engineering and Computer Sciences, first for the +Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab. +The work was officially overseen by Prof. Krste Asanovic, with funding provided +by these sources: +<BLOCKQUOTE> +<TABLE> +<COL> +<COL WIDTH=10> +<COL> +<TR> +<TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD> +<TD></TD> +<TD> +Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery +(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +</TD> +</TR> +<TR> +<TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD> +<TD></TD> +<TD> +DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from +ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, +Oracle, and Samsung. +</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +The following applies to the whole of TestFloat <NOBR>Release 3e</NOBR> as well +as to each source file individually. +</P> + +<P> +Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the +University of California. +All rights reserved. +</P> + +<P> +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +<OL> + +<LI> +<P> +Redistributions of source code must retain the above copyright notice, this +list of conditions, and the following disclaimer. +</P> + +<LI> +<P> +Redistributions in binary form must reproduce the above copyright notice, this +list of conditions, and the following disclaimer in the documentation and/or +other materials provided with the distribution. +</P> + +<LI> +<P> +Neither the name of the University nor the names of its contributors may be +used to endorse or promote products derived from this software without specific +prior written permission. +</P> + +</OL> +</P> + +<P> +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS”, +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE +DISCLAIMED. +IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</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: +<BLOCKQUOTE> +<PRE> +doc +source + subj-C +build + template + Linux-386-GCC + Linux-386-SSE2-GCC + Linux-x86_64-GCC + Linux-ARM-VFPv2-GCC + Win32-MinGW + Win32-SSE2-MinGW + Win64-MinGW-w64 +</PRE> +</BLOCKQUOTE> +The majority of the TestFloat sources are provided in the <CODE>source</CODE> +directory. +The <NOBR><CODE>subj-C</CODE></NOBR> subdirectory contains the sources that +configure the all-in-one <CODE>testfloat</CODE> program to test the C +compiler’s implementation of the standard C types <CODE>float</CODE>, +<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-<<I>target</I>></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><<I>execution-environment</I>>-<<I>compiler</I>></CODE></NOBR>. +For the example targets, +<NOBR><CODE><<I>execution-environment</I>></CODE></NOBR> is +<NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-386-SSE2</CODE></NOBR>, +<NOBR><CODE>Linux-x86_64</CODE></NOBR>, +<NOBR><CODE>Linux-ARM-VFPv2</CODE></NOBR>, <CODE>Win32</CODE>, +<NOBR><CODE>Win32-SSE2</CODE></NOBR>, or <CODE>Win64</CODE>, and +<NOBR><CODE><<I>compiler</I>></CODE></NOBR> is <CODE>GCC</CODE>, +<CODE>MinGW</CODE>, or <NOBR><CODE>MinGW-w64</CODE></NOBR>. +</P> + +<P> +All of the supplied target directories are merely examples that may or may not +be correct for compiling on any particular system. +There are currently no plans to include and maintain in the TestFloat package +the build files needed for a great many users’ compilation environments, +which can span a huge range of operating systems, compilers, and other tools. +</P> + +<P> +As supplied, each target directory contains two files: +<BLOCKQUOTE> +<PRE> +Makefile +platform.h +</PRE> +</BLOCKQUOTE> +The provided <CODE>Makefile</CODE> is written for GNU <CODE>make</CODE>. +A build of TestFloat for the specific target is begun by executing the +<CODE>make</CODE> command with the target directory as the current directory. +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"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></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> or <CODE>libsoftfloat.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>: +<BLOCKQUOTE> +<PRE> +bool +true +false +</PRE> +</BLOCKQUOTE> +and on these names from <CODE><stdint.h></CODE>: +<BLOCKQUOTE> +<PRE> +uint16_t +uint32_t +uint64_t +int32_t +int64_t +UINT64_C +INT64_C +uint_least8_t +uint_fast8_t +uint_fast16_t +uint_fast32_t +uint_fast64_t +int_fast8_t +int_fast16_t +int_fast32_t +int_fast64_t +</PRE> +</BLOCKQUOTE> +</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 several 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>INLINE</CODE> +<DD> +Can be defined to a sequence of tokens used to indicate that a C function +should be inlined. +If the compiler does not support the inlining of functions, this macro must not +be defined. +For compilers that conform to the C Standard’s rules for inline +functions, this macro can be defined as the single keyword <CODE>inline</CODE>. +For other compilers that follow a convention pre-dating the standardization of +<CODE>inline</CODE>, this macro may need to be defined to <CODE>extern</CODE> +<CODE>inline</CODE>. +<DT><CODE>THREAD_LOCAL</CODE> +<DD> +Can be defined to a sequence of tokens that, when appearing at the start of a +variable declaration, indicates to the C compiler that the variable is +<I>per-thread</I>, meaning that each execution thread gets its own separate +instance of the variable. +This macro is used in the supplied version of Berkeley SoftFloat’s header +<CODE>softfloat.h</CODE>, in the declarations of variables +<CODE>softfloat_roundingMode</CODE>, <CODE>softfloat_detectTininess</CODE>, +<CODE>extF80_roundingPrecision</CODE>, and +<CODE>softfloat_exceptionFlags</CODE>. +To use the supplied, unmodified header <CODE>softfloat.h</CODE>, this macro +must be defined (or not defined) the same as when the SoftFloat library was +built. +</DL> +<DL> +<DT><CODE>FLOAT16</CODE> +<DD> +Must be defined if the TestFloat programs are to support the +<NOBR>16-bit</NOBR> half-precision floating-point format. +<DT><CODE>FLOAT64</CODE> +<DD> +Must be defined if the TestFloat programs are to support the +<NOBR>64-bit</NOBR> double-precision floating-point format. +<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. +<DT><CODE>FLOAT_ROUND_ODD</CODE> +<DD> +Must be defined if the TestFloat programs are to support rounding to odd +(jamming). +To be useful, this option also requires that the Berkeley SoftFloat library was +compiled with macro <CODE>SOFTFLOAT_ROUND_ODD</CODE> defined. +</DL> +</BLOCKQUOTE> +Following the usual custom <NOBR>for C</NOBR>, for all the macros except +<CODE>INLINE</CODE> and <CODE>THREAD_LOCAL</CODE>, 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 macros <CODE>LITTLEENDIAN</CODE>, +<CODE>INLINE</CODE>, and <CODE>THREAD_LOCAL</CODE> be made in a build +target’s <CODE>platform.h</CODE> header file, because these macros are +expected to be determined inflexibly by the target machine and compiler. +The other five macros select build options, 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. +For other rounding modes, 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). +<DT><CODE>SUBJFLOAT_ROUND_ODD</CODE> +<DD> +Indicates that the subject floating-point supports rounding mode +<CODE>odd</CODE> (jamming). +</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: +<BLOCKQUOTE> +<PRE> +subjfloat_config.h +subjfloat.c +</PRE> +</BLOCKQUOTE> +For the default target of testing C’s floating-point, these files are +contained in directory <NOBR><CODE>source/subj-C</CODE></NOBR> as discussed +earlier. +For a different subject floating-point, it is recommended that appropriate +versions of <CODE>subjfloat_config.h</CODE> and <CODE>subjfloat.c</CODE> be +stored in a sibling <NOBR><CODE>subj-<<I>target</I>></CODE></NOBR> +directory, where <CODE><<I>target</I>></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, macros <CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE> and +<CODE>SUBJFLOAT_ROUND_ODD</CODE> always determine whether the +<CODE>testfloat</CODE> program attempts to test rounding modes +<CODE>near_maxMag</CODE> and <CODE>odd</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 +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"><NOBR><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></NOBR></A>. +</P> + + +</BODY> + diff --git a/src/libs/softfloat-3e/testfloat/doc/testfloat.html b/src/libs/softfloat-3e/testfloat/doc/testfloat.html new file mode 100644 index 00000000..f9404e04 --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/testfloat.html @@ -0,0 +1,286 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: <CODE>testfloat</CODE></H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</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 +five rounding modes defined by the IEEE Floating-Point Standard, one after the +other, plus possibly a sixth mode, <I>round to odd</I> (depending on the +options selected when <CODE>testfloat</CODE> was compiled). +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: +<BLOCKQUOTE> +<PRE> +testfloat [<<I>option</I>>...] <<I>function</I>> +</PRE> +</BLOCKQUOTE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, +<CODE><<I>option</I>></CODE> is a supported option, and +<CODE><<I>function</I>></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. +An operation is testable by <CODE>testfloat</CODE> if the program knows some +way to invoke the operation. +</P> + +<H3><CODE>-seed <<I>num</I>></CODE></H3> + +<P> +The <CODE>-seed</CODE> option sets the seed for the pseudo-random number +generator used for generating test cases. +The argument to <CODE>-seed</CODE> is a nonnegative integer. +Executing the same compiled <CODE>testfloat</CODE> program with the same +arguments (including the same pseudo-random number seed) should always perform +the same sequence of tests, whereas changing the pseudo-random number seed +should result in a different sequence of tests. +The default seed number <NOBR>is 1</NOBR>. +</P> + +<H3><CODE>-level <<I>num</I>></CODE></H3> + +<P> +The <CODE>-level</CODE> option sets the level of testing. +The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>. +The default is <NOBR>level 1</NOBR>. +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 <<I>num</I>></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 +(Berkeley SoftFloat) generates the proper NaN results for the system being +tested. +</P> + +<H3><CODE>-checkInvInts</CODE></H3> + +<P> +The <CODE>-checkInvInts</CODE> option causes <CODE>testfloat</CODE> to verify +the bitwise correctness of integer results of invalid operations. +In order for this option to be sensible, <CODE>testfloat</CODE> must have been +compiled so that its internal reference implementation of floating-point +(Berkeley SoftFloat) generates the proper integer results for the system being +tested. +</P> + +<H3><CODE>-checkAll</CODE></H3> + +<P> +Enables both <CODE>-checkNaNs</CODE> and <CODE>-checkInvInts</CODE>. +</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 supported at all if no +double-extended-precision operations are testable. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax, -rodd</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), <CODE>-rmax</CODE> forces rounding to maximum (up, +toward positive infinity), and <CODE>-rodd</CODE>, if supported, forces +rounding to odd. +These options are ignored for operations that are exact and thus do not round, +or that have the rounding mode included in the function name (such as +<CODE>f32_to_i32_r_near_maxMag</CODE>). +</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 or six +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> is all one-operand operations, while +<CODE>-all2</CODE> is all two-operand operations. +A function set is used in place of an operation name in the +<CODE>testfloat</CODE> command line, such as +<BLOCKQUOTE> +<PRE> +testfloat [<<I>option</I>>...] -all1 +</PRE> +</BLOCKQUOTE> +</P> + + +</BODY> + diff --git a/src/libs/softfloat-3e/testfloat/doc/testfloat_gen.html b/src/libs/softfloat-3e/testfloat/doc/testfloat_gen.html new file mode 100644 index 00000000..5190567c --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/testfloat_gen.html @@ -0,0 +1,367 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat_gen</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: <CODE>testfloat_gen</CODE></H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>testfloat_gen</CODE> program generates test cases for testing that an +implementation of floating-point arithmetic conforms to the IEEE Standard for +Binary Floating-Point Arithmetic. +<CODE>testfloat_gen</CODE> is part of the Berkeley TestFloat package, a small +collection of programs for performing such tests. +For general information about TestFloat, see file +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +A single execution of <CODE>testfloat_gen</CODE> generates test cases for only +a single floating-point operation and associated options. +The <CODE>testfloat_gen</CODE> program must be repeatedly executed to generate +test cases for each operation to be tested. +</P> + +<P> +The <CODE>testfloat_gen</CODE> program writes the test cases it generates to +standard output. +This output can either be captured in a file through redirection, or be piped +to another program that exercises a floating-point operation using the test +cases as they are supplied. +Depending on use, the total output from <CODE>testfloat_gen</CODE> can be +large, so piping to another program may be the best choice to avoid using +inordinate file space. +The format of <CODE>testfloat_gen</CODE>’s output is raw hexadecimal +text, described in the section below titled <I>Output Format</I>. +</P> + + +<H2>Command Syntax</H2> + +<P> +The <CODE>testfloat_gen</CODE> program is executed as a command in one of these +forms: +<BLOCKQUOTE> +<PRE> +testfloat_gen [<<I>option</I>>...] <<I>type</I>> +testfloat_gen [<<I>option</I>>...] <<I>function</I>> +</PRE> +</BLOCKQUOTE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, and +<CODE><<I>option</I>></CODE> is a supported option, documented below. +A <CODE>testfloat_gen</CODE> command expects either a +<CODE><<I>type</I>></CODE> specifying the type and number of outputs or a +<CODE><<I>function</I>></CODE> naming a floating-point operation. +If <CODE>testfloat_gen</CODE> is executed without any arguments, a summary of +usage is written. +</P> + +<P> +A <CODE><<I>type</I>></CODE> can be one of the following: +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> +<TD><CODE>ui32</CODE></TD> +<TD>unsigned <NOBR>32-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>ui64</CODE></TD> +<TD>unsigned <NOBR>64-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>i32</CODE></TD> +<TD>signed <NOBR>32-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>i64</CODE></TD> +<TD>signed <NOBR>64-bit</NOBR> integers</TD> +</TR> +<TR> +<TD><CODE>f16 [<<I>num</I>>]</CODE></TD> +<TD>one or more <NOBR>16-bit</NOBR> half-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>f32 [<<I>num</I>>]</CODE></TD> +<TD>one or more <NOBR>32-bit</NOBR> single-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>f64 [<<I>num</I>>]</CODE></TD> +<TD>one or more <NOBR>64-bit</NOBR> double-precision floating-point values</TD> +</TR> +<TR> +<TD><CODE>extF80 [<<I>num</I>>] </CODE></TD> +<TD>one or more <NOBR>80-bit</NOBR> double-extended-precision floating-point +values</TD> +</TR> +<TR> +<TD><CODE>f128 [<<I>num</I>>]</CODE></TD> +<TD>one or more <NOBR>128-bit</NOBR> quadruple-precision floating-point +values</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +Optional <CODE><<I>num</I>></CODE> is one of 1, 2, <NOBR>or 3</NOBR>. +If a <CODE><<I>type</I>></CODE> is given without +<CODE><<I>num</I>></CODE> (such as <CODE>ui32</CODE> or +<CODE>f64</CODE>), <CODE>testfloat_gen</CODE> outputs a list of values of the +specified type, one value per line, appropriate for testing a floating-point +operation with exactly one operand of the given type. +If a floating-point type and number are given (such as +<NOBR><CODE>f32</CODE> <CODE>2</CODE></NOBR> or +<NOBR><CODE>extF80</CODE> <CODE>1</CODE></NOBR>), <CODE>testfloat_gen</CODE> +outputs the specified number of values per line, appropriate for testing a +floating-point operation with that number of operands. +Although the exact operation being tested is not specified, the test cases +output by <CODE>testfloat_gen</CODE> cover all standard floating-point +operations, to the degree explained in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +</P> + +<P> +If a <CODE><<I>function</I>></CODE> operation name is given, then each +line of output from <CODE>testfloat_gen</CODE> contains not only the operands +for that operation (as would be generated by an appropriate +<CODE><<I>type</I>></CODE> argument) but also the expected results as +determined by <CODE>testfloat_gen</CODE>’s internal floating-point +emulation (Berkeley SoftFloat). +The available operation names are listed in +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>. +In all cases, floating-point operations have two results: +first, a value, which may be floating-point, integer, or Boolean, and, second, +the floating-point exception flags raised by the operation. +If the output from a tested floating-point operation does not match the +expected output specified by <CODE>testfloat_gen</CODE>, this may or may not +indicate an error in the floating-point operation. +For further explanation, see +<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>, +especially the section titled <I>Variations Allowed by the IEEE Floating-Point +Standard</I>. +</P> + + +<H2>Options</H2> + +<P> +The <CODE>testfloat_gen</CODE> program accepts several command options. +If mutually contradictory options are given, the last one has priority. +</P> + +<H3><CODE>-help</CODE></H3> + +<P> +The <CODE>-help</CODE> option causes a summary of program usage to be written, +after which the program exits. +</P> + +<H3><CODE>-prefix <<I>text</I>></CODE></H3> + +<P> +The <CODE>-prefix</CODE> option causes <CODE>testfloat_gen</CODE> to write the +supplied text argument verbatim as the first line of output before any test +cases. +This can be used, for example, to indicate to a downstream program what kind of +test to perform for the test cases that follow. +</P> + +<H3><CODE>-seed <<I>num</I>></CODE></H3> + +<P> +The <CODE>-seed</CODE> option sets the seed for the pseudo-random number +generator used for generating test cases. +The argument to <CODE>-seed</CODE> is a nonnegative integer. +Executing the same <CODE>testfloat_gen</CODE> program with the same arguments +(including the same pseudo-random number seed) should always generate the same +sequence of test cases, whereas changing the pseudo-random number seed should +result in a different sequence of test cases. +The default seed number <NOBR>is 1</NOBR>. +</P> + +<H3><CODE>-level <<I>num</I>></CODE></H3> + +<P> +The <CODE>-level</CODE> option sets the level of testing. +The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>. +The default is <NOBR>level 1</NOBR>. +<NOBR>Level 2</NOBR> causes many more test cases to be generated, with better +coverage, than <NOBR>level 1</NOBR>. +</P> + +<H3><CODE>-n <<I>num</I>></CODE></H3> + +<P> +Option <CODE>-n</CODE> specifies the number of test cases to generate. +For each <CODE><<I>type</I>></CODE> or +<CODE><<I>function</I>></CODE> and each testing level (set by +<CODE>-level</CODE>), there is a minimum value that <CODE>testfloat_gen</CODE> +will accept for <CODE><<I>num</I>></CODE>. +If no <CODE>-n</CODE> option is given, the number of test cases generated by +<CODE>testfloat_gen</CODE> equals the minimum value acceptable for the +<CODE>-n</CODE> argument. +Option <CODE>-n</CODE> cannot be used to reduce this number, but can increase +it, without changing the testing level. +</P> + +<H3><CODE>-forever</CODE></H3> + +<P> +The <CODE>-forever</CODE> option causes test cases to be generated +indefinitely, without limit (until the program is terminated by some external +cause). +The testing level is set to 2 by this option. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +When a <CODE><<I>function</I>></CODE> is specified that is an +<NOBR>80-bit</NOBR> double-extended-precision operation affected by rounding +precision control, the <CODE>-precision32</CODE> option sets the rounding +precision to <NOBR>32 bits</NOBR>, equivalent to <NOBR>32-bit</NOBR> +single-precision. +Likewise, <CODE>-precision64</CODE> sets the rounding precision to +<NOBR>64 bits</NOBR>, equivalent to <NOBR>64-bit</NOBR> double-precision, and +<CODE>-precision80</CODE> sets the rounding precision to the full +<NOBR>80 bits</NOBR> of the double-extended-precision format. +All these options are ignored for operations not affected by rounding precision +control. +When rounding precision is applicable but not specified, the default is the +full <NOBR>80 bits</NOBR>, same as <CODE>-precision80</CODE>. +</P> + +<H3><CODE>-rnear_even, -rnear_maxMag, -rminMag, -rmin, -rmax, -rodd</CODE></H3> + +<P> +When a <CODE><<I>function</I>></CODE> is specified that requires +rounding, the <CODE>-rnear_even</CODE> option sets the rounding mode to +nearest/even; +<CODE>-rnear_maxMag</CODE> sets rounding to nearest/maximum magnitude +(nearest-away); +<CODE>-rminMag</CODE> sets rounding to minimum magnitude (toward zero); +<CODE>-rmin</CODE> sets rounding to minimum (down, toward negative infinity); +<CODE>-rmax</CODE> sets rounding to maximum (up, toward positive infinity); +and <CODE>-rodd</CODE>, if supported, sets rounding to odd. +These options are ignored for operations that are exact and thus do not round. +When rounding mode is relevant but not specified, the default is to round to +nearest/even, same as <CODE>-rnear_even</CODE>. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +When a <CODE><<I>function</I>></CODE> is specified that requires +rounding, the <CODE>-tininessbefore</CODE> option indicates that tininess on +underflow will be detected before rounding, while <CODE>-tininessafter</CODE> +indicates that tininess on underflow will be detected after rounding. +These options are ignored for operations that are exact and thus do not round. +When the method of tininess detection matters but is not specified, the default +is to detect tininess on underflow after rounding, same as +<CODE>-tininessafter</CODE>. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +When a <CODE><<I>function</I>></CODE> is specified that rounds to an +integer (either conversion to an integer type or a <CODE>roundToInt</CODE> +operation), the <CODE>-notexact</CODE> option indicates that the <I>inexact</I> +exception flag is never raised, while <CODE>-exact</CODE> indicates that the +<I>inexact</I> exception flag is to be raised if the result is inexact. +For other operations, these options are ignored. +If neither option is specified, the default is not to raise the <I>inexact</I> +exception flag when rounding to an integer, same as <CODE>-notexact</CODE>. +</P> + + +<H2>Output Format</H2> + +<P> +For each test case generated, <CODE>testfloat_gen</CODE> writes a single line +of text to standard output. +When the <CODE>testfloat_gen</CODE> command is given a +<CODE><<I>type</I>></CODE> argument, each test case consists of either +one integer value or one, two, or three floating-point values. +Each value is written to output as a raw hexadecimal number. +When there is more than one value per line, they are separated by spaces. +For example, output from executing +<BLOCKQUOTE> +<PRE> +testfloat_gen f64 2 +</PRE> +</BLOCKQUOTE> +might look like this: +<BLOCKQUOTE> +<PRE> +3F90EB5825D6851E C3E0080080000000 +41E3C00000000000 C182024F8AE474A8 +7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 +3FFFED6A25C534BE 3CA1000000020000 +... +</PRE> +</BLOCKQUOTE> +with each hexadecimal number being one <NOBR>64-bit</NOBR> floating-point +value. +Note that, for floating-point values, the sign and exponent are at the +most-significant end of the number. +Thus, for the first number on the first line above, the leading hexadecimal +digits <CODE>3F9</CODE> are the sign and encoded exponent of the +<NOBR>64-bit</NOBR> floating-point value, and the remaining digits are the +encoded significand. +</P> + +<P> +When <CODE>testfloat_gen</CODE> is given a <CODE><<I>function</I>></CODE> +operation name, each line of output has not only the operands for the operation +but also the expected output, consisting of a result value and the exception +flags that are raised. +For example, the output from +<BLOCKQUOTE> +<PRE> +testfloat_gen f64_add +</PRE> +</BLOCKQUOTE> +could include these lines: +<BLOCKQUOTE> +<PRE> +3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 +41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 +7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 +3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 +... +</PRE> +</BLOCKQUOTE> +On each line, the first two numbers are the operands for the floating-point +addition, and the third and fourth numbers are the expected floating-point +result (the sum) and the exception flags raised. +Exception flags are encoded with one bit per flag as follows: +<BLOCKQUOTE> +<TABLE CELLSPACING=0 CELLPADDING=0> +<TR> + <TD>bit 0<CODE> </CODE></TD> + <TD><I>inexact</I> exception</TD> +</TR> +<TR><TD>bit 1</TD><TD><I>underflow</I> exception</TD></TR> +<TR><TD>bit 2</TD><TD><I>overflow</I> exception</TD></TR> +<TR> + <TD>bit 3</TD> + <TD><I>infinite</I> exception (“divide by zero”)</TD> +</TR> +<TR><TD>bit 4</TD><TD><I>invalid</I> exception</TD></TR> +</TABLE> +</BLOCKQUOTE> +</P> + + +</BODY> + diff --git a/src/libs/softfloat-3e/testfloat/doc/testfloat_ver.html b/src/libs/softfloat-3e/testfloat/doc/testfloat_ver.html new file mode 100644 index 00000000..0790896b --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/testfloat_ver.html @@ -0,0 +1,270 @@ + +<HTML> + +<HEAD> +<TITLE>testfloat_ver</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: <CODE>testfloat_ver</CODE></H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</P> + + +<H2>Overview</H2> + +<P> +The <CODE>testfloat_ver</CODE> program accepts 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: +<BLOCKQUOTE> +<PRE> +testfloat_ver [<<I>option</I>>...] <<I>function</I>> +</PRE> +</BLOCKQUOTE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, +<CODE><<I>option</I>></CODE> is a supported option, and +<CODE><<I>function</I>></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 <<I>num</I>></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 +(Berkeley SoftFloat) generates the proper NaN results for the system being +tested. +</P> + +<H3><CODE>-checkInvInts</CODE></H3> + +<P> +The <CODE>-checkInvInts</CODE> option causes <CODE>testfloat_ver</CODE> to +verify the bitwise correctness of integer results of invalid operations. +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 +(Berkeley SoftFloat) generates the proper integer results for the system being +tested. +</P> + +<H3><CODE>-checkAll</CODE></H3> + +<P> +Enables both <CODE>-checkNaNs</CODE> and <CODE>-checkInvInts</CODE>. +</P> + +<H3><CODE>-precision32, -precision64, -precision80</CODE></H3> + +<P> +When <CODE><<I>function</I>></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, -rodd</CODE></H3> + +<P> +When <CODE><<I>function</I>></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), <CODE>-rmax</CODE> +indicates rounding to maximum (up, toward positive infinity), and +<CODE>-rodd</CODE>, if supported, indicates rounding to odd. +These options are ignored for operations that are exact and thus do not round. +When rounding mode is relevant but not specified, the default assumption is +rounding to nearest/even, same as <CODE>-rnear_even</CODE>. +</P> + +<H3><CODE>-tininessbefore, -tininessafter</CODE></H3> + +<P> +When <CODE><<I>function</I>></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 after rounding, same as +<CODE>-tininessafter</CODE>. +</P> + +<H3><CODE>-notexact, -exact</CODE></H3> + +<P> +When <CODE><<I>function</I>></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><<I>function</I>></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 +<BLOCKQUOTE> +<PRE> +testfloat_ver f64_add +</PRE> +</BLOCKQUOTE> +valid input could include these lines: +<BLOCKQUOTE> +<PRE> +3F90EB5825D6851E C3E0080080000000 C3E0080080000000 01 +41E3C00000000000 C182024F8AE474A8 41E377F6C1D46E2D 01 +7FD80FFFFFFFFFFF 7FEFFFFFFFFFFF80 7FF0000000000000 05 +3FFFED6A25C534BE 3CA1000000020000 3FFFED6A25C534BF 01 +... +</PRE> +</BLOCKQUOTE> +On each line above, the first two hexadecimal numbers represent the +<NOBR>64-bit</NOBR> floating-point operands, the third hexadecimal number is +the <NOBR>64-bit</NOBR> floating-point result of the operation (the sum), and +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 CELLSPACING=0 CELLPADDING=0> +<TR> + <TD>bit 0<CODE> </CODE></TD> + <TD><I>inexact</I> exception</TD> +</TR> +<TR><TD>bit 1</TD><TD><I>underflow</I> exception</TD></TR> +<TR><TD>bit 2</TD><TD><I>overflow</I> exception</TD></TR> +<TR> + <TD>bit 3</TD> + <TD><I>infinite</I> exception (“divide by zero”)</TD> +</TR> +<TR><TD>bit 4</TD><TD><I>invalid</I> exception</TD></TR> +</TABLE> +</BLOCKQUOTE> +</P> + + +</BODY> + diff --git a/src/libs/softfloat-3e/testfloat/doc/testsoftfloat.html b/src/libs/softfloat-3e/testfloat/doc/testsoftfloat.html new file mode 100644 index 00000000..09e488b1 --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/testsoftfloat.html @@ -0,0 +1,236 @@ + +<HTML> + +<HEAD> +<TITLE>testsoftfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: <CODE>testsoftfloat</CODE></H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</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 +five rounding modes defined by the IEEE Floating-Point Standard, one after the +other, plus possibly a sixth mode, <I>round to odd</I> (depending on the +options selected when <CODE>testsoftfloat</CODE> was compiled). +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: +<BLOCKQUOTE> +<PRE> +testsoftfloat [<<I>option</I>>...] <<I>function</I>> +</PRE> +</BLOCKQUOTE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, +<CODE><<I>option</I>></CODE> is a supported option, and +<CODE><<I>function</I>></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>-seed <<I>num</I>></CODE></H3> + +<P> +The <CODE>-seed</CODE> option sets the seed for the pseudo-random number +generator used for generating test cases. +The argument to <CODE>-seed</CODE> is a nonnegative integer. +Executing the same <CODE>testsoftfloat</CODE> program with the same arguments +(including the same pseudo-random number seed) should always perform the same +sequence of tests, whereas changing the pseudo-random number seed should result +in a different sequence of tests. +The default seed number <NOBR>is 1</NOBR>. +</P> + +<H3><CODE>-level <<I>num</I>></CODE></H3> + +<P> +The <CODE>-level</CODE> option sets the level of testing. +The argument to <CODE>-level</CODE> can be either 1 <NOBR>or 2</NOBR>. +The default is <NOBR>level 1</NOBR>. +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 <<I>num</I>></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, -rodd</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), <CODE>-rmax</CODE> forces rounding to maximum (up, +toward positive infinity), and <CODE>-rodd</CODE>, if supported, forces +rounding to odd. +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 or six +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> is all one-operand operations, while +<CODE>-all2</CODE> is all two-operand operations. +A function set is used in place of a function name in the +<CODE>testsoftfloat</CODE> command line, such as +<BLOCKQUOTE> +<PRE> +testsoftfloat [<<I>option</I>>...] -all1 +</PRE> +</BLOCKQUOTE> +</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/src/libs/softfloat-3e/testfloat/doc/timesoftfloat.html b/src/libs/softfloat-3e/testfloat/doc/timesoftfloat.html new file mode 100644 index 00000000..8808fe61 --- /dev/null +++ b/src/libs/softfloat-3e/testfloat/doc/timesoftfloat.html @@ -0,0 +1,196 @@ + +<HTML> + +<HEAD> +<TITLE>timesoftfloat</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3e: <CODE>timesoftfloat</CODE></H1> + +<P> +John R. Hauser<BR> +2018 January 20<BR> +</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 the 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 of the five rounding modes defined by the IEEE +Floating-Point Standard, one after the other, plus possibly a sixth mode, +<I>round to odd</I> (depending on the options selected when +<CODE>timesoftfloat</CODE> was compiled). +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 Mop/s, or “millions of operations per +second”. +The speeds reported by <CODE>timesoftfloat</CODE> may be affected somewhat by +other software executing at the same time as <CODE>timesoftfloat</CODE>. +Be aware also that the exact execution time of any SoftFloat function depends +partly on the values of arguments and the state of the processor’s caches +at the time the function is called. +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 for larger formats (<CODE>f64_rem</CODE>, +<CODE>extF80_rem</CODE>, and <CODE>f128_rem</CODE>) can 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: +<BLOCKQUOTE> +<PRE> +timesoftfloat [<<I>option</I>>...] <<I>function</I>> +</PRE> +</BLOCKQUOTE> +Square brackets (<CODE>[ ]</CODE>) denote optional arguments, +<CODE><<I>option</I>></CODE> is a supported option, and +<CODE><<I>function</I>></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, -rodd</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), <CODE>-rmax</CODE> forces rounding to maximum (up, +toward positive infinity), and <CODE>-rodd</CODE>, if supported, forces +rounding to odd. +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 or six +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> is 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 +<BLOCKQUOTE> +<PRE> +timesoftfloat [<<I>option</I>>...] -all1 +</PRE> +</BLOCKQUOTE> +</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> + |