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 384
