Subversion Repositories fpu100

SoftFloat Release 2b Source Documentation

John R. Hauser

2002 May 27

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

Introduction

SoftFloat is a software implementation of floating-point that conforms to

the IEC/IEEE Standard for Binary Floating-Point Arithmetic.  SoftFloat can

support four floating-point formats:  single precision, double precision,

extended double precision, and quadruple precision.  All operations required

by 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 extended double-

precision and 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

SoftFloat.

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 extended double-precision and 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 single- and 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.  This work 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 TAKE FULL RESPONSIBILITY FOR ALL

LOSSES, COSTS, OR OTHER PROBLEMS THEY INCUR DUE TO THE SOFTWARE, AND WHO

FURTHERMORE EFFECTIVELY INDEMNIFY JOHN HAUSER AND THE INTERNATIONAL COMPUTER

SCIENCE INSTITUTE (possibly via similar legal warning) AGAINST ALL LOSSES,

COSTS, OR OTHER PROBLEMS INCURRED BY THEIR CUSTOMERS AND CLIENTS DUE TO THE

SOFTWARE.

Derivative works are acceptable, even for commercial purposes, provided

that 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

`--'.  The names of the supplied

target directories should be interpreted as follows:

  :

    386          - Intel 386-compatible processor.

    SPARC        - SPARC processor (as used by Sun computers).

  :

    Win32        - Microsoft Win32 executable.

    Solaris      - Sun Solaris executable.

  :

    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

`-.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 extended double-precision and

quadruple-precision formats to be enabled in the code.  Conversely, either

or both of the extended formats can be disabled by simply removing the

`#define' of the respective macro.  When an extended 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 single- and 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 IEC/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 (in Unix,

`softfloat.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.cs.berkeley.edu/~jhauser/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.cs.berkeley.edu/~jhauser/arithmetic/SoftFloat.html'.