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