softfloat/doc/SoftFloat-source.html

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