mirror of
https://github.com/cc65/cc65.git
synced 2024-11-03 10:07:02 +00:00
401 lines
18 KiB
Plaintext
401 lines
18 KiB
Plaintext
|
|
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'.
|
|
|