lib/libc/softfloat/softfloat-source.txt

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