1230363Sdas$NetBSD: softfloat-source.txt,v 1.2 2006/11/24 19:46:58 christos Exp $ 2129203Scognet$FreeBSD: releng/10.2/lib/libc/softfloat/softfloat-source.txt 230363 2012-01-20 06:16:14Z das $ 3129203Scognet 4129203ScognetSoftFloat Release 2a Source Documentation 5129203Scognet 6129203ScognetJohn R. Hauser 7129203Scognet1998 December 14 8129203Scognet 9129203Scognet 10129203Scognet------------------------------------------------------------------------------- 11129203ScognetIntroduction 12129203Scognet 13129203ScognetSoftFloat is a software implementation of floating-point that conforms to 14129203Scognetthe IEC/IEEE Standard for Binary Floating-Point Arithmetic. SoftFloat can 15129203Scognetsupport four floating-point formats: single precision, double precision, 16129203Scognetextended double precision, and quadruple precision. All operations required 17129203Scognetby the IEEE Standard are implemented, except for conversions to and from 18129203Scognetdecimal. SoftFloat is distributed in the form of C source code, so a 19129203ScognetC compiler is needed to compile the code. Support for the extended double- 20129203Scognetprecision and quadruple-precision formats is dependent on the C compiler 21129203Scognetimplementing a 64-bit integer type. 22129203Scognet 23129203ScognetThis document gives information needed for compiling and/or porting 24129203ScognetSoftFloat. 25129203Scognet 26129203ScognetThe source code for SoftFloat is intended to be relatively machine- 27129203Scognetindependent and should be compilable using any ISO/ANSI C compiler. At the 28129203Scognettime of this writing, SoftFloat has been successfully compiled with the GNU 29129203ScognetC Compiler (`gcc') for several platforms. 30129203Scognet 31129203Scognet 32129203Scognet------------------------------------------------------------------------------- 33129203ScognetLimitations 34129203Scognet 35129203ScognetSoftFloat as written requires an ISO/ANSI-style C compiler. No attempt has 36230363Sdasbeen made to accommodate compilers that are not ISO-conformant. Older ``K&R- 37129203Scognetstyle'' compilers are not adequate for compiling SoftFloat. All testing I 38129203Scognethave done so far has been with the GNU C Compiler. Compilation with other 39129203Scognetcompilers should be possible but has not been tested. 40129203Scognet 41129203ScognetThe SoftFloat sources assume that source code file names can be longer than 42129203Scognet8 characters. In order to compile under an MS-DOS-type system, many of the 43129203Scognetsource files will need to be renamed, and the source and makefiles edited 44129203Scognetappropriately. Once compiled, the SoftFloat binary does not depend on the 45129203Scognetexistence of long file names. 46129203Scognet 47129203ScognetThe underlying machine is assumed to be binary with a word size that is a 48129203Scognetpower of 2. Bytes are 8 bits. Support for the extended double-precision 49129203Scognetand quadruple-precision formats depends on the C compiler implementing 50129203Scogneta 64-bit integer type. If the largest integer type supported by the 51129203ScognetC compiler is 32 bits, SoftFloat is limited to the single- and double- 52129203Scognetprecision formats. 53129203Scognet 54129203Scognet 55129203Scognet------------------------------------------------------------------------------- 56129203ScognetContents 57129203Scognet 58129203Scognet Introduction 59129203Scognet Limitations 60129203Scognet Contents 61129203Scognet Legal Notice 62129203Scognet SoftFloat Source Directory Structure 63129203Scognet SoftFloat Source Files 64129203Scognet processors/*.h 65129203Scognet softfloat/bits*/*/softfloat.h 66129203Scognet softfloat/bits*/*/milieu.h 67129203Scognet softfloat/bits*/*/softfloat-specialize 68129203Scognet softfloat/bits*/softfloat-macros 69129203Scognet softfloat/bits*/softfloat.c 70129203Scognet Steps to Creating a `softfloat.o' 71129203Scognet Making `softfloat.o' a Library 72129203Scognet Testing SoftFloat 73129203Scognet Timing SoftFloat 74129203Scognet Compiler Options and Efficiency 75129203Scognet Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros' 76129203Scognet Contact Information 77129203Scognet 78129203Scognet 79129203Scognet 80129203Scognet------------------------------------------------------------------------------- 81129203ScognetLegal Notice 82129203Scognet 83129203ScognetSoftFloat was written by John R. Hauser. This work was made possible in 84129203Scognetpart by the International Computer Science Institute, located at Suite 600, 85129203Scognet1947 Center Street, Berkeley, California 94704. Funding was partially 86129203Scognetprovided by the National Science Foundation under grant MIP-9311980. The 87129203Scognetoriginal version of this code was written as part of a project to build 88129203Scogneta fixed-point vector processor in collaboration with the University of 89129203ScognetCalifornia at Berkeley, overseen by Profs. Nelson Morgan and John Wawrzynek. 90129203Scognet 91129203ScognetTHIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 92129203Scognethas been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 93129203ScognetTIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 94129203ScognetPERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 95129203ScognetAND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 96129203Scognet 97129203Scognet 98129203Scognet------------------------------------------------------------------------------- 99129203ScognetSoftFloat Source Directory Structure 100129203Scognet 101129203ScognetBecause SoftFloat is targeted to multiple platforms, its source code 102129203Scognetis slightly scattered between target-specific and target-independent 103129203Scognetdirectories and files. The directory structure is as follows: 104129203Scognet 105129203Scognet processors 106129203Scognet softfloat 107129203Scognet bits64 108129203Scognet templates 109129203Scognet 386-Win32-gcc 110129203Scognet SPARC-Solaris-gcc 111129203Scognet bits32 112129203Scognet templates 113129203Scognet 386-Win32-gcc 114129203Scognet SPARC-Solaris-gcc 115129203Scognet 116129203ScognetThe two topmost directories and their contents are: 117129203Scognet 118129203Scognet softfloat - Most of the source code needed for SoftFloat. 119129203Scognet processors - Target-specific header files that are not specific to 120129203Scognet SoftFloat. 121129203Scognet 122129203ScognetThe `softfloat' directory is further split into two parts: 123129203Scognet 124129203Scognet bits64 - SoftFloat implementation using 64-bit integers. 125129203Scognet bits32 - SoftFloat implementation using only 32-bit integers. 126129203Scognet 127129203ScognetWithin these directories are subdirectories for each of the targeted 128129203Scognetplatforms. The SoftFloat source code is distributed with targets 129129203Scognet`386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already 130129203Scognetprepared for both the 32-bit and 64-bit implementations. Source files that 131129203Scognetare not within these target-specific subdirectories are intended to be 132129203Scognettarget-independent. 133129203Scognet 134129203ScognetThe naming convention used for the target-specific directories is 135129203Scognet`<processor>-<executable-type>-<compiler>'. The names of the supplied 136129203Scognettarget directories should be interpreted as follows: 137129203Scognet 138129203Scognet <processor>: 139129203Scognet 386 - Intel 386-compatible processor. 140129203Scognet SPARC - SPARC processor (as used by Sun machines). 141129203Scognet <executable-type>: 142129203Scognet Win32 - Microsoft Win32 executable. 143129203Scognet Solaris - Sun Solaris executable. 144129203Scognet <compiler>: 145129203Scognet gcc - GNU C Compiler. 146129203Scognet 147129203ScognetYou do not need to maintain this convention if you do not want to. 148129203Scognet 149129203ScognetAlongside the supplied target-specific directories is a `templates' 150129203Scognetdirectory containing a set of ``generic'' target-specific source files. A 151129203Scognetnew target directory can be created by copying the `templates' directory and 152129203Scognetediting the files inside. (Complete instructions for porting SoftFloat to a 153129203Scognetnew target are in the section _Steps_to_Creating_a_`softfloat.o'_.) Note 154129203Scognetthat the `templates' directory will not work as a target directory without 155129203Scognetsome editing. To avoid confusion, it would be wise to refrain from editing 156129203Scognetthe files inside `templates' directly. 157129203Scognet 158129203Scognet 159129203Scognet------------------------------------------------------------------------------- 160129203ScognetSoftFloat Source Files 161129203Scognet 162129203ScognetThe purpose of each source file is described below. In the following, 163129203Scognetthe `*' symbol is used in place of the name of a specific target, such as 164129203Scognet`386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some other text, as 165129203Scognetin `bits*' for either `bits32' or `bits64'. 166129203Scognet 167129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 168129203Scognetprocessors/*.h 169129203Scognet 170129203ScognetThe target-specific `processors' header file defines integer types 171129203Scognetof various sizes, and also defines certain C preprocessor macros that 172129203Scognetcharacterize the target. The two examples supplied are `386-gcc.h' and 173129203Scognet`SPARC-gcc.h'. The naming convention used for processor header files is 174129203Scognet`<processor>-<compiler>.h'. 175129203Scognet 176129203ScognetIf 64-bit integers are supported by the compiler, the macro name `BITS64' 177129203Scognetshould be defined here along with the corresponding 64-bit integer 178129203Scognettypes. In addition, the function-like macro `LIT64' must be defined for 179129203Scognetconstructing 64-bit integer literals (constants). The `LIT64' macro is used 180129203Scognetconsistently in the SoftFloat code to annotate 64-bit literals. 181129203Scognet 182129203ScognetIf `BITS64' is not defined, only the 32-bit version of SoftFloat can be 183129203Scognetcompiled. If `BITS64' _is_ defined, either can be compiled. 184129203Scognet 185129203ScognetIf an inlining attribute (such as an `inline' keyword) is provided by the 186129203Scognetcompiler, the macro `INLINE' should be defined to the appropriate keyword. 187129203ScognetIf not, `INLINE' can be set to the keyword `static'. The `INLINE' macro 188129203Scognetappears in the SoftFloat source code before every function that should 189129203Scognetbe inlined by the compiler. SoftFloat depends on inlining to obtain 190129203Scognetgood speed. Even if inlining cannot be forced with a language keyword, 191129203Scognetthe compiler may still be able to perform inlining on its own as an 192129203Scognetoptimization. If a command-line option is needed to convince the compiler 193129203Scognetto perform this optimization, this should be assured in the makefile. (See 194129203Scognetthe section _Compiler_Options_and_Efficiency_ below.) 195129203Scognet 196129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 197129203Scognetsoftfloat/bits*/*/softfloat.h 198129203Scognet 199129203ScognetThe target-specific `softfloat.h' header file defines the SoftFloat 200129203Scognetinterface as seen by clients. 201129203Scognet 202129203ScognetUnlike the actual function definitions in `softfloat.c', the declarations 203129203Scognetin `softfloat.h' do not use any of the types defined by the `processors' 204129203Scognetheader file. This is done so that clients will not have to include the 205129203Scognet`processors' header file in order to use SoftFloat. Nevertheless, the 206129203Scognettarget-specific declarations in `softfloat.h' must match what `softfloat.c' 207129203Scognetexpects. For example, if `int32' is defined as `int' in the `processors' 208129203Scognetheader file, then in `softfloat.h' the output of `float32_to_int32' should 209129203Scognetbe stated as `int', although in `softfloat.c' it is given in target- 210129203Scognetindependent form as `int32'. 211129203Scognet 212129203ScognetFor the `bits64' implementation of SoftFloat, the macro names `FLOATX80' and 213129203Scognet`FLOAT128' must be defined in order for the extended double-precision and 214129203Scognetquadruple-precision formats to be enabled in the code. Conversely, either 215129203Scognetor both of the extended formats can be disabled by simply removing the 216129203Scognet`#define' of the respective macro. When an extended format is not enabled, 217129203Scognetnone of the functions that either input or output the format are defined, 218129203Scognetand no space is taken up in `softfloat.o' by such functions. There is no 219129203Scognetprovision for disabling the usual single- and double-precision formats. 220129203Scognet 221129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 222129203Scognetsoftfloat/bits*/*/milieu.h 223129203Scognet 224129203ScognetThe target-specific `milieu.h' header file provides declarations that are 225129203Scognetneeded to compile SoftFloat. In addition, deviations from ISO/ANSI C by 226129203Scognetthe compiler (such as names not properly declared in system header files) 227129203Scognetare corrected in this header if possible. 228129203Scognet 229129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 230129203Scognetsoftfloat/bits*/*/softfloat-specialize 231129203Scognet 232129203ScognetThis target-specific C source fragment defines: 233129203Scognet 234129203Scognet-- whether tininess for underflow is detected before or after rounding by 235129203Scognet default; 236129203Scognet-- what (if anything) special happens when exceptions are raised; 237129203Scognet-- how signaling NaNs are distinguished from quiet NaNs; 238129203Scognet-- the default generated quiet NaNs; and 239129203Scognet-- how NaNs are propagated from function inputs to output. 240129203Scognet 241129203ScognetThese details are not decided by the IEC/IEEE Standard. This fragment is 242129203Scognetincluded verbatim within `softfloat.c' when SoftFloat is compiled. 243129203Scognet 244129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 245129203Scognetsoftfloat/bits*/softfloat-macros 246129203Scognet 247129203ScognetThis target-independent C source fragment defines a number of arithmetic 248129203Scognetfunctions used as primitives within the `softfloat.c' source. Most of the 249129203Scognetfunctions defined here are intended to be inlined for efficiency. This 250129203Scognetfragment is included verbatim within `softfloat.c' when SoftFloat is 251129203Scognetcompiled. 252129203Scognet 253129203ScognetTarget-specific variations on this file are possible. See the section 254129203Scognet_Processor-Specific_Optimization_of_`softfloat.c'_Using_`softfloat-macros'_ 255129203Scognetbelow. 256129203Scognet 257129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 258129203Scognetsoftfloat/bits*/softfloat.c 259129203Scognet 260129203ScognetThe target-independent `softfloat.c' source file contains the body of the 261129203ScognetSoftFloat implementation. 262129203Scognet 263129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 264129203Scognet 265129203ScognetThe inclusion of the files above within each other (using `#include') can be 266129203Scognetshown graphically as follows: 267129203Scognet 268129203Scognet softfloat/bits*/softfloat.c 269129203Scognet softfloat/bits*/*/milieu.h 270129203Scognet processors/*.h 271129203Scognet softfloat/bits*/*/softfloat.h 272129203Scognet softfloat/bits*/*/softfloat-specialize 273129203Scognet softfloat/bits*/softfloat-macros 274129203Scognet 275129203ScognetNote in particular that `softfloat.c' does not include the `processors' 276129203Scognetheader file directly. Rather, `softfloat.c' includes the target-specific 277129203Scognet`milieu.h' header file, which in turn includes the processor header file. 278129203Scognet 279129203Scognet 280129203Scognet------------------------------------------------------------------------------- 281129203ScognetSteps to Creating a `softfloat.o' 282129203Scognet 283129203ScognetPorting and/or compiling SoftFloat involves the following steps: 284129203Scognet 285129203Scognet1. If one does not already exist, create an appropriate `.h' file in the 286129203Scognet `processors' directory. 287129203Scognet 288129203Scognet2. If `BITS64' is defined in the `processors' header file, choose whether 289129203Scognet to compile the 32-bit or 64-bit implementation of SoftFloat. If 290129203Scognet `BITS64' is not defined, your only choice is the 32-bit implementation. 291129203Scognet The remaining steps occur within either the `bits32' or `bits64' 292129203Scognet subdirectories. 293129203Scognet 294129203Scognet3. If one does not already exist, create an appropriate target-specific 295129203Scognet subdirectory by copying the given `templates' directory. 296129203Scognet 297129203Scognet4. In the target-specific subdirectory, edit the files `softfloat-specialize' 298129203Scognet and `softfloat.h' to define the desired exception handling functions 299129203Scognet and mode control values. In the `softfloat.h' header file, ensure also 300129203Scognet that all declarations give the proper target-specific type (such as 301129203Scognet `int' or `long') corresponding to the target-independent type used in 302129203Scognet `softfloat.c' (such as `int32'). None of the type names declared in the 303129203Scognet `processors' header file should appear in `softfloat.h'. 304129203Scognet 305129203Scognet5. In the target-specific subdirectory, edit the files `milieu.h' and 306129203Scognet `Makefile' to reflect the current environment. 307129203Scognet 308129203Scognet6. In the target-specific subdirectory, execute `make'. 309129203Scognet 310129203ScognetFor the targets that are supplied, if the expected compiler is available 311129203Scognet(usually `gcc'), it should only be necessary to execute `make' in the 312129203Scognettarget-specific subdirectory. 313129203Scognet 314129203Scognet 315129203Scognet------------------------------------------------------------------------------- 316129203ScognetMaking `softfloat.o' a Library 317129203Scognet 318129203ScognetSoftFloat is not made into a software library by the supplied makefile. 319129203ScognetIf desired, `softfloat.o' can easily be put into its own library (in Unix, 320129203Scognet`softfloat.a') using the usual system tool (in Unix, `ar'). 321129203Scognet 322129203Scognet 323129203Scognet------------------------------------------------------------------------------- 324129203ScognetTesting SoftFloat 325129203Scognet 326129203ScognetSoftFloat can be tested using the `testsoftfloat' program by the same 327129203Scognetauthor. The `testsoftfloat' program is part of the TestFloat package 328129203Scognetavailable at the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/ 329129203ScognetTestFloat.html'. 330129203Scognet 331129203Scognet 332129203Scognet------------------------------------------------------------------------------- 333129203ScognetTiming SoftFloat 334129203Scognet 335129203ScognetA program called `timesoftfloat' for timing the SoftFloat functions is 336129203Scognetincluded with the SoftFloat source code. Compiling `timesoftfloat' should 337129203Scognetpose no difficulties once `softfloat.o' exists. The supplied makefile 338129203Scognetwill create a `timesoftfloat' executable by default after generating 339129203Scognet`softfloat.o'. See `timesoftfloat.txt' for documentation about using 340129203Scognet`timesoftfloat'. 341129203Scognet 342129203Scognet 343129203Scognet------------------------------------------------------------------------------- 344129203ScognetCompiler Options and Efficiency 345129203Scognet 346129203ScognetIn order to get good speed with SoftFloat, it is important that the compiler 347129203Scognetinline the routines that have been marked `INLINE' in the code. Even if 348129203Scognetinlining cannot be forced by an appropriate definition of the `INLINE' 349129203Scognetmacro, the compiler may still be able to perform inlining on its own as 350129203Scognetan optimization. In that case, the makefile should be edited to give the 351129203Scognetcompiler whatever option is required to cause it to inline small functions. 352129203Scognet 353129203ScognetThe ability of the processor to do fast shifts has been assumed. Efficiency 354129203Scognetwill not be as good on processors for which this is not the case (such as 355129203Scognetthe original Motorola 68000 or Intel 8086 processors). 356129203Scognet 357129203Scognet 358129203Scognet------------------------------------------------------------------------------- 359129203ScognetProcessor-Specific Optimization of `softfloat.c' Using `softfloat-macros' 360129203Scognet 361129203ScognetThe `softfloat-macros' source fragment defines arithmetic functions used 362129203Scognetas primitives by `softfloat.c'. This file has been written in a target- 363129203Scognetindependent form. For a given target, it may be possible to improve on 364129203Scognetthese functions using target-specific and/or non-ISO-C features (such 365129203Scognetas `asm' statements). For example, one of the ``macro'' functions takes 366129203Scognettwo word-size integers and returns their full product in two words. 367129203ScognetThis operation can be done directly in hardware on many processors; but 368129203Scognetbecause it is not available through standard C, the function defined in 369129203Scognet`softfloat-macros' uses four multiplies to achieve the same result. 370129203Scognet 371129203ScognetTo address these shortcomings, a customized version of `softfloat-macros' 372129203Scognetcan be created in any of the target-specific subdirectories. A simple 373129203Scognetmodification to the target's makefile should be sufficient to ensure that 374129203Scognetthe custom version is used instead of the generic one. 375129203Scognet 376129203Scognet 377129203Scognet------------------------------------------------------------------------------- 378129203ScognetContact Information 379129203Scognet 380129203ScognetAt the time of this writing, the most up-to-date information about 381129203ScognetSoftFloat and the latest release can be found at the Web page `http:// 382129203ScognetHTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'. 383129203Scognet 384129203Scognet 385