John R. Hauser
2018 January 20
1. Introduction 2. Limitations 3. Acknowledgments and License 4. SoftFloat Package Directory Structure 5. Issues for Porting SoftFloat to a New Target 5.1. Standard Headers
5.2. Specializing Floating-Point Behavior 5.3. Macros for Build Options 5.4. Adapting a Template Target Directory 5.5. Target-Specific Optimization of Primitive Functions 6. Testing SoftFloat 7. Providing SoftFloat as a Common Library for Applications 8. Contact Information
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
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
gcc) for several platforms.
SoftFloat assumes the computer has an addressable byte size of either 8 or
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
<stdint.h> are required for defining standard Boolean and
If these headers are not supplied with the C compiler, minimal substitutes must
SoftFloat’s dependence on these headers is detailed later in
The SoftFloat 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 SoftFloat
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:
Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
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.
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.
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:
The majority of the SoftFloat sources are provided in thedoc source include 8086 8086-SSE ARM-VFPv2 ARM-VFPv2-defaultNaN build template-FAST_INT64 template-not-FAST_INT64 Linux-386-GCC Linux-386-SSE2-GCC Linux-x86_64-GCC Linux-ARM-VFPv2-GCC Win32-MinGW Win32-SSE2-MinGW Win64-MinGW-w64
includesubdirectory contains several header files (unsurprisingly), while the other subdirectories of
sourcecontain source files that specialize the floating-point behavior to match particular processor families:
If other specializations are attempted, these would be expected to be other subdirectories of
- Intel’s older, 8087-derived floating-point, extended to all supported floating-point types
- Intel’s x86 processors with Streaming SIMD Extensions (SSE) and later compatible extensions, having 8087 behavior for
extFloat80_t) and SSE behavior for other floating-point types
- ARM’s VFPv2 or later floating-point, with NaN payload propagation
- ARM’s VFPv2 or later floating-point, with the “default NaN” option
sourcealongside the ones listed above. Specialization is covered later, in
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
libsoftfloat.a) are created.
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.)
template directories, the supplied target directories
are intended to follow a naming system of
All of the supplied target directories are merely examples that may or may not be correct for compiling on any particular system. Despite requests, there are currently no plans to include and maintain in the SoftFloat 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:
The providedMakefile platform.h
Makefileis written for GNU
make. A build of SoftFloat for the specific target is begun by executing the
makecommand with the target directory as the current directory. A completely different build tool can be used if an appropriate
Makefileequivalent is created.
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
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
platform.h, avoiding the need to modify the main
The SoftFloat sources make use of standard headers
<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
For older or nonstandard compilers, substitutes for
<stdint.h> may need to be
SoftFloat depends on these names from
and on these names frombool true false
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
The IEEE Floating-Point Standard allows for some flexibility in a conforming
implementation, particularly concerning NaNs.
source directory is supplied with some
specialization subdirectories containing possible definitions for this
For example, the
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 ones
provided by the
specialize.h header file from any of the provided
specialization subdirectories can be used as a model for what definitions are
The SoftFloat source files adapt the floating-point implementation according to several C preprocessor macros:
- Must be defined for little-endian machines; must not be defined for big-endian machines.
- Specifies the sequence of tokens used to indicate that a C function should be inlined. If macro
INLINE_LEVELis defined with a value of 1 or higher, this macro must be defined; otherwise, this macro is ignored and need 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
- 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 header
softfloat.hin the declarations of variables
softfloat_exceptionFlags. If macro
THREAD_LOCALis left undefined, these variables will default to being ordinary global variables. Depending on the compiler, possible valid definitions of this macro include
- Can be defined to enable support for optional rounding mode
- 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.
- Can be defined to indicate that the build target’s implementation of
64-bitarithmetic is efficient. For newer 64-bitprocessors, this macro should usually be defined. For very small microprocessors whose buses and registers are 8-bitor 16-bitin size, this macro should usually not be defined. Whether this macro should be defined for a 32-bitprocessor may depend on the target machine and the applications that will use SoftFloat.
- Can be defined to indicate that the target’s division operator
in C(written as
/) is reasonably efficient for dividing a
32-bitunsigned integer by a 16-bitunsigned integer. Setting this macro may affect the performance of function
- Can be defined to indicate that the target’s division operator
in C(written as
/) is reasonably efficient for dividing a
64-bitunsigned integer by a 32-bitunsigned integer. Setting this macro may affect the performance of division, remainder, and square root operations other than
Following the usual custom
INLINE_LEVEL), the content of any definition is irrelevant;
what matters is a macro’s effect on
It is recommended that any definitions of macros
THREAD_LOCAL be made in a build
platform.h header file, because these macros are
expected to be determined inflexibly by the target machine and compiler.
The other five macros select options and control optimization, and thus might
be better located in the target’s Makefile (or its equivalent).
build directory, two
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 will be defined,
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
created 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
primitives.h declares a function called
softfloat_countLeadingZeros32 that takes an unsigned
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
platform.h header file.
For this purpose, it may be helpful for
#include header file
primitiveTypes.h, which defines
types used for arguments and results of functions declared in
When a desired replacement implementation is a function, not a macro, it is
platform.h to include the line
where#define <function-name> <function-name>
The supplied header file
opts-GCC.h (in directory
source/include) provides an example of target-specific
optimization for the GCC compiler.
Each GCC target example in the
build directory has
platform.hheader file. Before
opts-GCC.his included, the following macros must be defined (or not) to control which features are invoked:
On some machines, these improvements are observed to increase the speeds of
- If defined, SoftFloat’s internal ‘
countLeadingZeros’ functions use intrinsics
- If defined, SoftFloat makes use of GCC’s nonstandard
f128_mulby around 20 to 25%, although other functions receive less dramatic boosts, or none at all. Results can vary greatly across different platforms.
SoftFloat can be tested using the
testsoftfloat program by the
This program is part of the Berkeley TestFloat package available at the Web
measures the speed of SoftFloat’s floating-point functions.
softfloat.h defines the SoftFloat interface as seen by
If the SoftFloat library will be made a common library for programs on a
system, the supplied
softfloat.h has a couple of deficiencies for
softfloat.hdepends on another header,
softfloat_types.h, that is not intended for public use but which must also be visible to the programmer’s compiler.
softfloat.his included in a C source file, macros
THREAD_LOCALmust be defined, or not defined, consistent with how these macro were defined when the SoftFloat library was built.
softfloat.h, it is recommended that a custom, self-contained version of this header file be created that eliminates these issues.
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