StdLib/LibC/Softfloat/softfloat-source.txt

   1 $NetBSD: softfloat-source.txt,v 1.2 2006/11/24 19:46:58 christos Exp $
   2
   3 SoftFloat Release 2a Source Documentation
   4
   5 John R. Hauser
   6 1998 December 14
   7
   8
   9 -------------------------------------------------------------------------------
  10 Introduction
  11
  12 SoftFloat is a software implementation of floating-point that conforms to
  13 the IEC/IEEE Standard for Binary Floating-Point Arithmetic.  SoftFloat can
  14 support four floating-point formats:  single precision, double precision,
  15 extended double precision, and quadruple precision.  All operations required
  16 by the IEEE Standard are implemented, except for conversions to and from
  17 decimal.  SoftFloat is distributed in the form of C source code, so a
  18 C compiler is needed to compile the code.  Support for the extended double-
  19 precision and quadruple-precision formats is dependent on the C compiler
  20 implementing a 64-bit integer type.
  21
  22 This document gives information needed for compiling and/or porting
  23 SoftFloat.
  24
  25 The source code for SoftFloat is intended to be relatively machine-
  26 independent and should be compilable using any ISO/ANSI C compiler.  At the
  27 time of this writing, SoftFloat has been successfully compiled with the GNU
  28 C Compiler (`gcc') for several platforms.
  29
  30
  31 -------------------------------------------------------------------------------
  32 Limitations
  33
  34 SoftFloat as written requires an ISO/ANSI-style C compiler.  No attempt has
  35 been made to accommodate compilers that are not ISO-conformant.  Older ``K&R-
  36 style'' compilers are not adequate for compiling SoftFloat.  All testing I
  37 have done so far has been with the GNU C Compiler.  Compilation with other
  38 compilers should be possible but has not been tested.
  39
  40 The SoftFloat sources assume that source code file names can be longer than
  41 8 characters.  In order to compile under an MS-DOS-type system, many of the
  42 source files will need to be renamed, and the source and makefiles edited
  43 appropriately.  Once compiled, the SoftFloat binary does not depend on the
  44 existence of long file names.
  45
  46 The underlying machine is assumed to be binary with a word size that is a
  47 power of 2.  Bytes are 8 bits.  Support for the extended double-precision
  48 and quadruple-precision formats depends on the C compiler implementing
  49 a 64-bit integer type.  If the largest integer type supported by the
  50 C compiler is 32 bits, SoftFloat is limited to the single- and double-
  51 precision formats.
  52
  53
  54 -------------------------------------------------------------------------------
  55 Contents
  56
  57     Introduction
  58     Limitations
  59     Contents
  60     Legal Notice
  61     SoftFloat Source Directory Structure
  62     SoftFloat Source Files
  63         processors/*.h
  64         softfloat/bits*/*/softfloat.h
  65         softfloat/bits*/*/milieu.h
  66         softfloat/bits*/*/softfloat-specialize
  67         softfloat/bits*/softfloat-macros
  68         softfloat/bits*/softfloat.c
  69     Steps to Creating a `softfloat.o'
  70     Making `softfloat.o' a Library
  71     Testing SoftFloat
  72     Timing SoftFloat
  73     Compiler Options and Efficiency
  74     Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'
  75     Contact Information
  76
  77
  78
  79 -------------------------------------------------------------------------------
  80 Legal Notice
  81
  82 SoftFloat was written by John R. Hauser.  This work was made possible in
  83 part by the International Computer Science Institute, located at Suite 600,
  84 1947 Center Street, Berkeley, California 94704.  Funding was partially
  85 provided by the National Science Foundation under grant MIP-9311980.  The
  86 original version of this code was written as part of a project to build
  87 a fixed-point vector processor in collaboration with the University of
  88 California at Berkeley, overseen by Profs. Nelson Morgan and John Wawrzynek.
  89
  90 THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE.  Although reasonable effort
  91 has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT
  92 TIMES RESULT IN INCORRECT BEHAVIOR.  USE OF THIS SOFTWARE IS RESTRICTED TO
  93 PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY
  94 AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE.
  95
  96
  97 -------------------------------------------------------------------------------
  98 SoftFloat Source Directory Structure
  99
 100 Because SoftFloat is targeted to multiple platforms, its source code
 101 is slightly scattered between target-specific and target-independent
 102 directories and files.  The directory structure is as follows:
 103
 104     processors
 105     softfloat
 106         bits64
 107             templates
 108             386-Win32-gcc
 109             SPARC-Solaris-gcc
 110         bits32
 111             templates
 112             386-Win32-gcc
 113             SPARC-Solaris-gcc
 114
 115 The two topmost directories and their contents are:
 116
 117     softfloat    - Most of the source code needed for SoftFloat.
 118     processors   - Target-specific header files that are not specific to
 119                        SoftFloat.
 120
 121 The `softfloat' directory is further split into two parts:
 122
 123     bits64       - SoftFloat implementation using 64-bit integers.
 124     bits32       - SoftFloat implementation using only 32-bit integers.
 125
 126 Within these directories are subdirectories for each of the targeted
 127 platforms.  The SoftFloat source code is distributed with targets
 128 `386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already
 129 prepared for both the 32-bit and 64-bit implementations.  Source files that
 130 are not within these target-specific subdirectories are intended to be
 131 target-independent.
 132
 133 The naming convention used for the target-specific directories is
 134 `<processor>-<executable-type>-<compiler>'.  The names of the supplied
 135 target directories should be interpreted as follows:
 136
 137   <processor>:
 138     386          - Intel 386-compatible processor.
 139     SPARC        - SPARC processor (as used by Sun machines).
 140   <executable-type>:
 141     Win32        - Microsoft Win32 executable.
 142     Solaris      - Sun Solaris executable.
 143   <compiler>:
 144     gcc          - GNU C Compiler.
 145
 146 You do not need to maintain this convention if you do not want to.
 147
 148 Alongside the supplied target-specific directories is a `templates'
 149 directory containing a set of ``generic'' target-specific source files.  A
 150 new target directory can be created by copying the `templates' directory and
 151 editing the files inside.  (Complete instructions for porting SoftFloat to a
 152 new target are in the section _Steps_to_Creating_a_`softfloat.o'_.)  Note
 153 that the `templates' directory will not work as a target directory without
 154 some editing.  To avoid confusion, it would be wise to refrain from editing
 155 the files inside `templates' directly.
 156
 157
 158 -------------------------------------------------------------------------------
 159 SoftFloat Source Files
 160
 161 The purpose of each source file is described below.  In the following,
 162 the `*' symbol is used in place of the name of a specific target, such as
 163 `386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some other text, as
 164 in `bits*' for either `bits32' or `bits64'.
 165
 166 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 167 processors/*.h
 168
 169 The target-specific `processors' header file defines integer types
 170 of various sizes, and also defines certain C preprocessor macros that
 171 characterize the target.  The two examples supplied are `386-gcc.h' and
 172 `SPARC-gcc.h'.  The naming convention used for processor header files is
 173 `<processor>-<compiler>.h'.
 174
 175 If 64-bit integers are supported by the compiler, the macro name `BITS64'
 176 should be defined here along with the corresponding 64-bit integer
 177 types.  In addition, the function-like macro `LIT64' must be defined for
 178 constructing 64-bit integer literals (constants).  The `LIT64' macro is used
 179 consistently in the SoftFloat code to annotate 64-bit literals.
 180
 181 If `BITS64' is not defined, only the 32-bit version of SoftFloat can be
 182 compiled.  If `BITS64' _is_ defined, either can be compiled.
 183
 184 If an inlining attribute (such as an `inline' keyword) is provided by the
 185 compiler, the macro `INLINE' should be defined to the appropriate keyword.
 186 If not, `INLINE' can be set to the keyword `static'.  The `INLINE' macro
 187 appears in the SoftFloat source code before every function that should
 188 be inlined by the compiler.  SoftFloat depends on inlining to obtain
 189 good speed.  Even if inlining cannot be forced with a language keyword,
 190 the compiler may still be able to perform inlining on its own as an
 191 optimization.  If a command-line option is needed to convince the compiler
 192 to perform this optimization, this should be assured in the makefile.  (See
 193 the section _Compiler_Options_and_Efficiency_ below.)
 194
 195 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 196 softfloat/bits*/*/softfloat.h
 197
 198 The target-specific `softfloat.h' header file defines the SoftFloat
 199 interface as seen by clients.
 200
 201 Unlike the actual function definitions in `softfloat.c', the declarations
 202 in `softfloat.h' do not use any of the types defined by the `processors'
 203 header file.  This is done so that clients will not have to include the
 204 `processors' header file in order to use SoftFloat.  Nevertheless, the
 205 target-specific declarations in `softfloat.h' must match what `softfloat.c'
 206 expects.  For example, if `int32' is defined as `int' in the `processors'
 207 header file, then in `softfloat.h' the output of `float32_to_int32' should
 208 be stated as `int', although in `softfloat.c' it is given in target-
 209 independent form as `int32'.
 210
 211 For the `bits64' implementation of SoftFloat, the macro names `FLOATX80' and
 212 `FLOAT128' must be defined in order for the extended double-precision and
 213 quadruple-precision formats to be enabled in the code.  Conversely, either
 214 or both of the extended formats can be disabled by simply removing the
 215 `#define' of the respective macro.  When an extended format is not enabled,
 216 none of the functions that either input or output the format are defined,
 217 and no space is taken up in `softfloat.o' by such functions.  There is no
 218 provision for disabling the usual single- and double-precision formats.
 219
 220 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 221 softfloat/bits*/*/milieu.h
 222
 223 The target-specific `milieu.h' header file provides declarations that are
 224 needed to compile SoftFloat.  In addition, deviations from ISO/ANSI C by
 225 the compiler (such as names not properly declared in system header files)
 226 are corrected in this header if possible.
 227
 228 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 229 softfloat/bits*/*/softfloat-specialize
 230
 231 This target-specific C source fragment defines:
 232
 233 -- whether tininess for underflow is detected before or after rounding by
 234        default;
 235 -- what (if anything) special happens when exceptions are raised;
 236 -- how signaling NaNs are distinguished from quiet NaNs;
 237 -- the default generated quiet NaNs; and
 238 -- how NaNs are propagated from function inputs to output.
 239
 240 These details are not decided by the IEC/IEEE Standard.  This fragment is
 241 included verbatim within `softfloat.c' when SoftFloat is compiled.
 242
 243 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 244 softfloat/bits*/softfloat-macros
 245
 246 This target-independent C source fragment defines a number of arithmetic
 247 functions used as primitives within the `softfloat.c' source.  Most of the
 248 functions defined here are intended to be inlined for efficiency.  This
 249 fragment is included verbatim within `softfloat.c' when SoftFloat is
 250 compiled.
 251
 252 Target-specific variations on this file are possible.  See the section
 253 _Processor-Specific_Optimization_of_`softfloat.c'_Using_`softfloat-macros'_
 254 below.
 255
 256 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 257 softfloat/bits*/softfloat.c
 258
 259 The target-independent `softfloat.c' source file contains the body of the
 260 SoftFloat implementation.
 261
 262 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 263
 264 The inclusion of the files above within each other (using `#include') can be
 265 shown graphically as follows:
 266
 267     softfloat/bits*/softfloat.c
 268         softfloat/bits*/*/milieu.h
 269             processors/*.h
 270         softfloat/bits*/*/softfloat.h
 271         softfloat/bits*/*/softfloat-specialize
 272         softfloat/bits*/softfloat-macros
 273
 274 Note in particular that `softfloat.c' does not include the `processors'
 275 header file directly.  Rather, `softfloat.c' includes the target-specific
 276 `milieu.h' header file, which in turn includes the processor header file.
 277
 278
 279 -------------------------------------------------------------------------------
 280 Steps to Creating a `softfloat.o'
 281
 282 Porting and/or compiling SoftFloat involves the following steps:
 283
 284 1. If one does not already exist, create an appropriate `.h' file in the
 285    `processors' directory.
 286
 287 2. If `BITS64' is defined in the `processors' header file, choose whether
 288    to compile the 32-bit or 64-bit implementation of SoftFloat.  If
 289    `BITS64' is not defined, your only choice is the 32-bit implementation.
 290    The remaining steps occur within either the `bits32' or `bits64'
 291    subdirectories.
 292
 293 3. If one does not already exist, create an appropriate target-specific
 294    subdirectory by copying the given `templates' directory.
 295
 296 4. In the target-specific subdirectory, edit the files `softfloat-specialize'
 297    and `softfloat.h' to define the desired exception handling functions
 298    and mode control values.  In the `softfloat.h' header file, ensure also
 299    that all declarations give the proper target-specific type (such as
 300    `int' or `long') corresponding to the target-independent type used in
 301    `softfloat.c' (such as `int32').  None of the type names declared in the
 302    `processors' header file should appear in `softfloat.h'.
 303
 304 5. In the target-specific subdirectory, edit the files `milieu.h' and
 305    `Makefile' to reflect the current environment.
 306
 307 6. In the target-specific subdirectory, execute `make'.
 308
 309 For the targets that are supplied, if the expected compiler is available
 310 (usually `gcc'), it should only be necessary to execute `make' in the
 311 target-specific subdirectory.
 312
 313
 314 -------------------------------------------------------------------------------
 315 Making `softfloat.o' a Library
 316
 317 SoftFloat is not made into a software library by the supplied makefile.
 318 If desired, `softfloat.o' can easily be put into its own library (in Unix,
 319 `softfloat.a') using the usual system tool (in Unix, `ar').
 320
 321
 322 -------------------------------------------------------------------------------
 323 Testing SoftFloat
 324
 325 SoftFloat can be tested using the `testsoftfloat' program by the same
 326 author.  The `testsoftfloat' program is part of the TestFloat package
 327 available at the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/
 328 TestFloat.html'.
 329
 330
 331 -------------------------------------------------------------------------------
 332 Timing SoftFloat
 333
 334 A program called `timesoftfloat' for timing the SoftFloat functions is
 335 included with the SoftFloat source code.  Compiling `timesoftfloat' should
 336 pose no difficulties once `softfloat.o' exists.  The supplied makefile
 337 will create a `timesoftfloat' executable by default after generating
 338 `softfloat.o'.  See `timesoftfloat.txt' for documentation about using
 339 `timesoftfloat'.
 340
 341
 342 -------------------------------------------------------------------------------
 343 Compiler Options and Efficiency
 344
 345 In order to get good speed with SoftFloat, it is important that the compiler
 346 inline the routines that have been marked `INLINE' in the code.  Even if
 347 inlining cannot be forced by an appropriate definition of the `INLINE'
 348 macro, the compiler may still be able to perform inlining on its own as
 349 an optimization.  In that case, the makefile should be edited to give the
 350 compiler whatever option is required to cause it to inline small functions.
 351
 352 The ability of the processor to do fast shifts has been assumed.  Efficiency
 353 will not be as good on processors for which this is not the case (such as
 354 the original Motorola 68000 or Intel 8086 processors).
 355
 356
 357 -------------------------------------------------------------------------------
 358 Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'
 359
 360 The `softfloat-macros' source fragment defines arithmetic functions used
 361 as primitives by `softfloat.c'.  This file has been written in a target-
 362 independent form.  For a given target, it may be possible to improve on
 363 these functions using target-specific and/or non-ISO-C features (such
 364 as `asm' statements).  For example, one of the ``macro'' functions takes
 365 two word-size integers and returns their full product in two words.
 366 This operation can be done directly in hardware on many processors; but
 367 because it is not available through standard C, the function defined in
 368 `softfloat-macros' uses four multiplies to achieve the same result.
 369
 370 To address these shortcomings, a customized version of `softfloat-macros'
 371 can be created in any of the target-specific subdirectories.  A simple
 372 modification to the target's makefile should be sufficient to ensure that
 373 the custom version is used instead of the generic one.
 374
 375
 376 -------------------------------------------------------------------------------
 377 Contact Information
 378
 379 At the time of this writing, the most up-to-date information about
 380 SoftFloat and the latest release can be found at the Web page `http://
 381 HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.
 382
 383