1 2<HTML> 3 4<HEAD> 5<TITLE>Berkeley SoftFloat Source Documentation</TITLE> 6</HEAD> 7 8<BODY> 9 10<H1>Berkeley SoftFloat Release 3a: Source Documentation</H1> 11 12<P> 13John R. Hauser<BR> 142015 October 23<BR> 15</P> 16 17 18<H2>Contents</H2> 19 20<BLOCKQUOTE> 21<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> 22<COL WIDTH=25> 23<COL WIDTH=*> 24<TR><TD COLSPAN=2>1. Introduction</TD></TR> 25<TR><TD COLSPAN=2>2. Limitations</TD></TR> 26<TR><TD COLSPAN=2>3. Acknowledgments and License</TD></TR> 27<TR><TD COLSPAN=2>4. SoftFloat Package Directory Structure</TD></TR> 28<TR><TD COLSPAN=2>5. Issues for Porting SoftFloat to a New Target</TD></TR> 29<TR> 30 <TD></TD> 31 <TD>5.1. Standard Headers <CODE><stdbool.h></CODE> and 32 <CODE><stdint.h></CODE></TD> 33</TR> 34<TR><TD></TD><TD>5.2. Specializing Floating-Point Behavior</TD></TR> 35<TR><TD></TD><TD>5.3. Macros for Build Options</TD></TR> 36<TR><TD></TD><TD>5.4. Adapting a Template Target Directory</TD></TR> 37<TR> 38 <TD></TD><TD>5.5. Target-Specific Optimization of Primitive Functions</TD> 39</TR> 40<TR><TD COLSPAN=2>6. Testing SoftFloat</TD></TR> 41<TR> 42 <TD COLSPAN=2>7. Providing SoftFloat as a Common Library for Applications</TD> 43</TR> 44<TR><TD COLSPAN=2>8. Contact Information</TD></TR> 45</TABLE> 46</BLOCKQUOTE> 47 48 49<H2>1. Introduction</H2> 50 51<P> 52This document gives information needed for compiling and/or porting Berkeley 53SoftFloat, a library of C functions implementing binary floating-point 54conforming to the IEEE Standard for Floating-Point Arithmetic. 55For basic documentation about SoftFloat refer to 56<A HREF="SoftFloat.html"><CODE>SoftFloat.html</CODE></A>. 57</P> 58 59<P> 60The source code for SoftFloat is intended to be relatively machine-independent 61and should be compilable with any ISO-Standard C compiler that also supports 62<NOBR>64-bit</NOBR> integers. 63SoftFloat has been successfully compiled with the GNU C Compiler 64(<CODE>gcc</CODE>) for several platforms. 65</P> 66 67<P> 68<NOBR>Release 3</NOBR> of SoftFloat was a complete rewrite relative to 69<NOBR>Release 2</NOBR> or earlier. 70Changes to the interface of SoftFloat functions are documented in 71<A HREF="SoftFloat.html"><CODE>SoftFloat.html</CODE></A>. 72The current version of SoftFloat is <NOBR>Release 3a</NOBR>. 73</P> 74 75 76<H2>2. Limitations</H2> 77 78<P> 79SoftFloat assumes the computer has an addressable byte size of either 8 or 80<NOBR>16 bits</NOBR>. 81(Nearly all computers in use today have <NOBR>8-bit</NOBR> bytes.) 82</P> 83 84<P> 85SoftFloat is written in C and is designed to work with other C code. 86The C compiler used must conform at a minimum to the 1989 ANSI standard for the 87C language (same as the 1990 ISO standard) and must in addition support basic 88arithmetic on <NOBR>64-bit</NOBR> integers. 89Earlier releases of SoftFloat included implementations of <NOBR>32-bit</NOBR> 90single-precision and <NOBR>64-bit</NOBR> double-precision floating-point that 91did not require <NOBR>64-bit</NOBR> integers, but this option is not supported 92starting with <NOBR>Release 3</NOBR>. 93Since 1999, ISO standards for C have mandated compiler support for 94<NOBR>64-bit</NOBR> integers. 95A compiler conforming to the 1999 C Standard or later is recommended but not 96strictly required. 97</P> 98 99<P> 100<NOBR>C Standard</NOBR> header files <CODE><stdbool.h></CODE> and 101<CODE><stdint.h></CODE> are required for defining standard Boolean and 102integer types. 103If these headers are not supplied with the C compiler, minimal substitutes must 104be provided. 105SoftFloat’s dependence on these headers is detailed later in 106<NOBR>section 5.1</NOBR>, <I>Standard Headers <stdbool.h> and 107<stdint.h></I>. 108</P> 109 110 111<H2>3. Acknowledgments and License</H2> 112 113<P> 114The SoftFloat package was written by me, <NOBR>John R.</NOBR> Hauser. 115<NOBR>Release 3</NOBR> of SoftFloat was a completely new implementation 116supplanting earlier releases. 117The project to create <NOBR>Release 3</NOBR> (and <NOBR>now 3a</NOBR>) was done 118in the employ of the University of California, Berkeley, within the Department 119of Electrical Engineering and Computer Sciences, first for the Parallel 120Computing Laboratory (Par Lab) and then for the ASPIRE Lab. 121The work was officially overseen by Prof. Krste Asanovic, with funding provided 122by these sources: 123<BLOCKQUOTE> 124<TABLE> 125<COL> 126<COL WIDTH=10> 127<COL> 128<TR> 129<TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD> 130<TD></TD> 131<TD> 132Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery 133(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, 134NVIDIA, Oracle, and Samsung. 135</TD> 136</TR> 137<TR> 138<TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD> 139<TD></TD> 140<TD> 141DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from 142ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, 143Oracle, and Samsung. 144</TD> 145</TR> 146</TABLE> 147</BLOCKQUOTE> 148</P> 149 150<P> 151The following applies to the whole of SoftFloat <NOBR>Release 3a</NOBR> as well 152as to each source file individually. 153</P> 154 155<P> 156Copyright 2011, 2012, 2013, 2014, 2015 The Regents of the University of 157California. 158All rights reserved. 159</P> 160 161<P> 162Redistribution and use in source and binary forms, with or without 163modification, are permitted provided that the following conditions are met: 164<OL> 165 166<LI> 167<P> 168Redistributions of source code must retain the above copyright notice, this 169list of conditions, and the following disclaimer. 170</P> 171 172<LI> 173<P> 174Redistributions in binary form must reproduce the above copyright notice, this 175list of conditions, and the following disclaimer in the documentation and/or 176other materials provided with the distribution. 177</P> 178 179<LI> 180<P> 181Neither the name of the University nor the names of its contributors may be 182used to endorse or promote products derived from this software without specific 183prior written permission. 184</P> 185 186</OL> 187</P> 188 189<P> 190THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS”, 191AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 192IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE 193DISCLAIMED. 194IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 195INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 196BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 197DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 198LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 199OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 200ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 201</P> 202 203 204<H2>4. SoftFloat Package Directory Structure</H2> 205 206<P> 207Because SoftFloat is targeted to multiple platforms, its source code is 208slightly scattered between target-specific and target-independent directories 209and files. 210The supplied directory structure is as follows: 211<BLOCKQUOTE> 212<PRE> 213doc 214source 215 include 216 8086 217 8086-SSE 218build 219 template-FAST_INT64 220 template-not-FAST_INT64 221 Linux-386-GCC 222 Linux-386-SSE2-GCC 223 Linux-x86_64-GCC 224 Win32-MinGW 225 Win32-SSE2-MinGW 226 Win64-MinGW-w64 227</PRE> 228</BLOCKQUOTE> 229The majority of the SoftFloat sources are provided in the <CODE>source</CODE> 230directory. 231The <CODE>include</CODE> subdirectory of <CODE>source</CODE> contains several 232header files (unsurprisingly), while the <CODE>8086</CODE> and 233<NOBR><CODE>8086-SSE</CODE></NOBR> subdirectories contain source files that 234specialize the floating-point behavior to match the Intel x86 line of 235processors. 236The files in directory <CODE>8086</CODE> give floating-point behavior 237consistent solely with Intel’s older, 8087-derived floating-point, while 238those in <NOBR><CODE>8086-SSE</CODE></NOBR> update the behavior of the 239non-extended formats (<CODE>float32_t</CODE>, <CODE>float64_t</CODE>, and 240<CODE>float128_t</CODE>) to mirror Intel’s more recent Streaming SIMD 241Extensions (SSE) and other compatible extensions. 242If other specializations are attempted, these would be expected to be other 243subdirectories of <CODE>source</CODE> alongside <CODE>8086</CODE> and 244<NOBR><CODE>8086-SSE</CODE></NOBR>. 245Specialization is covered later, in <NOBR>section 5.2</NOBR>, <I>Specializing 246Floating-Point Behavior</I>. 247</P> 248 249<P> 250The <CODE>build</CODE> directory is intended to contain a subdirectory for each 251target platform for which a build of the SoftFloat library may be created. 252For each build target, the target’s subdirectory is where all derived 253object files and the completed SoftFloat library (typically 254<CODE>softfloat.a</CODE> or <CODE>libsoftfloat.a</CODE>) are created. 255The two <CODE>template</CODE> subdirectories are not actual build targets but 256contain sample files for creating new target directories. 257(The meaning of <CODE>FAST_INT64</CODE> will be explained later.) 258</P> 259 260<P> 261Ignoring the <CODE>template</CODE> directories, the supplied target directories 262are intended to follow a naming system of 263<NOBR><CODE><execution-environment>-<compiler></CODE></NOBR>. 264For the example targets, 265<NOBR><CODE><execution-environment></CODE></NOBR> is 266<NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-386-SSE2</CODE></NOBR>, 267<NOBR><CODE>Linux-x86_64</CODE></NOBR>, <CODE>Win32</CODE>, 268<NOBR><CODE>Win32-SSE2</CODE></NOBR>, or <CODE>Win64</CODE>, and 269<NOBR><CODE><compiler></CODE></NOBR> is <CODE>GCC</CODE>, 270<CODE>MinGW</CODE>, or <NOBR><CODE>MinGW-w64</CODE></NOBR>. 271</P> 272 273<P> 274As supplied, each target directory contains two files: 275<BLOCKQUOTE> 276<PRE> 277Makefile 278platform.h 279</PRE> 280</BLOCKQUOTE> 281The provided <CODE>Makefile</CODE> is written for GNU <CODE>make</CODE>. 282A build of SoftFloat for the specific target is begun by executing the 283<CODE>make</CODE> command with the target directory as the current directory. 284A completely different build tool can be used if an appropriate 285<CODE>Makefile</CODE> equivalent is created. 286</P> 287 288<P> 289The <CODE>platform.h</CODE> header file exists to provide a location for 290additional C declarations specific to the build target. 291Every C source file of SoftFloat contains a <CODE>#include</CODE> for 292<CODE>platform.h</CODE>. 293In many cases, the contents of <CODE>platform.h</CODE> can be as simple as one 294or two lines of code. 295At the other extreme, to get maximal performance from SoftFloat, it may be 296desirable to include in header <CODE>platform.h</CODE> (directly or via 297<CODE>#include</CODE>) declarations for numerous target-specific optimizations. 298Such possibilities are discussed in the next section, <I>Issues for Porting 299SoftFloat to a New Target</I>. 300If the target’s compiler or library has bugs or other shortcomings, 301workarounds for these issues may also be possible with target-specific 302declarations in <CODE>platform.h</CODE>, avoiding the need to modify the main 303SoftFloat sources. 304</P> 305 306 307<H2>5. Issues for Porting SoftFloat to a New Target</H2> 308 309<H3>5.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE></H3> 310 311<P> 312The SoftFloat sources make use of standard headers 313<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, which have 314been part of the ISO C Standard Library since 1999. 315With any recent compiler, these standard headers are likely to be supported, 316even if the compiler does not claim complete conformance to the latest ISO C 317Standard. 318For older or nonstandard compilers, substitutes for 319<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE> may need to be 320created. 321SoftFloat depends on these names from <CODE><stdbool.h></CODE>: 322<BLOCKQUOTE> 323<PRE> 324bool 325true 326false 327</PRE> 328</BLOCKQUOTE> 329and on these names from <CODE><stdint.h></CODE>: 330<BLOCKQUOTE> 331<PRE> 332uint16_t 333uint32_t 334uint64_t 335int32_t 336int64_t 337UINT64_C 338INT64_C 339uint_least8_t 340uint_fast8_t 341uint_fast16_t 342uint_fast32_t 343uint_fast64_t 344int_fast8_t 345int_fast16_t 346int_fast32_t 347int_fast64_t 348</PRE> 349</BLOCKQUOTE> 350</P> 351 352 353<H3>5.2. Specializing Floating-Point Behavior</H3> 354 355<P> 356The IEEE Floating-Point Standard allows for some flexibility in a conforming 357implementation, particularly concerning NaNs. 358The SoftFloat <CODE>source</CODE> directory is supplied with some 359<I>specialization</I> subdirectories containing possible definitions for this 360implementation-specific behavior. 361For example, the <CODE>8086</CODE> and <NOBR><CODE>8086-SSE</CODE></NOBR> 362subdirectories have source files that specialize SoftFloat’s behavior to 363match that of Intel’s x86 line of processors. 364The files in a specialization subdirectory must determine: 365<UL> 366<LI> 367whether tininess for underflow is detected before or after rounding by default; 368<LI> 369what (if anything) special happens when exceptions are raised; 370<LI> 371how signaling NaNs are distinguished from quiet NaNs; 372<LI> 373the default generated quiet NaNs; and 374<LI> 375how NaNs are propagated from function inputs to output. 376</UL> 377</P> 378 379<P> 380As provided, the build process for a target expects to involve exactly 381<EM>one</EM> specialization directory that defines <EM>all</EM> of these 382implementation-specific details for the target. 383A specialization directory such as <CODE>8086</CODE> is expected to contain a 384header file called <CODE>specialize.h</CODE>, together with whatever other 385source files are needed to complete the specialization. 386</P> 387 388<P> 389A new build target may use an existing specialization, such as the ones 390provided by the <CODE>8086</CODE> and <NOBR><CODE>8086-SSE</CODE></NOBR> 391subdirectories. 392If a build target needs a new specialization, different from any existing ones, 393it is recommended that a new specialization subdirectory be created in the 394<CODE>source</CODE> directory for this purpose. 395The <CODE>specialize.h</CODE> header file from any of the provided 396specialization subdirectories can be used as a model for what definitions are 397needed. 398</P> 399 400 401<H3>5.3. Macros for Build Options</H3> 402 403<P> 404The SoftFloat source files adapt the floating-point implementation according to 405a few C preprocessor macros: 406<BLOCKQUOTE> 407<DL> 408<DT><CODE>LITTLEENDIAN</CODE> 409<DD> 410Must be defined for little-endian machines; must not be defined for big-endian 411machines. 412<DT><CODE>SOFTFLOAT_FAST_INT64</CODE> 413<DD> 414Can be defined to indicate that the build target’s implementation of 415<NOBR>64-bit</NOBR> arithmetic is efficient. 416For newer <NOBR>64-bit</NOBR> processors, this macro should usually be defined. 417For very small microprocessors whose buses and registers are <NOBR>8-bit</NOBR> 418or <NOBR>16-bit</NOBR> in size, this macro should usually not be defined. 419Whether this macro should be defined for a <NOBR>32-bit</NOBR> processor may 420depend on the target machine and the applications that will use SoftFloat. 421<DT><CODE>SOFTFLOAT_FAST_DIV64TO32</CODE> 422<DD> 423Can be defined to indicate that the target’s division operator 424<NOBR>in C</NOBR> (written as <CODE>/</CODE>) is reasonably efficient for 425dividing a <NOBR>64-bit</NOBR> unsigned integer by a <NOBR>32-bit</NOBR> 426unsigned integer. 427Setting this macro may affect the performance of division, remainder, and 428square root operations. 429<DT><CODE>INLINE_LEVEL</CODE> 430<DD> 431Can be defined to an integer to determine the degree of inlining requested of 432the compiler. 433Larger numbers request that more inlining be done. 434If this macro is not defined or is defined to a value less <NOBR>than 1</NOBR> 435(zero or negative), no inlining is requested. 436The maximum effective value is no higher <NOBR>than 5</NOBR>. 437Defining this macro to a value greater than 5 is the same as defining it 438<NOBR>to 5</NOBR>. 439<DT><CODE>INLINE</CODE> 440<DD> 441Specifies the sequence of tokens used to indicate that a C function should be 442inlined. 443If macro <CODE>INLINE_LEVEL</CODE> is defined with a value of 1 or higher, this 444macro must be defined; otherwise, this macro is ignored and need not be 445defined. 446For some compilers, this macro can be defined as the single keyword 447<CODE>inline</CODE>. 448Historically, the <CODE>gcc</CODE> compiler has required that this macro be 449defined to <CODE>extern</CODE> <CODE>inline</CODE>. 450</DL> 451</BLOCKQUOTE> 452</P> 453 454<P> 455Following the usual custom <NOBR>for C</NOBR>, for the first three macros (all 456except <CODE>INLINE_LEVEL</CODE> and <CODE>INLINE</CODE>), the content of any 457definition is irrelevant; 458what matters is a macro’s effect on <CODE>#ifdef</CODE> directives. 459</P> 460 461<P> 462It is recommended that any definitions of macros <CODE>LITTLEENDIAN</CODE> and 463<CODE>INLINE</CODE> be made in a build target’s <CODE>platform.h</CODE> 464header file, because these macros are expected to be determined inflexibly by 465the target machine and compiler. 466The other three macros control optimization and might be better located in the 467target’s Makefile (or its equivalent). 468</P> 469 470 471<H3>5.4. Adapting a Template Target Directory</H3> 472 473<P> 474In the <CODE>build</CODE> directory, two <CODE>template</CODE> subdirectories 475provide models for new target directories. 476Two different templates exist because different functions are needed in the 477SoftFloat library depending on whether macro <CODE>SOFTFLOAT_FAST_INT64</CODE> 478is defined. 479If macro <CODE>SOFTFLOAT_FAST_INT64</CODE> will be defined, 480<NOBR><CODE>template-FAST_INT64</CODE></NOBR> is the template to use; 481otherwise, <NOBR><CODE>template-not-FAST_INT64</CODE></NOBR> is the appropriate 482template. 483A new target directory can be created by copying the correct template directory 484and editing the files inside. 485To avoid confusion, it would be wise to refrain from editing the files within a 486template directory directly. 487</P> 488 489 490<H3>5.5. Target-Specific Optimization of Primitive Functions</H3> 491 492<P> 493Header file <CODE>primitives.h</CODE> (in directory 494<CODE>source/include</CODE>) declares macros and functions for numerous 495underlying arithmetic operations upon which many of SoftFloat’s 496floating-point functions are ultimately built. 497The SoftFloat sources include implementations of all of these functions/macros, 498written as standard C code, so a complete and correct SoftFloat library can be 499built using only the supplied code for all functions. 500However, for many targets, SoftFloat’s performance can be improved by 501substituting target-specific implementations of some of the functions/macros 502declared in <CODE>primitives.h</CODE>. 503</P> 504 505<P> 506For example, <CODE>primitives.h</CODE> declares a function called 507<CODE>softfloat_countLeadingZeros32</CODE> that takes an unsigned 508<NOBR>32-bit</NOBR> integer as an argument and returns the maximal number of 509the integer’s most-significant bits that are all zeros. 510While the SoftFloat sources include an implementation of this function written 511in <NOBR>standard C</NOBR>, many processors can perform this same function 512directly in only one or two machine instructions. 513An alternative, target-specific implementation that maps to those instructions 514is likely to be more efficient than the generic C code from the SoftFloat 515package. 516</P> 517 518<P> 519A build target can replace the supplied version of any function or macro of 520<CODE>primitives.h</CODE> by defining a macro with the same name in the 521target’s <CODE>platform.h</CODE> header file. 522For this purpose, it may be helpful for <CODE>platform.h</CODE> to 523<CODE>#include</CODE> header file <CODE>primitiveTypes.h</CODE>, which defines 524types used for arguments and results of functions declared in 525<CODE>primitives.h</CODE>. 526When a desired replacement implementation is a function, not a macro, it is 527sufficient for <CODE>platform.h</CODE> to include the line 528<BLOCKQUOTE> 529<PRE> 530#define <function-name> <function-name> 531</PRE> 532</BLOCKQUOTE> 533where <NOBR><CODE><function-name></CODE></NOBR> is the name of the 534function. 535This technically defines <NOBR><CODE><function-name></CODE></NOBR> as a 536macro, but one that resolves to the same name, which may then be a function. 537(A preprocessor conforming to the C Standard must limit recursive macro 538expansion from being applied more than once.) 539</P> 540 541 542<H2>6. Testing SoftFloat</H2> 543 544<P> 545SoftFloat can be tested using the <CODE>testsoftfloat</CODE> program by the 546same author. 547This program is part of the Berkeley TestFloat package available at the Web 548page 549<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></A>. 550The TestFloat package also has a program called <CODE>timesoftfloat</CODE> that 551measures the speed of SoftFloat’s floating-point functions. 552</P> 553 554 555<H2>7. Providing SoftFloat as a Common Library for Applications</H2> 556 557<P> 558Header file <CODE>softfloat.h</CODE> defines the SoftFloat interface as seen by 559clients. 560If the SoftFloat library will be made a common library for programs on a 561particular system, the supplied <CODE>softfloat.h</CODE> has a couple of 562deficiencies for this purpose: 563<UL> 564<LI> 565As supplied, <CODE>softfloat.h</CODE> depends on another header, 566<CODE>softfloat_types.h</CODE>, that is not intended for public use but which 567must also be visible to the programmer’s compiler. 568<LI> 569More troubling, at the time <CODE>softfloat.h</CODE> is included in a C 570source file, macro <CODE>SOFTFLOAT_FAST_INT64</CODE> must be defined, or not 571defined, consistent with whether this macro was defined when the SoftFloat 572library was built. 573</UL> 574In the situation that new programs may regularly <CODE>#include</CODE> header 575file <CODE>softfloat.h</CODE>, it is recommended that a custom, self-contained 576version of this header file be created that eliminates these issues. 577</P> 578 579 580<H2>8. Contact Information</H2> 581 582<P> 583At the time of this writing, the most up-to-date information about SoftFloat 584and the latest release can be found at the Web page 585<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>. 586</P> 587 588 589</BODY> 590 591