doc/TestFloat-source.html - berkeley-testfloat-3 - Git at Google


 <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>
 &nbsp;&nbsp;&nbsp;&nbsp;6.1. Standard Headers <CODE>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</CODE><BR>
 &nbsp;&nbsp;&nbsp;&nbsp;6.2. Standard Header <CODE>&lt;fenv.h&gt;</CODE><BR>
 &nbsp;&nbsp;&nbsp;&nbsp;6.3. Macros for Build Options<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;6.4. Specializing the <CODE>testfloat</CODE> Program<BR>
 &nbsp;&nbsp;&nbsp;&nbsp;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>&lt;stdbool.h&gt;</CODE> and
 <CODE>&lt;stdint.h&gt;</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>&lt;stdbool.h&gt;</CODE>
 and <CODE>&lt;stdint.h&gt;</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-&lt;target&gt;</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>&lt;execution-environment&gt;-&lt;compiler&gt;</CODE></NOBR>.
 For the example targets,
 <NOBR><CODE>&lt;execution-environment&gt;</CODE></NOBR> is <CODE>Win32</CODE>
 and <CODE>Linux-386</CODE>, and <NOBR><CODE>&lt;compiler&gt;</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>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</CODE></H3>

 <P>
 The TestFloat sources make use of standard headers
 <CODE>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</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>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</CODE> may need to be
 created.
 TestFloat depends on these names from <CODE>&lt;stdbool.h&gt;</CODE>:
 <PRE>
      bool
      true
      false
 </PRE>
 and on these names from <CODE>&lt;stdint.h&gt;</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>&lt;fenv.h&gt;</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>&lt;fenv.h&gt;</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>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</CODE>,
 <CODE>&lt;fenv.h&gt;</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>&lt;fenv.h&gt;</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>&lt;fenv.h&gt;</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-&lt;target&gt;</CODE></NOBR> directory,
 where <CODE>&lt;target&gt;</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>

	<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>