John R. Hauser
2014 _____
*** CONTENT DONE.
*** REPLACE QUOTATION MARKS.
*** CHECK.
*** FIX FORMATTING.
1. Introduction
2. Limitations
3. Acknowledgments and License
4. TestFloat Package Directory Structure
5. Dependence on Berkeley SoftFloat
6. Issues for Porting TestFloat to a New Target
6.1. Standard Headers<stdbool.h>
and<stdint.h>
6.2. Standard Header<fenv.h>
6.3. Macros for Build Options
6.4. Specializing thetestfloat
Program
6.5. Improving the Random Number Functions
7. Contact Information
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
TestFloat-general.html
.
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 testfloat
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
(gcc
) for several platforms.
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
http://www.jhauser.us/arithmetic/SoftFloat.html
.
TestFloat assumes the computer has an addressable byte size of either 8 or
TestFloat is written entirely
<stdbool.h>
and
<stdint.h>
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
<stdbool.h>
and <stdint.h>
.
The TestFloat package was written by me,
Par Lab: 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. ASPIRE Lab: 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.
The following applies to the whole of TestFloat
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:
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.
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.
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 "
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:
doc source subj-C build template Win32-MinGW Linux-386-GCCThe majority of the TestFloat sources are provided in the
source
directory.
The subj-C
testfloat
program to test the C
compiler's implementation of the standard C types float
,
double
, and possibly long
double
.
The `subj
' in subj-C
testfloat
is retargeted to test other floating-point
implementations, the corresponding source files would be expected to be in
other subdirectories alongside subj-C
subj-<target>
testfloat
is found in
testfloat
Program.
The build
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 template
subdirectory is not an actual build target but
contains sample files for creating new target directories.
Ignoring the template
directory, the supplied target directories
are intended to follow a naming system of
<execution-environment>-<compiler>
<execution-environment>
Win32
and Linux-386
, and <compiler>
MinGW
and GCC
, respectively.
As supplied, each target directory contains two files:
Makefile platform.hThe provided
Makefile
is written for GNU make
.
A build of TestFloat for the specific target is begun by executing the
make
command with the target directory as the current directory.
A completely different build tool can be used if an appropriate
Makefile
equivalent is created.
The platform.h
header file exists to provide a location for
additional C declarations specific to the build target.
Every C source file of TestFloat contains a #include
for
platform.h
.
In many cases, the contents of platform.h
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
platform.h
, without the need to modify the main TestFloat sources.
It may not be necessary to build all of the TestFloat programs.
For testing a floating-point implementation, typically
testfloat_gen
and testfloat
will not both be used,
and testfloat_ver
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
testfloat
, which might not build without special attention.
In addition to the distributed sources, TestFloat depends on the existence of a
compatible Berkeley SoftFloat library and the corresponding header file
softfloat.h
.
As mentioned earlier, SoftFloat is a separate package available at Web page
http://www.jhauser.us/arithmetic/SoftFloat.html
.
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:
SOFTFLOAT_INCLUDE_DIR
- The path of the directory containing
softfloat.h
, as well as other nonstandard header files referenced bysoftfloat.h
, if any.SOFTFLOAT_H
- A list of the full paths of all SoftFloat header files needed by SoftFloat clients. This list must include
softfloat.h
and may also include other header files referenced bysoftfloat.h
, such assoftfloat_types.h
. 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.SOFTFLOAT_LIB
- The full path of the compiled SoftFloat library (usually
softfloat.a
).
<stdbool.h>
and <stdint.h>
The TestFloat sources make use of standard headers
<stdbool.h>
and <stdint.h>
, 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
<stdbool.h>
and <stdint.h>
may need to be
created.
TestFloat depends on these names from <stdbool.h>
:
bool true falseand on these names from
<stdint.h>
:
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
<fenv.h>
Because the supplied all-in-one testfloat
program tests the
floating-point operations of the C language, it uses the facilities provided by
standard C header <fenv.h>
to access the floating-point
environment of C, in particular to set the rounding mode and to access the
floating-point exception flags.
Like <stdbool.h>
and <stdint.h>
,
<fenv.h>
has been part of the ISO C Standard Library since
1999, but older or nonstandard C compilers may not support it.
Some form of standard header <fenv.h>
is needed only if the
testfloat
program is wanted and the program will not be
retargeted to invoke a floating-point implementation in a way that bypasses the
standard C environment.
Typically, if testfloat
is wanted, it will be retargeted to invoke
a new floating-point implementation directly, making
<fenv.h>
irrelevant.
For more about retargeting testfloat
, see testfloat
Program.
The TestFloat source files are affected by a few C preprocessor macros:
Following the usual custom
LITTLEENDIAN
- Must be defined for little-endian machines; must not be defined for big-endian machines.
EXTFLOAT80
- Must be defined if the TestFloat programs are to support the
80-bit double-extended-precision floating-point format.FLOAT128
- Must be defined if the TestFloat programs are to support the
128-bit quadruple-precision floating-point format.
#ifdef
directives.
It is recommended that any definition of macro LITTLEENDIAN
be
made in a build target's platform.h
header file, because
endianness is expected to be determined inflexibly by the target machine.
On the other hand, the EXTFLOAT80
and FLOAT128
macros
are not dictated by the target and hence might be better located in the
target's Makefile (or its equivalent).
testfloat
Program
The supplied sources for the all-in-one testfloat
program cause
testfloat
to test the C compiler's float
and
double
types for C operations +
, -
,
*
, /
, etc.
The supplied version is also capable of testing C type long
double
if the sources are compiled with one of these macros
defined:
By default,
LONG_DOUBLE_IS_EXTFLOAT80
- Indicates that type
long
double
is80-bit double-extended-precision floating-point.LONG_DOUBLE_IS_FLOAT128
- Indicates that type
long
double
is128-bit quadruple-precision floating-point.
testfloat
assumes that only the IEEE Standard's
original four rounding modes (near_even
, minMag
,
min
, and max
) are supported by the floating-point
being tested.
If the fifth rounding mode, near_maxMag
, is also supported, an
additional macro can be defined:
SUBJFLOAT_ROUND_NEAR_MAXMAG
- Indicates that the subject floating-point supports rounding mode
near_maxMag
(nearest/away).
To test a new and/or different implementation of floating-point,
testfloat
must normally be retargeted to invoke this other
floating-point instead of C's floating-point.
Two source files define the functions that testfloat
uses to
invoke floating-point operations for testing:
subjfloat_config.h subjfloat.cFor the default target of testing C's floating-point, these files are contained in directory
source/subj-C
subjfloat_config.h
and subjfloat.c
be
stored in a sibling subj-<target>
<target>
names the particular target.
Header file subjfloat_config.h
defines a macro of the form
SUBJ_*
for each subject function supported.
For example, if function subj_f32_add
exists to perform
subjfloat_config.h
should have a definition for macro
SUBJ_F32_ADD
.
The actual function subj_f32_add
is expected to be defined in
subjfloat.c
, along with all other subject functions.
A common header file, subjfloat.h
, (not target-specific) provides
prototype declarations for all possible subject functions that
testfloat
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 testfloat
, the -list
option
will list all subject functions that the testfloat
program is able
to invoke and thus test.
In the source code as supplied, macros LONG_DOUBLE_IS_EXTFLOAT80
and LONG_DOUBLE_IS_FLOAT128
affect only the target-specific source
files in source/subj-C
SUBJFLOAT_ROUND_NEAR_MAXMAG
always
determines whether the testfloat
program attempts to test rounding
mode near_maxMag
, regardless of the subject floating-point.
If you are serious about using TestFloat for testing floating-point, you should
consider replacing the random number functions in random.c
.
The supplied random number functions are built on top of the standard C
rand
function.
Because function rand
is rather poor on some systems, the
functions in random.c
assume very little about the quality of
rand
.
As a result, rand
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 rand
is better on a given target platform, or if another,
better random number generator is available (such as rand48
on
most UNIX-derived systems), TestFloat can be improved by overriding the given
random.c
with a target-specific one.
Rather than modifying the supplied file random.c
, 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
random.c
.
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
http://www.jhauser.us/arithmetic/TestFloat.html
.