Subversion Repositories fpu100

SoftFloat Release 2b General 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.  As many as four

formats are supported:  single precision, double precision, extended double

precision, and quadruple precision.  All operations required by the standard

are implemented, except for conversions to and from decimal.

This document gives information about the types defined and the routines

implemented by SoftFloat.  It does not attempt to define or explain the

IEC/IEEE Floating-Point Standard.  Details about the standard are available

elsewhere.

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

Limitations

SoftFloat is written in C and is designed to work with other C code.  The

SoftFloat header files assume an ISO/ANSI-style C compiler.  No attempt

has been made to accomodate compilers that are not ISO-conformant.  In

particular, the distributed header files will not be acceptable to any

compiler that does not recognize function prototypes.

Support for the extended double-precision and quadruple-precision formats

depends on a C compiler that implements 64-bit integer arithmetic.  If the

largest integer format supported by the C compiler is 32 bits, SoftFloat

is limited to only single and double precisions.  When that is the case,

all references in this document to extended double precision, quadruple

precision, and 64-bit integers should be ignored.

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

Contents

    Introduction

    Limitations

    Contents

    Legal Notice

    Types and Functions

    Rounding Modes

    Extended Double-Precision Rounding Precision

    Exceptions and Exception Flags

    Function Details

        Conversion Functions

        Standard Arithmetic Functions

        Remainder Functions

        Round-to-Integer Functions

        Comparison Functions

        Signaling NaN Test Functions

        Raise-Exception Function

    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.

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

Types and Functions

When 64-bit integers are supported by the compiler, the `softfloat.h'

header file defines four types:  `float32' (single precision), `float64'

(double precision), `floatx80' (extended double precision), and `float128'

(quadruple precision).  The `float32' and `float64' types are defined in

terms of 32-bit and 64-bit integer types, respectively, while the `float128'

type is defined as a structure of two 64-bit integers, taking into account

the byte order of the particular machine being used.  The `floatx80' type

is defined as a structure containing one 16-bit and one 64-bit integer, with

the machine's byte order again determining the order within the structure.

When 64-bit integers are _not_ supported by the compiler, the `softfloat.h'

header file defines only two types:  `float32' and `float64'.  Because

ISO/ANSI C guarantees at least one built-in integer type of 32 bits,

the `float32' type is identified with an appropriate integer type.  The

`float64' type is defined as a structure of two 32-bit integers, with the

machine's byte order determining the order of the fields.

In either case, the types in `softfloat.h' are defined such that if a system

implements the usual C `float' and `double' types according to the IEC/IEEE

Standard, then the `float32' and `float64' types should be indistinguishable

in memory from the native `float' and `double' types.  (On the other hand,

when `float32' or `float64' values are placed in processor registers by

the compiler, the type of registers used may differ from those used for the

native `float' and `double' types.)

SoftFloat implements the following arithmetic operations:

-- Conversions among all the floating-point formats, and also between

   integers (32-bit and 64-bit) and any of the floating-point formats.

-- The usual add, subtract, multiply, divide, and square root operations

   for all floating-point formats.

-- For each format, the floating-point remainder operation defined by the

   IEC/IEEE Standard.

-- For each floating-point format, a ``round to integer'' operation that

   rounds to the nearest integer value in the same format.  (The floating-

   point formats can hold integer values, of course.)

-- Comparisons between two values in the same floating-point format.

The only functions required by the IEC/IEEE Standard that are not provided

are conversions to and from decimal.

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

Rounding Modes

All four rounding modes prescribed by the IEC/IEEE Standard are implemented

for all operations that require rounding.  The rounding mode is selected

by the global variable `float_rounding_mode'.  This variable may be set

to one of the values `float_round_nearest_even', `float_round_to_zero',

`float_round_down', or `float_round_up'.  The rounding mode is initialized

to nearest/even.

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

Extended Double-Precision Rounding Precision

