Berkeley SoftFloat Release 3: Source Documentation

John R. Hauser
2014 _____

*** REPLACE QUOTATION MARKS.

*** CHECK.
*** FIX FORMATTING.

    Introduction
    Limitations
    Acknowledgments and License
    SoftFloat Package Directory Structure
    Issues for Porting SoftFloat to a New Target
        Standard Headers <stdbool.h> and <stdint.h>
        Specializing Floating-Point Behavior
        Macros for Build Options
        Adapting a Template Target Directory
        Target-Specific Optimization of Primitive Functions
    Testing SoftFloat
    Providing SoftFloat as a Common Library for Applications
    Contact Information

1. Introduction

This document gives information needed for compiling and/or porting Berkeley SoftFloat, a library of C functions implementing binary floating-point conforming to the IEEE Standard for Floating-Point Arithmetic. For basic documentation about SoftFloat refer to SoftFloat.html.

The source code for SoftFloat is intended to be relatively machine-independent and should be compilable with any ISO-standard C compiler that also supports 64-bit integers. SoftFloat has been successfully compiled with the GNU C Compiler (gcc) for several platforms.

Release 3 of SoftFloat is a complete rewrite relative to Release 2 or earlier. Changes to the interface of SoftFloat functions are documented in SoftFloat.html.

2. Limitations

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

SoftFloat is written in C and is designed to work with other C code. 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 SoftFloat included implementations of 32-bit single-precision and 64-bit double-precision floating-point that did not require 64-bit integers, but this option is not supported 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. SoftFloat's dependence on these headers is detailed later in section 5.1, Standard Headers <stdbool.h> and <stdint.h>.

3. Acknowledgments and License

The SoftFloat package was written by me, John R. Hauser. Release 3 of SoftFloat 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:

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

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 "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

4. SoftFloat Package Directory Structure

Because SoftFloat 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
         include
         8086
     build
         template-FAST_INT64
         template-not-FAST_INT64
         Win32-MinGW
         Linux-386-GCC

The majority of the SoftFloat sources are provided in the source directory. The include subdirectory of source contains several header files (unsurprisingly), while the 8086 subdirectory contains source files that specialize the floating-point behavior to match the Intel x86 line of processors. If other specializations are attempted, these would be expected to be other subdirectories of source alongside 8086. Specialization is covered later, in section 5.2, Specializing Floating-Point Behavior.

The build directory is intended to contain a subdirectory for each target platform for which a build of the SoftFloat library may be created. For each build target, the target's subdirectory is where all derived object files and the completed SoftFloat library (typically softfloat.a) are created. The two template subdirectories are not actual build targets but contain sample files for creating new target directories. (The meaning of FAST_INT64 will be explained later.)

Ignoring the template directories, the supplied target directories are intended to follow a naming system of <execution-environment>-<compiler>. For the example targets, <execution-environment> is Win32 and Linux-386, and <compiler> is MinGW and GCC, respectively.

As supplied, each target directory contains two files:

     Makefile
     platform.h

