SoftFloat-source.txt

Berkeley SoftFloat Release 2c Source Documentation

John R. Hauser
2015 January 30


----------------------------------------------------------------------------
Introduction

Berkeley SoftFloat is a software implementation of binary floating-point
that conforms to the IEEE Standard for Floating-Point Arithmetic.
Release 2c of SoftFloat can support four floating-point formats:  32-bit
single-precision, 64-bit double-precision, 80-bit double-extended-precision,
and 128-bit quadruple-precision.  All operations required by the older 1985
version of the IEEE Standard are implemented, except for conversions to and
from decimal.  SoftFloat is distributed in the form of C source code, so a
C compiler is needed to compile the code.  Support for the 80-bit double-
extended-precision and 128-bit quadruple-precision formats is dependent on
the C compiler implementing a 64-bit integer type.

This document gives information needed for compiling and/or porting this
SoftFloat release.

The source code for SoftFloat is intended to be relatively machine-
independent and should be compilable using most any ISO/ANSI C compiler.  At
the time of this writing, SoftFloat has been successfully compiled with the
GNU C Compiler (`gcc') for several platforms.


----------------------------------------------------------------------------
Limitations

As supplied, SoftFloat requires an ISO/ANSI-style C compiler.  No attempt
has been made to accomodate compilers that are not ISO-conformant.  Older
"K&R-style" compilers are not adequate for compiling SoftFloat.  All testing
I have done so far has been with the GNU C Compiler.  Compilation with other
compilers should be possible but has not been tested by me.

The SoftFloat sources assume that source code file names can be longer than
8 characters.  In order to compile under an MS-DOS-type system, many of the
source files will need to be renamed, and the source and Makefiles edited
appropriately.  Once compiled, the SoftFloat binary does not depend on the
existence of long file names.

The underlying machine is assumed to be binary with a word size that is a
power of 2.  Bytes are 8 bits.  Arithmetic on signed integers must modularly
wrap around on overflows (as is already required for unsigned integers
in C).

Support for the 80-bit double-extended-precision and 128-bit quadruple-
precision formats depends on the C compiler implementing a 64-bit integer
type.  If the largest integer type supported by the C compiler is 32 bits,
SoftFloat is limited to the 32-bit single-precision and 64-bit double-
precision formats.


----------------------------------------------------------------------------
Contents

    Introduction
    Limitations
    Contents
    Legal Notice
    SoftFloat Source Directory Structure
    SoftFloat Source Files
        processors/*.h
        softfloat/bits*/*/softfloat.h
        softfloat/bits*/*/milieu.h
        softfloat/bits*/*/softfloat-specialize
        softfloat/bits*/softfloat-macros
        softfloat/bits*/softfloat.c
    Steps to Creating a `softfloat.o'
    Making `softfloat.o' a Library
    Testing SoftFloat
    Timing SoftFloat
    Compiler Options and Efficiency
    Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'
    Contact Information



----------------------------------------------------------------------------
Legal Notice

SoftFloat was written by John R. Hauser.  Release 2c of SoftFloat was made
possible in part by the International Computer Science Institute, located
at Suite 600, 1947 Center Street, Berkeley, California 94704.  Funding
was partially provided by the National Science Foundation under grant
MIP-9311980.  The original version of this code was written as part of a
project to build a fixed-point vector processor in collaboration with the
University of California at Berkeley, overseen by Profs. Nelson Morgan and
John Wawrzynek.

THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE.  Although reasonable effort
has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT
TIMES RESULT IN INCORRECT BEHAVIOR.  USE OF THIS SOFTWARE IS RESTRICTED TO
PERSONS AND ORGANIZATIONS WHO CAN AND WILL TOLERATE ALL LOSSES, COSTS, OR
OTHER PROBLEMS THEY INCUR DUE TO THE SOFTWARE WITHOUT RECOMPENSE FROM JOHN
HAUSER OR THE INTERNATIONAL COMPUTER SCIENCE INSTITUTE, AND WHO FURTHERMORE
EFFECTIVELY INDEMNIFY JOHN HAUSER AND THE INTERNATIONAL COMPUTER SCIENCE
INSTITUTE (possibly via similar legal notice) AGAINST ALL LOSSES, COSTS, OR
OTHER PROBLEMS INCURRED BY THEIR CUSTOMERS AND CLIENTS DUE TO THE SOFTWARE,
OR INCURRED BY ANYONE DUE TO A DERIVATIVE WORK THEY CREATE USING ANY PART OF
THE SOFTWARE.

The following are expressly permitted, even for commercial purposes:
(1) distribution of SoftFloat in whole or in part, as long as this and
other legal notices remain and are prominent, and provided also that, for a
partial distribution, prominent notice is given that it is a subset of the
original; and
(2) inclusion or use of SoftFloat in whole or in part in a derivative
work, provided that the use restrictions above are met and the minimal
documentation requirements stated in the source code are satisfied.


----------------------------------------------------------------------------
SoftFloat Source 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 directory structure is as follows:

    processors
    softfloat
        bits64
            templates
            386-Win32-GCC
            SPARC-Solaris-GCC
        bits32
            templates
            386-Win32-GCC
            SPARC-Solaris-GCC

The two topmost directories and their contents are:

    softfloat    - Most of the source code needed for SoftFloat.
    processors   - Target-specific header files that are not specific to
                       SoftFloat.

The `softfloat' directory is further split into two parts:

    bits64       - SoftFloat implementation using 64-bit integers.
    bits32       - SoftFloat implementation using only 32-bit integers.

Within these directories are subdirectories for each of the targeted
platforms.  The SoftFloat source code is distributed with targets
`386-Win32-GCC' and `SPARC-Solaris-GCC' (and perhaps others) already
prepared for both the 32-bit and 64-bit implementations.  Source files
that are not within these target-specific subdirectories are intended to be
target-independent.

The naming convention used for the target-specific directories is
`<processor>-<executable-type>-<compiler>'.  The names of the supplied
target directories should be interpreted as follows:

  <processor>:
    386          - Intel 386-compatible processor.
    SPARC        - SPARC processor (as used by Sun computers).
  <executable-type>:
    Win32        - Microsoft Win32 executable.
    Solaris      - Sun Solaris executable.
  <compiler>:
    GCC          - GNU C Compiler.

You do not need to maintain this convention if you do not want to.

Alongside the supplied target-specific directories is a `templates'
directory containing a set of "generic" target-specific source files.  A
new target directory can be created by copying the `templates' directory and
editing the files inside.  (Complete instructions for porting SoftFloat to
a new target are in the section _Steps to Creating a `softfloat.o'_.)  Note
that the `templates' directory will not work as a target directory without
some editing.  To avoid confusion, it would be wise to refrain from editing
the files inside `templates' directly.


----------------------------------------------------------------------------
SoftFloat Source Files

The purpose of each source file is described below.  In the following,
the `*' symbol is used in place of the name of a specific target, such as
`386-Win32-GCC' or `SPARC-Solaris-GCC', or in place of some other text, as
in `bits*' for either `bits32' or `bits64'.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
processors/*.h

The target-specific `processors' header file defines integer types
of various sizes, and also defines certain C preprocessor macros that
characterize the target.  The two examples supplied are `386-GCC.h' and
`SPARC-GCC.h'.  The naming convention used for processor header files is
`<processor>-<compiler>.h'.

If 64-bit integers are supported by the compiler, the macro name `BITS64'
should be defined here along with the corresponding 64-bit integer
types.  In addition, the function-like macro `LIT64' must be defined for
constructing 64-bit integer literals (constants).  The `LIT64' macro is used
consistently in the SoftFloat code to annotate 64-bit literals.

If `BITS64' is not defined, only the 32-bit version of SoftFloat can be
compiled.  If `BITS64' _is_ defined, either can be compiled.

If an inlining attribute (such as an `inline' keyword) is provided by the
compiler, the macro `INLINE' should be defined to the appropriate keyword.
If not, `INLINE' can be set to the keyword `static'.  The `INLINE' macro
appears in the SoftFloat source code before every function that should
be inlined by the compiler.  SoftFloat depends on inlining to obtain
good speed.  Even if inlining cannot be forced with a language keyword,
the compiler may still be able to perform inlining on its own as an
optimization.  If a command-line option is needed to convince the compiler
to perform this optimization, this should be assured in the Makefile.  (See
the section _Compiler Options and Efficiency_ below.)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
softfloat/bits*/*/softfloat.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'.

For the `bits64' implementation of SoftFloat, the macro names `FLOATX80'
and `FLOAT128' must be defined in order for the 80-bit double-extended-
precision and 128-bit quadruple-precision formats to be enabled in the
code.  Conversely, either or both of these larger formats can be disabled by
simply removing the `#define' of the respective macro.  When a format is not
enabled, none of the functions that either input or output the format are
defined, and no space is taken up in `softfloat.o' by such functions.  There
is no provision for disabling the usual 32-bit single-precision and 64-bit
double-precision formats.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
softfloat/bits*/*/milieu.h

The target-specific `milieu.h' header file provides declarations that are
needed to compile SoftFloat.  In addition, deviations from ISO/ANSI C by
the compiler (such as names not properly declared in system header files)
are corrected in this header if possible.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
softfloat/bits*/*/softfloat-specialize

This target-specific C source fragment defines:

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

These details are not decided by the IEEE Standard.  This fragment is
included verbatim within `softfloat.c' when SoftFloat is compiled.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
softfloat/bits*/softfloat-macros

This target-independent C source fragment defines a number of arithmetic
functions used as primitives within the `softfloat.c' source.  Most of
the functions defined here are intended to be inlined for efficiency.
This fragment is included verbatim within `softfloat.c' when SoftFloat is
compiled.

Target-specific variations on this file are possible.  See the section
_Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'_
below.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
softfloat/bits*/softfloat.c

The target-independent `softfloat.c' source file contains the body of the
SoftFloat implementation.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

The inclusion of the files above within each other (using `#include') can be
shown graphically as follows:

    softfloat/bits*/softfloat.c
        softfloat/bits*/*/milieu.h
            processors/*.h
        softfloat/bits*/*/softfloat.h
        softfloat/bits*/*/softfloat-specialize
        softfloat/bits*/softfloat-macros

Note in particular that `softfloat.c' does not include the `processors'
header file directly.  Rather, `softfloat.c' includes the target-specific
`milieu.h' header file, which in turn includes the appropriate processor
header file.


----------------------------------------------------------------------------
Steps to Creating a `softfloat.o'

Porting and/or compiling SoftFloat involves the following steps:

1. If one does not already exist, create an appropriate `.h' file in the
   `processors' directory.

2. If `BITS64' is defined in the `processors' header file, choose whether
   to compile the 32-bit or 64-bit implementation of SoftFloat.  If
   `BITS64' is not defined, your only choice is the 32-bit implementation.
   The remaining steps occur within either the `bits32' or `bits64'
   subdirectories.

3. If one does not already exist, create an appropriate target-specific
   subdirectory by copying the given `templates' directory.

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

5. In the target-specific subdirectory, edit the files `milieu.h' and
   `Makefile' to reflect the current environment.

6. In the target-specific subdirectory, execute `make'.

For the targets that are supplied, if the expected compiler is available
(usually `gcc'), it should only be necessary to execute `make' in the
target-specific subdirectory.


----------------------------------------------------------------------------
Making `softfloat.o' a Library

SoftFloat is not made into a software library by the supplied Makefile.
If desired, `softfloat.o' can easily be put into its own library (typically
`softfloat.a' or `libsoftfloat.a') using the usual system tool (in UNIX,
`ar').


----------------------------------------------------------------------------
Testing SoftFloat

SoftFloat can be tested using the `testsoftfloat' program by the same
author.  The `testsoftfloat' program is part of the TestFloat package
available at the Web page `http://www.jhauser.us/arithmetic/TestFloat.html'.


----------------------------------------------------------------------------
Timing SoftFloat

A program called `timesoftfloat' for timing the SoftFloat functions is
included with the SoftFloat source code.  Compiling `timesoftfloat' should
pose no difficulties once `softfloat.o' exists.  The supplied Makefile
will create a `timesoftfloat' executable by default after generating
`softfloat.o'.  See `timesoftfloat.txt' for documentation about using
`timesoftfloat'.


----------------------------------------------------------------------------
Compiler Options and Efficiency

In order to get good speed with SoftFloat, it is important that the compiler
inline the routines that have been marked `INLINE' in the code.  Even if
inlining cannot be forced by an appropriate definition of the `INLINE'
macro, the compiler may still be able to perform inlining on its own as
an optimization.  In that case, the Makefile should be edited to give the
compiler whatever option is required to cause it to inline small functions.


----------------------------------------------------------------------------
Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'

The `softfloat-macros' source fragment defines arithmetic functions used
as primitives by `softfloat.c'.  This file has been written in a target-
independent form.  For a given target, it may be possible to improve on
these functions using target-specific and/or non-ISO-C features (such
as `asm' statements).  For example, one of the "macro" functions takes
two word-size integers and returns their full product in two words.
This operation can be done directly in hardware on many processors; but
because it is not available through standard C, the function defined in
`softfloat-macros' uses four multiplications to achieve the same result.

To address these shortcomings, a customized version of `softfloat-macros'
can be created in any of the target-specific subdirectories.  A simple
modification to the target's Makefile should be sufficient to ensure that
the custom version is used instead of the generic one.


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