diff options
Diffstat (limited to 'doc/TestFloat-source.html')
| -rw-r--r-- | doc/TestFloat-source.html | 546 |
1 files changed, 546 insertions, 0 deletions
diff --git a/doc/TestFloat-source.html b/doc/TestFloat-source.html new file mode 100644 index 0000000..a875479 --- /dev/null +++ b/doc/TestFloat-source.html @@ -0,0 +1,546 @@ + +<HTML> + +<HEAD> +<TITLE>Berkeley TestFloat Source Documentation</TITLE> +</HEAD> + +<BODY> + +<H1>Berkeley TestFloat Release 3: Source Documentation</H1> + +<P> +John R. Hauser<BR> +2014 _____<BR> +</P> + +<P> +*** CONTENT DONE. +</P> + +<P> +*** REPLACE QUOTATION MARKS. +</P> + + +<H2>Contents</H2> + +<P> +*** CHECK.<BR> +*** FIX FORMATTING. +</P> + +<BLOCKQUOTE> +1. Introduction<BR> +2. Limitations<BR> +3. Acknowledgments and License<BR> +4. TestFloat Package Directory Structure<BR> +5. Dependence on Berkeley SoftFloat<BR> +6. Issues for Porting TestFloat to a New Target<BR> + 6.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE><BR> + 6.2. Standard Header <CODE><fenv.h></CODE><BR> + 6.3. Macros for Build Options<BR> + 6.4. Specializing the <CODE>testfloat</CODE> Program<BR> + 6.5. Improving the Random Number Functions<BR> +7. Contact Information<BR> +</BLOCKQUOTE> + + +<H2>1. Introduction</H2> + +<P> +This document gives information needed for compiling and/or porting Berkeley +TestFloat, a small collection of programs for testing that an implementation of +binary floating-point conforms to the IEEE Standard for Floating-Point +Arithmetic. +For basic documentation about TestFloat refer to +<A HREF="TestFloat-general.html"><CODE>TestFloat-general.html</CODE></A>. +</P> + +<P> +The source code for TestFloat is intended to be relatively machine-independent. +Most programs in the TestFloat package should be compilable with any +ISO-standard C compiler that also supports <NOBR>64-bit</NOBR> integers. +If the all-in-one <CODE>testfloat</CODE> program will be used to test a new +floating-point implementation, additional effort will likely be required to +retarget that program to invoke the new floating-point operations. +TestFloat has been successfully compiled with the GNU C Compiler +(<CODE>gcc</CODE>) for several platforms. +</P> + +<P> +<NOBR>Release 3</NOBR> of TestFloat is a complete rewrite relative to +<NOBR>Release 2</NOBR> or earlier. +</P> + +<P> +TestFloat depends on Berkeley SoftFloat, which is a software implementation of +binary floating-point that conforms to the IEEE Standard for Floating-Point +Arithmetic. +SoftFloat is not included with the TestFloat sources. +It can be obtained from the Web page +<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. +</P> + + +<H2>2. Limitations</H2> + +<P> +TestFloat assumes the computer has an addressable byte size of either 8 or +<NOBR>16 bits</NOBR>. +(Nearly all computers in use today have <NOBR>8-bit</NOBR> bytes.) +</P> + +<P> +TestFloat is written entirely <NOBR>in C</NOBR>. +The C compiler used must conform at a minimum to the 1989 ANSI standard for the +C language (same as the 1990 ISO standard) and must in addition support basic +arithmetic on <NOBR>64-bit</NOBR> integers. +Earlier releases of TestFloat were capable of testing <NOBR>32-bit</NOBR> +single-precision and <NOBR>64-bit</NOBR> double-precision floating-point +without requiring compiler support for <NOBR>64-bit</NOBR> integers, but this +option is not supported with <NOBR>Release 3</NOBR>. +Since 1999, ISO standards for C have mandated compiler support for +<NOBR>64-bit</NOBR> integers. +A compiler conforming to the 1999 C Standard or later is recommended but not +strictly required. +</P> + +<P> +<NOBR>C Standard</NOBR> header files <CODE><stdbool.h></CODE> and +<CODE><stdint.h></CODE> are required for defining standard Boolean and +integer types. +If these headers are not supplied with the C compiler, minimal substitutes must +be provided. +TestFloat's dependence on these headers is detailed later in +<NOBR>section 6.1</NOBR>, <I>Standard Headers <CODE><stdbool.h></CODE> +and <CODE><stdint.h></CODE></I>. +</P> + + +<H2>3. Acknowledgments and License</H2> + +<P> +The TestFloat package was written by me, <NOBR>John R.</NOBR> Hauser. +<NOBR>Release 3</NOBR> of TestFloat is a completely new implementation +supplanting earlier releases. +This project was done in the employ of the University of California, Berkeley, +within the Department of Electrical Engineering and Computer Sciences, first +for the Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab. +The work was officially overseen by Prof. Krste Asanovic, with funding provided +by these sources: +<BLOCKQUOTE> +<TABLE> +<TR> +<TD><NOBR>Par Lab:</NOBR></TD> +<TD> +Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery +(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, +NVIDIA, Oracle, and Samsung. +</TD> +</TR> +<TR> +<TD><NOBR>ASPIRE Lab:</NOBR></TD> +<TD> +DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from +ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, +Oracle, and Samsung. +</TD> +</TR> +</TABLE> +</BLOCKQUOTE> +</P> + +<P> +The following applies to the whole of TestFloat <NOBR>Release 3</NOBR> as well +as to each source file individually. +</P> + +<P> +Copyright 2011, 2012, 2013, 2014 The Regents of the University of California +(Regents). +All Rights Reserved. +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: +</P> + +<P> +Redistributions of source code must retain the above copyright notice, this +list of conditions, and the following two paragraphs of disclaimer. +Redistributions in binary form must reproduce the above copyright notice, this +list of conditions, and the following two paragraphs of disclaimer in the +documentation and/or other materials provided with the distribution. +Neither the name of the Regents nor the names of its contributors may be used +to endorse or promote products derived from this software without specific +prior written permission. +</P> + +<P> +IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, +INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF +THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</P> + +<P> +REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS +PROVIDED "<NOBR>AS IS</NOBR>". +REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, +ENHANCEMENTS, OR MODIFICATIONS. +</P> + + +<H2>4. TestFloat Package Directory Structure</H2> + +<P> +Because TestFloat is targeted to multiple platforms, its source code is +slightly scattered between target-specific and target-independent directories +and files. +The supplied directory structure is as follows: +<PRE> + doc + source + subj-C + build + template + Win32-MinGW + Linux-386-GCC +</PRE> +The majority of the TestFloat sources are provided in the <CODE>source</CODE> +directory. +The <NOBR><CODE>subj-C</CODE></NOBR> subdirectory contains the sources that +configure the all-in-one <CODE>testfloat</CODE> program to test the C +compiler's implementation of the standard C types <CODE>float</CODE>, +<CODE>double</CODE>, and possibly <CODE>long</CODE> <CODE>double</CODE>. +The `<CODE>subj</CODE>' in <NOBR><CODE>subj-C</CODE></NOBR> is an abbreviation +of <I>subject</I>, referring to the floating-point that is the subject of the +test. +If <CODE>testfloat</CODE> is retargeted to test other floating-point +implementations, the corresponding source files would be expected to be in +other subdirectories alongside <NOBR><CODE>subj-C</CODE></NOBR>, with names of +the form <NOBR><CODE>subj-<target></CODE></NOBR>. +More about retargeting <CODE>testfloat</CODE> is found in +<NOBR>section 6.4</NOBR>, <I>Specializing the <CODE>testfloat</CODE> +Program</I>. +</P> + +<P> +The <CODE>build</CODE> directory is intended to contain a subdirectory for each +target platform for which builds of the TestFloat programs may be created. +For each build target, the target's subdirectory is where all derived object +files and the completed TestFloat executables are created. +The <CODE>template</CODE> subdirectory is not an actual build target but +contains sample files for creating new target directories. +</P> + +<P> +Ignoring the <CODE>template</CODE> directory, the supplied target directories +are intended to follow a naming system of +<NOBR><CODE><execution-environment>-<compiler></CODE></NOBR>. +For the example targets, +<NOBR><CODE><execution-environment></CODE></NOBR> is <CODE>Win32</CODE> +and <CODE>Linux-386</CODE>, and <NOBR><CODE><compiler></CODE></NOBR> is +<CODE>MinGW</CODE> and <CODE>GCC</CODE>, respectively. +</P> + +<P> +As supplied, each target directory contains two files: +<PRE> + Makefile + platform.h +</PRE> +The provided <CODE>Makefile</CODE> is written for GNU <CODE>make</CODE>. +A build of TestFloat for the specific target is begun by executing the +<CODE>make</CODE> command with the target directory as the current directory. +A completely different build tool can be used if an appropriate +<CODE>Makefile</CODE> equivalent is created. +</P> + +<P> +The <CODE>platform.h</CODE> header file exists to provide a location for +additional C declarations specific to the build target. +Every C source file of TestFloat contains a <CODE>#include</CODE> for +<CODE>platform.h</CODE>. +In many cases, the contents of <CODE>platform.h</CODE> can be as simple as one +or two lines of code. +If the target's compiler or library has bugs or other shortcomings, workarounds +for these issues may be possible with target-specific declarations in +<CODE>platform.h</CODE>, without the need to modify the main TestFloat sources. +</P> + +<P> +It may not be necessary to build all of the TestFloat programs. +For testing a floating-point implementation, typically +<CODE>testfloat_gen</CODE> and <CODE>testfloat</CODE> will not both be used, +and <CODE>testfloat_ver</CODE> may not be needed either. +The Makefile (or equivalent) can be modified not to create unneeded programs. +This may be especially relevant for the all-in-one test program +<CODE>testfloat</CODE>, which might not build without special attention. +</P> + + +<H2>5. Dependence on Berkeley SoftFloat</H2> + +<P> +In addition to the distributed sources, TestFloat depends on the existence of a +compatible Berkeley SoftFloat library and the corresponding header file +<CODE>softfloat.h</CODE>. +As mentioned earlier, SoftFloat is a separate package available at Web page +<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. +The SoftFloat library must be compiled before the TestFloat programs can be +built. +In the example Makefiles, the locations of the SoftFloat header files and +pre-compiled library are specified by these macros: +<BLOCKQUOTE> +<DL> +<DT><CODE>SOFTFLOAT_INCLUDE_DIR</CODE> +<DD> +The path of the directory containing <CODE>softfloat.h</CODE>, as well as other +nonstandard header files referenced by <CODE>softfloat.h</CODE>, if any. +<DT><CODE>SOFTFLOAT_H</CODE> +<DD> +A list of the full paths of all SoftFloat header files needed by SoftFloat +clients. This list must include <CODE>softfloat.h</CODE> and may also include +other header files referenced by <CODE>softfloat.h</CODE>, such as +<CODE>softfloat_types.h</CODE>. +This macro is used only to establish build dependencies between the SoftFloat +header files and TestFloat's source files, in case the SoftFloat header files +are changed. +<DT><CODE>SOFTFLOAT_LIB</CODE> +<DD> +The full path of the compiled SoftFloat library (usually +<CODE>softfloat.a</CODE>). +</DL> +</BLOCKQUOTE> +</P> + + +<H2>6. Issues for Porting TestFloat to a New Target</H2> + +<H3>6.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE></H3> + +<P> +The TestFloat sources make use of standard headers +<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, which have +been part of the ISO C Standard Library since 1999. +With any recent compiler, these standard headers are likely to be supported, +even if the compiler does not claim complete conformance to the latest ISO C +Standard. +For older or nonstandard compilers, substitutes for +<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE> may need to be +created. +TestFloat depends on these names from <CODE><stdbool.h></CODE>: +<PRE> + bool + true + false +</PRE> +and on these names from <CODE><stdint.h></CODE>: +<PRE> + uint16_t + uint32_t + uint64_t + int32_t + int64_t + UINT64_C + INT64_C + uint_least8_t + uint_fast8_t + uint_fast16_t + uint_fast32_t + uint_fast64_t + int_fast16_t + int_fast32_t + int_fast64_t +</PRE> +</P> + + +<H3>6.2. Standard Header <CODE><fenv.h></CODE></H3> + +<P> +Because the supplied all-in-one <CODE>testfloat</CODE> program tests the +floating-point operations of the C language, it uses the facilities provided by +standard C header <CODE><fenv.h></CODE> to access the floating-point +environment of C, in particular to set the rounding mode and to access the +floating-point exception flags. +Like <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, +<CODE><fenv.h></CODE> has been part of the ISO C Standard Library since +1999, but older or nonstandard C compilers may not support it. +</P> + +<P> +Some form of standard header <CODE><fenv.h></CODE> is needed only if the +<CODE>testfloat</CODE> program is wanted <EM>and</EM> the program will not be +retargeted to invoke a floating-point implementation in a way that bypasses the +standard C environment. +Typically, if <CODE>testfloat</CODE> is wanted, it will be retargeted to invoke +a new floating-point implementation directly, making +<CODE><fenv.h></CODE> irrelevant. +For more about retargeting <CODE>testfloat</CODE>, see <NOBR>section 6.4</NOBR> +below, <I>Specializing the <CODE>testfloat</CODE> Program</I>. +</P> + + +<H3>6.3. Macros for Build Options</H3> + +<P> +The TestFloat source files are affected by a few C preprocessor macros: +<BLOCKQUOTE> +<DL> +<DT><CODE>LITTLEENDIAN</CODE> +<DD> +Must be defined for little-endian machines; +must not be defined for big-endian machines. +<DT><CODE>EXTFLOAT80</CODE> +<DD> +Must be defined if the TestFloat programs are to support the +<NOBR>80-bit</NOBR> double-extended-precision floating-point format. +<DT><CODE>FLOAT128</CODE> +<DD> +Must be defined if the TestFloat programs are to support the +<NOBR>128-bit</NOBR> quadruple-precision floating-point format. +</DL> +</BLOCKQUOTE> +Following the usual custom <NOBR>for C</NOBR>, the content of a macro's +definition is irrelevant; +what matters is a macro's effect on <CODE>#ifdef</CODE> directives. +</P> + +<P> +It is recommended that any definition of macro <CODE>LITTLEENDIAN</CODE> be +made in a build target's <CODE>platform.h</CODE> header file, because +endianness is expected to be determined inflexibly by the target machine. +On the other hand, the <CODE>EXTFLOAT80</CODE> and <CODE>FLOAT128</CODE> macros +are not dictated by the target and hence might be better located in the +target's Makefile (or its equivalent). +</P> + + +<H3>6.4. Specializing the <CODE>testfloat</CODE> Program</H3> + +<P> +The supplied sources for the all-in-one <CODE>testfloat</CODE> program cause +<CODE>testfloat</CODE> to test the C compiler's <CODE>float</CODE> and +<CODE>double</CODE> types for C operations <CODE>+</CODE>, <CODE>-</CODE>, +<CODE>*</CODE>, <CODE>/</CODE>, etc. +The supplied version is also capable of testing C type <CODE>long</CODE> +<CODE>double</CODE> if the sources are compiled with one of these macros +defined: +<BLOCKQUOTE> +<DL> +<DT><CODE>LONG_DOUBLE_IS_EXTFLOAT80</CODE> +<DD> +Indicates that type <CODE>long</CODE> <CODE>double</CODE> is +<NOBR>80-bit</NOBR> double-extended-precision floating-point. +<DT><CODE>LONG_DOUBLE_IS_FLOAT128</CODE> +<DD> +Indicates that type <CODE>long</CODE> <CODE>double</CODE> is +<NOBR>128-bit</NOBR> quadruple-precision floating-point. +</DL> +</BLOCKQUOTE> +By default, <CODE>testfloat</CODE> assumes that only the IEEE Standard's +original four rounding modes (<CODE>near_even</CODE>, <CODE>minMag</CODE>, +<CODE>min</CODE>, and <CODE>max</CODE>) are supported by the floating-point +being tested. +If the fifth rounding mode, <CODE>near_maxMag</CODE>, is also supported, an +additional macro can be defined: +<BLOCKQUOTE> +<DL> +<DT><CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE> +<DD> +Indicates that the subject floating-point supports rounding mode +<CODE>near_maxMag</CODE> (nearest/away). +</DL> +</BLOCKQUOTE> +</P> + +<P> +To test a new and/or different implementation of floating-point, +<CODE>testfloat</CODE> must normally be retargeted to invoke this other +floating-point instead of C's floating-point. +Two source files define the functions that <CODE>testfloat</CODE> uses to +invoke floating-point operations for testing: +<PRE> + subjfloat_config.h + subjfloat.c +</PRE> +For the default target of testing C's floating-point, these files are contained +in directory <NOBR><CODE>source/subj-C</CODE></NOBR> as discussed earlier. +For a different subject floating-point, it is recommended that appropriate +versions of <CODE>subjfloat_config.h</CODE> and <CODE>subjfloat.c</CODE> be +stored in a sibling <NOBR><CODE>subj-<target></CODE></NOBR> directory, +where <CODE><target></CODE> names the particular target. +</P> + +<P> +Header file <CODE>subjfloat_config.h</CODE> defines a macro of the form +<CODE>SUBJ_*</CODE> for each subject function supported. +For example, if function <CODE>subj_f32_add</CODE> exists to perform +<NOBR>32-bit</NOBR> floating-point addition, then +<CODE>subjfloat_config.h</CODE> should have a definition for macro +<CODE>SUBJ_F32_ADD</CODE>. +The actual function <CODE>subj_f32_add</CODE> is expected to be defined in +<CODE>subjfloat.c</CODE>, along with all other subject functions. +A common header file, <CODE>subjfloat.h</CODE>, (not target-specific) provides +prototype declarations for all possible subject functions that +<CODE>testfloat</CODE> may be compiled to test, whether actually existing or +not. +(There is no penalty for the header to declare prototypes of nonexistent +functions that are never called.) +For a specific build of <CODE>testfloat</CODE>, the <CODE>-list</CODE> option +will list all subject functions that the <CODE>testfloat</CODE> program is able +to invoke and thus test. +</P> + +<P> +In the source code as supplied, macros <CODE>LONG_DOUBLE_IS_EXTFLOAT80</CODE> +and <CODE>LONG_DOUBLE_IS_FLOAT128</CODE> affect only the target-specific source +files in <NOBR><CODE>source/subj-C</CODE></NOBR>, so these macros can be +ignored for any other subject floating-point that does not depend on them. +On the other hand, macro <CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE> always +determines whether the <CODE>testfloat</CODE> program attempts to test rounding +mode <CODE>near_maxMag</CODE>, regardless of the subject floating-point. +</P> + + +<H3>6.5. Improving the Random Number Functions</H3> + +<P> +If you are serious about using TestFloat for testing floating-point, you should +consider replacing the random number functions in <CODE>random.c</CODE>. +The supplied random number functions are built on top of the standard C +<CODE>rand</CODE> function. +Because function <CODE>rand</CODE> is rather poor on some systems, the +functions in <CODE>random.c</CODE> assume very little about the quality of +<CODE>rand</CODE>. +As a result, <CODE>rand</CODE> is called more frequently than it might need to +be, shortening the time before random number sequences repeat, and possibly +wasting time as well. +If <CODE>rand</CODE> is better on a given target platform, or if another, +better random number generator is available (such as <CODE>rand48</CODE> on +most UNIX-derived systems), TestFloat can be improved by overriding the given +<CODE>random.c</CODE> with a target-specific one. +</P> + +<P> +Rather than modifying the supplied file <CODE>random.c</CODE>, it is +recommended instead that a new, alternate file be created and the target's +Makefile be modified to refer to that alternate file in place of +<CODE>random.c</CODE>. +</P> + + +<H2>7. Contact Information</H2> + +<P> +At the time of this writing, the most up-to-date information about TestFloat +and the latest release can be found at the Web page +<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></A>. +</P> + + +</BODY> + |