+++ /dev/null
-$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
projects / mirror_edk2.git / blobdiff