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