The provided Makefile is written for GNU make. A build of SoftFloat 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 SoftFloat 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. At the other extreme, to get maximal performance from SoftFloat, it may be desirable to include in header platform.h (directly or via #include) declarations for numerous target-specific optimizations. Such possibilities are discussed in the next section, Issues for Porting SoftFloat to a New Target. If the target's compiler or library has bugs or other shortcomings, workarounds for these issues may also be possible with target-specific declarations in platform.h, avoiding the need to modify the main SoftFloat sources.

5. Issues for Porting SoftFloat to a New Target

5.1. Standard Headers `<stdbool.h>` and `<stdint.h>`

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

5.2. Specializing Floating-Point Behavior

The IEEE Floating-Point Standard allows for some flexibility in a conforming implementation, particularly concerning NaNs. The SoftFloat source directory is supplied with one or more specialization subdirectories containing possible definitions for this implementation-specific behavior. For example, the 8086 subdirectory has source files that specialize SoftFloat's behavior to match that of Intel's x86 line of processors. The files in a specialization subdirectory must determine:

whether tininess for underflow is detected before or after rounding by default;
what (if anything) special happens when exceptions are raised;
how signaling NaNs are distinguished from quiet NaNs;
the default generated quiet NaNs; and
how NaNs are propagated from function inputs to output.

As provided, the build process for a target expects to involve exactly one specialization directory that defines all of these implementation-specific details for the target. A specialization directory such as 8086 is expected to contain a header file called specialize.h, together with whatever other source files are needed to complete the specialization.

A new build target may use an existing specialization, such as the one provided by the 8086 subdirectory. If a build target needs a new specialization, different from any existing ones, it is recommended that a new specialization subdirectory be created in the source directory for this purpose. The specialize.h header file from any of the provided specialization subdirectories can be used as a model for what definitions are needed.

5.3. Macros for Build Options

The SoftFloat source files adapt the floating-point implementation according to a few C preprocessor macros:

LITTLEENDIAN
Must be defined for little-endian machines; must not be defined for big-endian machines.
SOFTFLOAT_FAST_INT64
Can be defined to indicate that the build target's implementation of 64-bit arithmetic is efficient. For newer 64-bit processors, this macro should usually be defined. For very small microprocessors whose buses and registers are 8-bit or 16-bit in size, this macro should usually not be defined. Whether this macro should be defined for a 32-bit processor may depend on the target machine and the applications that will use SoftFloat.
SOFTFLOAT_FAST_DIV64TO32
Can be defined to indicate that the target's division operator in C (written as /) is reasonably efficient for dividing a 64-bit unsigned integer by a 32-bit unsigned integer. Setting this macro may affect the performance of division, remainder, and square root operations.
INLINE_LEVEL
Can be defined to an integer to determine the degree of inlining requested of the compiler. Larger numbers request that more inlining be done. If this macro is not defined or is defined to a value less than 1 (zero or negative), no inlining is requested. The maximum effective value is no higher than 5. Defining this macro to a value greater than 5 is the same as defining it to 5.
INLINE
Specifies the sequence of tokens used to indicate that a C function should be inlined. If macro INLINE_LEVEL is defined with a value of 1 or higher, this macro must be defined; otherwise, this macro is ignored and need not be defined. For some compilers, this macro can be defined as the single keyword inline. Historically, the gcc compiler has required that this macro be defined to extern inline.

Following the usual custom for C, for the first three macros (all except INLINE_LEVEL and INLINE), the content of any definition is irrelevant; what matters is a macro's effect on #ifdef directives.

It is recommended that any definitions of macros LITTLEENDIAN and INLINE 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 three macros control optimization and might be better located in the target's Makefile (or its equivalent).

5.4. Adapting a Template Target Directory

In the build directory, two template subdirectories provide models for new target directories. Two different templates exist because different functions are needed in the SoftFloat library depending on whether macro SOFTFLOAT_FAST_INT64 is defined. If macro SOFTFLOAT_FAST_INT64 will be defined, template-FAST_INT64 is the template to use; otherwise, template-not-FAST_INT64 is the appropriate template. A new target directory can be created by copying the correct template directory and editing the files inside. To avoid confusion, it would be wise to refrain from editing the files within a template directory directly.

5.5. Target-Specific Optimization of Primitive Functions

Header file primitives.h (in directory source/include) declares macros and functions for numerous underlying arithmetic operations upon which many of SoftFloat's floating-point functions are ultimately built. The SoftFloat sources include implementations of all of these functions/macros, written as standard C code, so a complete and correct SoftFloat library can be built using only the supplied code for all functions. However, for many targets, SoftFloat's performance can be improved by substituting target-specific implementations of some of the functions/macros declared in primitives.h.

For example, primitives.h declares a function called softfloat_countLeadingZeros32 that takes an unsigned 32-bit integer as an argument and returns the maximal number of the integer's most-significant bits that are all zeros. While the SoftFloat sources include an implementation of this function written in standard C, many processors can perform this same function directly in only one or two machine instructions. An alternative, target-specific implementation that maps to those instructions is likely to be more efficient than the generic C code from the SoftFloat package.

A build target can replace the supplied version of any function or macro of primitives.h by defining a macro with the same name in the target's platform.h header file. For this purpose, it may be helpful for platform.h to #include header file primitiveTypes.h, which defines types used for arguments and results of functions declared in primitives.h. When a desired replacement implementation is a function, not a macro, it is sufficient for platform.h to include the line

     #define <function-name> <function-name>

where <function-name> is the name of the function. This technically defines <function-name> as a macro, but one that resolves to the same name, which may then be a function. (A preprocessor conforming to the C Standard must limit recursive macro expansion from being applied more than once.)

6. Testing SoftFloat

SoftFloat can be tested using the testsoftfloat program by the same author. This program is part of the Berkeley TestFloat package available at the Web page http://www.jhauser.us/arithmetic/TestFloat.html. The TestFloat package also has a program called timesoftfloat that measures the speed of SoftFloat's floating-point functions.

7. Providing SoftFloat as a Common Library for Applications

Supplied softfloat.h depends on softfloat_types.h.

The target-specific `softfloat.h' header file defines the SoftFloat
interface as seen by clients.

Unlike the actual function definitions in `softfloat.c', the declarations
in `softfloat.h' do not use any of the types defined by the `processors'
header file.  This is done so that clients will not have to include the
`processors' header file in order to use SoftFloat.  Nevertheless, the
target-specific declarations in `softfloat.h' must match what `softfloat.c'
expects.  For example, if `int32' is defined as `int' in the `processors'
header file, then in `softfloat.h' the output of `float32_to_int32' should
be stated as `int', although in `softfloat.c' it is given in target-
independent form as `int32'.

*** HERE

Porting and/or compiling SoftFloat involves the following steps:

4. In the target-specific subdirectory, edit the files `softfloat-specialize'
   and `softfloat.h' to define the desired exception handling functions
   and mode control values.  In the `softfloat.h' header file, ensure also
   that all declarations give the proper target-specific type (such as
   `int' or `long') corresponding to the target-independent type used in
   `softfloat.c' (such as `int32').  None of the type names declared in the
   `processors' header file should appear in `softfloat.h'.

8. Contact Information

At the time of this writing, the most up-to-date information about SoftFloat and the latest release can be found at the Web page http://www.jhauser.us/arithmetic/SoftFloat.html.

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.