ArmPlatformPkg/PrePeiCoreMPCore: use a unique GUID

[mirror_edk2.git] / StdLib / LibC / Softfloat / softfloat-source.txt

$NetBSD: softfloat-source.txt,v 1.2 2006/11/24 19:46:58 christos Exp $\r
\r
SoftFloat Release 2a Source Documentation\r
\r
John R. Hauser\r
1998 December 14\r
\r
\r
-------------------------------------------------------------------------------\r
Introduction\r
\r
SoftFloat is a software implementation of floating-point that conforms to\r
the IEC/IEEE Standard for Binary Floating-Point Arithmetic.  SoftFloat can\r
support four floating-point formats:  single precision, double precision,\r
extended double precision, and quadruple precision.  All operations required\r
by the IEEE Standard are implemented, except for conversions to and from\r
decimal.  SoftFloat is distributed in the form of C source code, so a\r
C compiler is needed to compile the code.  Support for the extended double-\r
precision and quadruple-precision formats is dependent on the C compiler\r
implementing a 64-bit integer type.\r
\r
This document gives information needed for compiling and/or porting\r
SoftFloat.\r
\r
The source code for SoftFloat is intended to be relatively machine-\r
independent and should be compilable using any ISO/ANSI C compiler.  At the\r
time of this writing, SoftFloat has been successfully compiled with the GNU\r
C Compiler (`gcc') for several platforms.\r
\r
\r
-------------------------------------------------------------------------------\r
Limitations\r
\r
SoftFloat as written requires an ISO/ANSI-style C compiler.  No attempt has\r
been made to accommodate compilers that are not ISO-conformant.  Older ``K&R-\r
style'' compilers are not adequate for compiling SoftFloat.  All testing I\r
have done so far has been with the GNU C Compiler.  Compilation with other\r
compilers should be possible but has not been tested.\r
\r
The SoftFloat sources assume that source code file names can be longer than\r
8 characters.  In order to compile under an MS-DOS-type system, many of the\r
source files will need to be renamed, and the source and makefiles edited\r
appropriately.  Once compiled, the SoftFloat binary does not depend on the\r
existence of long file names.\r
\r
The underlying machine is assumed to be binary with a word size that is a\r
power of 2.  Bytes are 8 bits.  Support for the extended double-precision\r
and quadruple-precision formats depends on the C compiler implementing\r
a 64-bit integer type.  If the largest integer type supported by the\r
C compiler is 32 bits, SoftFloat is limited to the single- and double-\r
precision formats.\r
\r
\r
-------------------------------------------------------------------------------\r
Contents\r
\r
    Introduction\r
    Limitations\r
    Contents\r
    Legal Notice\r
    SoftFloat Source Directory Structure\r
    SoftFloat Source Files\r
        processors/*.h\r
        softfloat/bits*/*/softfloat.h\r
        softfloat/bits*/*/milieu.h\r
        softfloat/bits*/*/softfloat-specialize\r
        softfloat/bits*/softfloat-macros\r
        softfloat/bits*/softfloat.c\r
    Steps to Creating a `softfloat.o'\r
    Making `softfloat.o' a Library\r
    Testing SoftFloat\r
    Timing SoftFloat\r
    Compiler Options and Efficiency\r
    Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'\r
    Contact Information\r
\r
\r
\r
-------------------------------------------------------------------------------\r
Legal Notice\r
\r
SoftFloat was written by John R. Hauser.  This work was made possible in\r
part by the International Computer Science Institute, located at Suite 600,\r
1947 Center Street, Berkeley, California 94704.  Funding was partially\r
provided by the National Science Foundation under grant MIP-9311980.  The\r
original version of this code was written as part of a project to build\r
a fixed-point vector processor in collaboration with the University of\r
California at Berkeley, overseen by Profs. Nelson Morgan and John Wawrzynek.\r
\r
THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE.  Although reasonable effort\r
has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT\r
TIMES RESULT IN INCORRECT BEHAVIOR.  USE OF THIS SOFTWARE IS RESTRICTED TO\r
PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY\r
AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE.\r
\r
\r
-------------------------------------------------------------------------------\r
SoftFloat Source Directory Structure\r
\r
Because SoftFloat is targeted to multiple platforms, its source code\r
is slightly scattered between target-specific and target-independent\r
directories and files.  The directory structure is as follows:\r
\r
    processors\r
    softfloat\r
        bits64\r
            templates\r
            386-Win32-gcc\r
            SPARC-Solaris-gcc\r
        bits32\r
            templates\r
            386-Win32-gcc\r
            SPARC-Solaris-gcc\r
\r
The two topmost directories and their contents are:\r
\r
    softfloat    - Most of the source code needed for SoftFloat.\r
    processors   - Target-specific header files that are not specific to\r
                       SoftFloat.\r
\r
The `softfloat' directory is further split into two parts:\r
\r
    bits64       - SoftFloat implementation using 64-bit integers.\r
    bits32       - SoftFloat implementation using only 32-bit integers.\r
\r
Within these directories are subdirectories for each of the targeted\r
platforms.  The SoftFloat source code is distributed with targets\r
`386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already\r
prepared for both the 32-bit and 64-bit implementations.  Source files that\r
are not within these target-specific subdirectories are intended to be\r
target-independent.\r
\r
The naming convention used for the target-specific directories is\r
`<processor>-<executable-type>-<compiler>'.  The names of the supplied\r
target directories should be interpreted as follows:\r
\r
  <processor>:\r
    386          - Intel 386-compatible processor.\r
    SPARC        - SPARC processor (as used by Sun machines).\r
  <executable-type>:\r
    Win32        - Microsoft Win32 executable.\r
    Solaris      - Sun Solaris executable.\r
  <compiler>:\r
    gcc          - GNU C Compiler.\r
\r
You do not need to maintain this convention if you do not want to.\r
\r
Alongside the supplied target-specific directories is a `templates'\r
directory containing a set of ``generic'' target-specific source files.  A\r
new target directory can be created by copying the `templates' directory and\r
editing the files inside.  (Complete instructions for porting SoftFloat to a\r
new target are in the section _Steps_to_Creating_a_`softfloat.o'_.)  Note\r
that the `templates' directory will not work as a target directory without\r
some editing.  To avoid confusion, it would be wise to refrain from editing\r
the files inside `templates' directly.\r
\r
\r
-------------------------------------------------------------------------------\r
SoftFloat Source Files\r
\r
The purpose of each source file is described below.  In the following,\r
the `*' symbol is used in place of the name of a specific target, such as\r
`386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some other text, as\r
in `bits*' for either `bits32' or `bits64'.\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
processors/*.h\r
\r
The target-specific `processors' header file defines integer types\r
of various sizes, and also defines certain C preprocessor macros that\r
characterize the target.  The two examples supplied are `386-gcc.h' and\r
`SPARC-gcc.h'.  The naming convention used for processor header files is\r
`<processor>-<compiler>.h'.\r
\r
If 64-bit integers are supported by the compiler, the macro name `BITS64'\r
should be defined here along with the corresponding 64-bit integer\r
types.  In addition, the function-like macro `LIT64' must be defined for\r
constructing 64-bit integer literals (constants).  The `LIT64' macro is used\r
consistently in the SoftFloat code to annotate 64-bit literals.\r
\r
If `BITS64' is not defined, only the 32-bit version of SoftFloat can be\r
compiled.  If `BITS64' _is_ defined, either can be compiled.\r
\r
If an inlining attribute (such as an `inline' keyword) is provided by the\r
compiler, the macro `INLINE' should be defined to the appropriate keyword.\r
If not, `INLINE' can be set to the keyword `static'.  The `INLINE' macro\r
appears in the SoftFloat source code before every function that should\r
be inlined by the compiler.  SoftFloat depends on inlining to obtain\r
good speed.  Even if inlining cannot be forced with a language keyword,\r
the compiler may still be able to perform inlining on its own as an\r
optimization.  If a command-line option is needed to convince the compiler\r
to perform this optimization, this should be assured in the makefile.  (See\r
the section _Compiler_Options_and_Efficiency_ below.)\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
softfloat/bits*/*/softfloat.h\r
\r
The target-specific `softfloat.h' header file defines the SoftFloat\r
interface as seen by clients.\r
\r
Unlike the actual function definitions in `softfloat.c', the declarations\r
in `softfloat.h' do not use any of the types defined by the `processors'\r
header file.  This is done so that clients will not have to include the\r
`processors' header file in order to use SoftFloat.  Nevertheless, the\r
target-specific declarations in `softfloat.h' must match what `softfloat.c'\r
expects.  For example, if `int32' is defined as `int' in the `processors'\r
header file, then in `softfloat.h' the output of `float32_to_int32' should\r
be stated as `int', although in `softfloat.c' it is given in target-\r
independent form as `int32'.\r
\r
For the `bits64' implementation of SoftFloat, the macro names `FLOATX80' and\r
`FLOAT128' must be defined in order for the extended double-precision and\r
quadruple-precision formats to be enabled in the code.  Conversely, either\r
or both of the extended formats can be disabled by simply removing the\r
`#define' of the respective macro.  When an extended format is not enabled,\r
none of the functions that either input or output the format are defined,\r
and no space is taken up in `softfloat.o' by such functions.  There is no\r
provision for disabling the usual single- and double-precision formats.\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
softfloat/bits*/*/milieu.h\r
\r
The target-specific `milieu.h' header file provides declarations that are\r
needed to compile SoftFloat.  In addition, deviations from ISO/ANSI C by\r
the compiler (such as names not properly declared in system header files)\r
are corrected in this header if possible.\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
softfloat/bits*/*/softfloat-specialize\r
\r
This target-specific C source fragment defines:\r
\r
-- whether tininess for underflow is detected before or after rounding by\r
       default;\r
-- what (if anything) special happens when exceptions are raised;\r
-- how signaling NaNs are distinguished from quiet NaNs;\r
-- the default generated quiet NaNs; and\r
-- how NaNs are propagated from function inputs to output.\r
\r
These details are not decided by the IEC/IEEE Standard.  This fragment is\r
included verbatim within `softfloat.c' when SoftFloat is compiled.\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
softfloat/bits*/softfloat-macros\r
\r
This target-independent C source fragment defines a number of arithmetic\r
functions used as primitives within the `softfloat.c' source.  Most of the\r
functions defined here are intended to be inlined for efficiency.  This\r
fragment is included verbatim within `softfloat.c' when SoftFloat is\r
compiled.\r
\r
Target-specific variations on this file are possible.  See the section\r
_Processor-Specific_Optimization_of_`softfloat.c'_Using_`softfloat-macros'_\r
below.\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
softfloat/bits*/softfloat.c\r
\r
The target-independent `softfloat.c' source file contains the body of the\r
SoftFloat implementation.\r
\r
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r
\r
The inclusion of the files above within each other (using `#include') can be\r
shown graphically as follows:\r
\r
    softfloat/bits*/softfloat.c\r
        softfloat/bits*/*/milieu.h\r
            processors/*.h\r
        softfloat/bits*/*/softfloat.h\r
        softfloat/bits*/*/softfloat-specialize\r
        softfloat/bits*/softfloat-macros\r
\r
Note in particular that `softfloat.c' does not include the `processors'\r
header file directly.  Rather, `softfloat.c' includes the target-specific\r
`milieu.h' header file, which in turn includes the processor header file.\r
\r
\r
-------------------------------------------------------------------------------\r
Steps to Creating a `softfloat.o'\r
\r
Porting and/or compiling SoftFloat involves the following steps:\r
\r
1. If one does not already exist, create an appropriate `.h' file in the\r
   `processors' directory.\r
\r
2. If `BITS64' is defined in the `processors' header file, choose whether\r
   to compile the 32-bit or 64-bit implementation of SoftFloat.  If\r
   `BITS64' is not defined, your only choice is the 32-bit implementation.\r
   The remaining steps occur within either the `bits32' or `bits64'\r
   subdirectories.\r
\r
3. If one does not already exist, create an appropriate target-specific\r
   subdirectory by copying the given `templates' directory.\r
\r
4. In the target-specific subdirectory, edit the files `softfloat-specialize'\r
   and `softfloat.h' to define the desired exception handling functions\r
   and mode control values.  In the `softfloat.h' header file, ensure also\r
   that all declarations give the proper target-specific type (such as\r
   `int' or `long') corresponding to the target-independent type used in\r
   `softfloat.c' (such as `int32').  None of the type names declared in the\r
   `processors' header file should appear in `softfloat.h'.\r
\r
5. In the target-specific subdirectory, edit the files `milieu.h' and\r
   `Makefile' to reflect the current environment.\r
\r
6. In the target-specific subdirectory, execute `make'.\r
\r
For the targets that are supplied, if the expected compiler is available\r
(usually `gcc'), it should only be necessary to execute `make' in the\r
target-specific subdirectory.\r
\r
\r
-------------------------------------------------------------------------------\r
Making `softfloat.o' a Library\r
\r
SoftFloat is not made into a software library by the supplied makefile.\r
If desired, `softfloat.o' can easily be put into its own library (in Unix,\r
`softfloat.a') using the usual system tool (in Unix, `ar').\r
\r
\r
-------------------------------------------------------------------------------\r
Testing SoftFloat\r
\r
SoftFloat can be tested using the `testsoftfloat' program by the same\r
author.  The `testsoftfloat' program is part of the TestFloat package\r
available at the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/\r
TestFloat.html'.\r
\r
\r
-------------------------------------------------------------------------------\r
Timing SoftFloat\r
\r
A program called `timesoftfloat' for timing the SoftFloat functions is\r
included with the SoftFloat source code.  Compiling `timesoftfloat' should\r
pose no difficulties once `softfloat.o' exists.  The supplied makefile\r
will create a `timesoftfloat' executable by default after generating\r
`softfloat.o'.  See `timesoftfloat.txt' for documentation about using\r
`timesoftfloat'.\r
\r
\r
-------------------------------------------------------------------------------\r
Compiler Options and Efficiency\r
\r
In order to get good speed with SoftFloat, it is important that the compiler\r
inline the routines that have been marked `INLINE' in the code.  Even if\r
inlining cannot be forced by an appropriate definition of the `INLINE'\r
macro, the compiler may still be able to perform inlining on its own as\r
an optimization.  In that case, the makefile should be edited to give the\r
compiler whatever option is required to cause it to inline small functions.\r
\r
The ability of the processor to do fast shifts has been assumed.  Efficiency\r
will not be as good on processors for which this is not the case (such as\r
the original Motorola 68000 or Intel 8086 processors).\r
\r
\r
-------------------------------------------------------------------------------\r
Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'\r
\r
The `softfloat-macros' source fragment defines arithmetic functions used\r
as primitives by `softfloat.c'.  This file has been written in a target-\r
independent form.  For a given target, it may be possible to improve on\r
these functions using target-specific and/or non-ISO-C features (such\r
as `asm' statements).  For example, one of the ``macro'' functions takes\r
two word-size integers and returns their full product in two words.\r
This operation can be done directly in hardware on many processors; but\r
because it is not available through standard C, the function defined in\r
`softfloat-macros' uses four multiplies to achieve the same result.\r
\r
To address these shortcomings, a customized version of `softfloat-macros'\r
can be created in any of the target-specific subdirectories.  A simple\r
modification to the target's makefile should be sufficient to ensure that\r
the custom version is used instead of the generic one.\r
\r
\r
-------------------------------------------------------------------------------\r
Contact Information\r
\r
At the time of this writing, the most up-to-date information about\r
SoftFloat and the latest release can be found at the Web page `http://\r
HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.\r
\r
\r