Berkeley TestFloat Source Documentation

# Berkeley TestFloat Release 3e: Source Documentation

John R. Hauser
2018 January 20

## Contents

> 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 the `testfloat` Program
> | 6.5. Improving the Random Number Functions
> 7. Contact Information

## 1. Introduction

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 64-bit integers. If the all-in-one `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.

Release 3 of TestFloat was a complete rewrite relative to Release 2c or earlier. The current version of TestFloat is Release 3e.

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

## 2. Limitations

TestFloat assumes the computer has an addressable byte size of either 8 or 16 bits. (Nearly all computers in use today have 8-bit bytes.)

TestFloat is written entirely in C. 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 64-bit integers. Earlier releases of TestFloat were capable of testing 32-bit single-precision and 64-bit double-precision floating-point without requiring compiler support for 64-bit integers, but this option is not supported starting with Release 3. Since 1999, ISO standards for C have mandated compiler support for 64-bit integers. A compiler conforming to the 1999 C Standard or later is recommended but not strictly required.

C Standard header files `<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 section 6.1, Standard Headers `<stdbool.h>` and `<stdint.h>`.

## 3. Acknowledgments and License

The TestFloat package was written by me, John R. Hauser. Release 3 of TestFloat was a completely new implementation supplanting earlier releases. The project to create Release 3 (now through 3e) 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:

> 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 Release 3e as well as to each source file individually.

Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the University of California. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.

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

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

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.

## 4. TestFloat Package Directory Structure

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
>         Linux-386-GCC
>         Linux-386-SSE2-GCC
>         Linux-x86_64-GCC
>         Linux-ARM-VFPv2-GCC
>         Win32-MinGW
>         Win32-SSE2-MinGW
>         Win64-MinGW-w64

The majority of the TestFloat sources are provided in the `source` directory. The `subj-C` subdirectory contains the sources that configure the all-in-one `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` is an abbreviation of subject, referring to the floating-point that is the subject of the test. If `testfloat` is retargeted to test other floating-point implementations, the corresponding source files would be expected to be in other subdirectories alongside `subj-C`, with names of the form `subj-<target>`. More about retargeting `testfloat` is found in section 6.4, Specializing the `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>`. For the example targets, `<execution-environment>` is `Linux-386`, `Linux-386-SSE2`, `Linux-x86_64`, `Linux-ARM-VFPv2`, `Win32`, `Win32-SSE2`, or `Win64`, and `<compiler>` is `GCC`, `MinGW`, or `MinGW-w64`.

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.

As supplied, each target directory contains two files:

>     Makefile
>     platform.h

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

## 5. Dependence on Berkeley SoftFloat

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 by `softfloat.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 by `softfloat.h`, such as `softfloat_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` or `libsoftfloat.a`).

## 6. Issues for Porting TestFloat to a New Target

### 6.1. Standard Headers `<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
>     false

and 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_fast8_t
>     int_fast16_t
>     int_fast32_t
>     int_fast64_t

### 6.2. Standard Header `<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 section 6.4 below, Specializing the `testfloat` Program.

### 6.3. Macros for Build Options

The TestFloat source files are affected by several C preprocessor macros:

> `LITTLEENDIAN`
>   Must be defined for little-endian machines; must not be defined for big-endian machines.
> `INLINE`
>   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 `inline`. For other compilers that follow a convention pre-dating the standardization of `inline`, this macro may need to be defined to `extern` `inline`.
> `THREAD_LOCAL`
>   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 per-thread, 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 `softfloat.h`, in the declarations of variables `softfloat_roundingMode`, `softfloat_detectTininess`, `extF80_roundingPrecision`, and `softfloat_exceptionFlags`. To use the supplied, unmodified header `softfloat.h`, this macro must be defined (or not defined) the same as when the SoftFloat library was built.
> `FLOAT16`
>   Must be defined if the TestFloat programs are to support the 16-bit half-precision floating-point format.
> `FLOAT64`
>   Must be defined if the TestFloat programs are to support the 64-bit double-precision floating-point format.
> `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.
> `FLOAT_ROUND_ODD`
>   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 `SOFTFLOAT_ROUND_ODD` defined.

Following the usual custom for C, for all the macros except `INLINE` and `THREAD_LOCAL`, the content of a macro’s definition is irrelevant; what matters is a macro’s effect on `#ifdef` directives.

It is recommended that any definition of macros `LITTLEENDIAN`, `INLINE`, and `THREAD_LOCAL` be made in a build target’s `platform.h` 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).

### 6.4. Specializing the `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:

> `LONG_DOUBLE_IS_EXTFLOAT80`
>   Indicates that type `long` `double` is 80-bit double-extended-precision floating-point.
> `LONG_DOUBLE_IS_FLOAT128`
>   Indicates that type `long` `double` is 128-bit quadruple-precision floating-point.

By default, `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. For other rounding modes, additional macro can be defined:

> `SUBJFLOAT_ROUND_NEAR_MAXMAG`
>   Indicates that the subject floating-point supports rounding mode `near_maxMag` (nearest/away).
> `SUBJFLOAT_ROUND_ODD`
>   Indicates that the subject floating-point supports rounding mode `odd` (jamming).

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

For the default target of testing C’s floating-point, these files are contained in directory `source/subj-C` as discussed earlier. For a different subject floating-point, it is recommended that appropriate versions of `subjfloat_config.h` and `subjfloat.c` be stored in a sibling `subj-<target>` directory, where `<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 32-bit floating-point addition, then `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`, so these macros can be ignored for any other subject floating-point that does not depend on them. On the other hand, macros `SUBJFLOAT_ROUND_NEAR_MAXMAG` and `SUBJFLOAT_ROUND_ODD` always determine whether the `testfloat` program attempts to test rounding modes `near_maxMag` and `odd`, regardless of the subject floating-point.

### 6.5. Improving the Random Number Functions

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

## 7. Contact Information

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