For extended double precision (`floatx80') only, the rounding precision

of the standard arithmetic operations is controlled by the global variable

`floatx80_rounding_precision'.  The operations affected are:

   floatx80_add   floatx80_sub   floatx80_mul   floatx80_div   floatx80_sqrt

When `floatx80_rounding_precision' is set to its default value of 80, these

operations are rounded (as usual) to the full precision of the extended

double-precision format.  Setting `floatx80_rounding_precision' to 32

or to 64 causes the operations listed to be rounded to reduced precision

equivalent to single precision (`float32') or to double precision

(`float64'), respectively.  When rounding to reduced precision, additional

bits in the result significand beyond the rounding point are set to zero.

The consequences of setting `floatx80_rounding_precision' to a value other

than 32, 64, or 80 is not specified.  Operations other than the ones listed

above are not affected by `floatx80_rounding_precision'.

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

Exceptions and Exception Flags

All five exception flags required by the IEC/IEEE Standard are

implemented.  Each flag is stored as a unique bit in the global variable

`float_exception_flags'.  The positions of the exception flag bits within

this variable are determined by the bit masks `float_flag_inexact',

`float_flag_underflow', `float_flag_overflow', `float_flag_divbyzero', and

`float_flag_invalid'.  The exception flags variable is initialized to all 0,

meaning no exceptions.

An individual exception flag can be cleared with the statement

    float_exception_flags &= ~ float_flag_;

where `' is the appropriate name.  To raise a floating-point

exception, the SoftFloat function `float_raise' should be used (see below).

In the terminology of the IEC/IEEE Standard, SoftFloat can detect tininess

for underflow either before or after rounding.  The choice is made by

the global variable `float_detect_tininess', which can be set to either

`float_tininess_before_rounding' or `float_tininess_after_rounding'.

Detecting tininess after rounding is better because it results in fewer

spurious underflow signals.  The other option is provided for compatibility

with some systems.  Like most systems, SoftFloat always detects loss of

accuracy for underflow as an inexact result.

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

Function Details

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

Conversion Functions

All conversions among the floating-point formats are supported, as are all

conversions between a floating-point format and 32-bit and 64-bit signed

integers.  The complete set of conversion functions is:

   int32_to_float32      int64_to_float32

   int32_to_float64      int64_to_float32

   int32_to_floatx80     int64_to_floatx80

   int32_to_float128     int64_to_float128

   float32_to_int32      float32_to_int64

   float32_to_int32      float64_to_int64

   floatx80_to_int32     floatx80_to_int64

   float128_to_int32     float128_to_int64

   float32_to_float64    float32_to_floatx80   float32_to_float128

   float64_to_float32    float64_to_floatx80   float64_to_float128

   floatx80_to_float32   floatx80_to_float64   floatx80_to_float128

   float128_to_float32   float128_to_float64   float128_to_floatx80

Each conversion function takes one operand of the appropriate type and

returns one result.  Conversions from a smaller to a larger floating-point

format are always exact and so require no rounding.  Conversions from 32-bit

integers to double precision and larger formats are also exact, and likewise

for conversions from 64-bit integers to extended double and quadruple

precisions.

Conversions from floating-point to integer raise the invalid exception if

the source value cannot be rounded to a representable integer of the desired

size (32 or 64 bits).  If the floating-point operand is a NaN, the largest

positive integer is returned.  Otherwise, if the conversion overflows, the

largest integer with the same sign as the operand is returned.

On conversions to integer, if the floating-point operand is not already

an integer value, the operand is rounded according to the current rounding

mode as specified by `float_rounding_mode'.  Because C (and perhaps other

languages) require that conversions to integers be rounded toward zero, the

following functions are provided for improved speed and convenience:

   float32_to_int32_round_to_zero    float32_to_int64_round_to_zero

   float64_to_int32_round_to_zero    float64_to_int64_round_to_zero

   floatx80_to_int32_round_to_zero   floatx80_to_int64_round_to_zero

   float128_to_int32_round_to_zero   float128_to_int64_round_to_zero

These variant functions ignore `float_rounding_mode' and always round toward

zero.

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

Standard Arithmetic Functions

The following standard arithmetic functions are provided:

   float32_add    float32_sub    float32_mul    float32_div    float32_sqrt

   float64_add    float64_sub    float64_mul    float64_div    float64_sqrt

   floatx80_add   floatx80_sub   floatx80_mul   floatx80_div   floatx80_sqrt

   float128_add   float128_sub   float128_mul   float128_div   float128_sqrt

Each function takes two operands, except for `sqrt' which takes only one.

The operands and result are all of the same type.

Rounding of the extended double-precision (`floatx80') functions is affected

by the `floatx80_rounding_precision' variable, as explained above in the

section _Extended Double-Precision Rounding Precision_.

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

Remainder Functions

For each format, SoftFloat implements the remainder function according to

the IEC/IEEE Standard.  The remainder functions are:

   float32_rem

   float64_rem

   floatx80_rem

   float128_rem

Each remainder function takes two operands.  The operands and result are all

of the same type.  Given operands x and y, the remainder functions return

the value x - n*y, where n is the integer closest to x/y.  If x/y is exactly

halfway between two integers, n is the even integer closest to x/y.  The

remainder functions are always exact and so require no rounding.

Depending on the relative magnitudes of the operands, the remainder

functions can take considerably longer to execute than the other SoftFloat

functions.  This is inherent in the remainder operation itself and is not a

flaw in the SoftFloat implementation.

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

Round-to-Integer Functions

For each format, SoftFloat implements the round-to-integer function

specified by the IEC/IEEE Standard.  The functions are:

   float32_round_to_int

   float64_round_to_int

   floatx80_round_to_int

   float128_round_to_int

Each function takes a single floating-point operand and returns a result of

the same type.  (Note that the result is not an integer type.)  The operand

is rounded to an exact integer according to the current rounding mode, and

the resulting integer value is returned in the same floating-point format.

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

Comparison Functions

The following floating-point comparison functions are provided:

   float32_eq    float32_le    float32_lt

   float64_eq    float64_le    float64_lt

   floatx80_eq   floatx80_le   floatx80_lt

   float128_eq   float128_le   float128_lt

Each function takes two operands of the same type and returns a 1 or 0

representing either _true_ or _false_.  The abbreviation `eq' stands for

``equal'' (=); `le' stands for ``less than or equal'' (<=); and `lt' stands

for ``less than'' (<).

The standard greater-than (>), greater-than-or-equal (>=), and not-equal

(!=) functions are easily obtained using the functions provided.  The

not-equal function is just the logical complement of the equal function.

The greater-than-or-equal function is identical to the less-than-or-equal

function with the operands reversed, and the greater-than function is

identical to the less-than function with the operands reversed.

The IEC/IEEE Standard specifies that the less-than-or-equal and less-than

functions raise the invalid exception if either input is any kind of NaN.

The equal functions, on the other hand, are defined not to raise the invalid

exception on quiet NaNs.  For completeness, SoftFloat provides the following

additional functions:

   float32_eq_signaling    float32_le_quiet    float32_lt_quiet

   float64_eq_signaling    float64_le_quiet    float64_lt_quiet

   floatx80_eq_signaling   floatx80_le_quiet   floatx80_lt_quiet

   float128_eq_signaling   float128_le_quiet   float128_lt_quiet

The `signaling' equal functions are identical to the standard functions

except that the invalid exception is raised for any NaN input.  Likewise,

the `quiet' comparison functions are identical to their counterparts except

that the invalid exception is not raised for quiet NaNs.

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

Signaling NaN Test Functions

The following functions test whether a floating-point value is a signaling

NaN:

   float32_is_signaling_nan

   float64_is_signaling_nan

   floatx80_is_signaling_nan

   float128_is_signaling_nan

The functions take one operand and return 1 if the operand is a signaling

NaN and 0 otherwise.

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

Raise-Exception Function

SoftFloat provides a function for raising floating-point exceptions:

    float_raise

The function takes a mask indicating the set of exceptions to raise.  No

result is returned.  In addition to setting the specified exception flags,

this function may cause a trap or abort appropriate for the current system.

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

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

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