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