| |
| <HTML> |
| |
| <HEAD> |
| <TITLE>Berkeley SoftFloat Source Documentation</TITLE> |
| </HEAD> |
| |
| <BODY> |
| |
| <H1>Berkeley SoftFloat Release 3e: Source Documentation</H1> |
| |
| <P> |
| John R. Hauser<BR> |
| 2018 January 20<BR> |
| </P> |
| |
| |
| <H2>Contents</H2> |
| |
| <BLOCKQUOTE> |
| <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> |
| <COL WIDTH=25> |
| <COL WIDTH=*> |
| <TR><TD COLSPAN=2>1. Introduction</TD></TR> |
| <TR><TD COLSPAN=2>2. Limitations</TD></TR> |
| <TR><TD COLSPAN=2>3. Acknowledgments and License</TD></TR> |
| <TR><TD COLSPAN=2>4. SoftFloat Package Directory Structure</TD></TR> |
| <TR><TD COLSPAN=2>5. Issues for Porting SoftFloat to a New Target</TD></TR> |
| <TR> |
| <TD></TD> |
| <TD>5.1. Standard Headers <CODE><stdbool.h></CODE> and |
| <CODE><stdint.h></CODE></TD> |
| </TR> |
| <TR><TD></TD><TD>5.2. Specializing Floating-Point Behavior</TD></TR> |
| <TR><TD></TD><TD>5.3. Macros for Build Options</TD></TR> |
| <TR><TD></TD><TD>5.4. Adapting a Template Target Directory</TD></TR> |
| <TR> |
| <TD></TD><TD>5.5. Target-Specific Optimization of Primitive Functions</TD> |
| </TR> |
| <TR><TD COLSPAN=2>6. Testing SoftFloat</TD></TR> |
| <TR> |
| <TD COLSPAN=2>7. Providing SoftFloat as a Common Library for Applications</TD> |
| </TR> |
| <TR><TD COLSPAN=2>8. Contact Information</TD></TR> |
| </TABLE> |
| </BLOCKQUOTE> |
| |
| |
| <H2>1. Introduction</H2> |
| |
| <P> |
| This document gives information needed for compiling and/or porting Berkeley |
| SoftFloat, a library of C functions implementing binary floating-point |
| conforming to the IEEE Standard for Floating-Point Arithmetic. |
| For basic documentation about SoftFloat refer to |
| <A HREF="SoftFloat.html"><NOBR><CODE>SoftFloat.html</CODE></NOBR></A>. |
| </P> |
| |
| <P> |
| The source code for SoftFloat is intended to be relatively machine-independent |
| and should be compilable with any ISO-Standard C compiler that also supports |
| <NOBR>64-bit</NOBR> integers. |
| SoftFloat has been successfully compiled with the GNU C Compiler |
| (<CODE>gcc</CODE>) for several platforms. |
| </P> |
| |
| <P> |
| <NOBR>Release 3</NOBR> of SoftFloat was a complete rewrite relative to |
| <NOBR>Release 2</NOBR> or earlier. |
| Changes to the interface of SoftFloat functions are documented in |
| <A HREF="SoftFloat.html"><NOBR><CODE>SoftFloat.html</CODE></NOBR></A>. |
| The current version of SoftFloat is <NOBR>Release 3e</NOBR>. |
| </P> |
| |
| |
| <H2>2. Limitations</H2> |
| |
| <P> |
| SoftFloat assumes the computer has an addressable byte size of either 8 or |
| <NOBR>16 bits</NOBR>. |
| (Nearly all computers in use today have <NOBR>8-bit</NOBR> bytes.) |
| </P> |
| |
| <P> |
| SoftFloat is written in C and is designed to work with other C code. |
| The C compiler used must conform at a minimum to the 1989 ANSI standard for the |
| C language (same as the 1990 ISO standard) and must in addition support basic |
| arithmetic on <NOBR>64-bit</NOBR> integers. |
| Earlier releases of SoftFloat included implementations of <NOBR>32-bit</NOBR> |
| single-precision and <NOBR>64-bit</NOBR> double-precision floating-point that |
| did not require <NOBR>64-bit</NOBR> integers, but this option is not supported |
| starting with <NOBR>Release 3</NOBR>. |
| Since 1999, ISO standards for C have mandated compiler support for |
| <NOBR>64-bit</NOBR> integers. |
| A compiler conforming to the 1999 C Standard or later is recommended but not |
| strictly required. |
| </P> |
| |
| <P> |
| <NOBR>C Standard</NOBR> header files <CODE><stdbool.h></CODE> and |
| <CODE><stdint.h></CODE> are required for defining standard Boolean and |
| integer types. |
| If these headers are not supplied with the C compiler, minimal substitutes must |
| be provided. |
| SoftFloat’s dependence on these headers is detailed later in |
| <NOBR>section 5.1</NOBR>, <I>Standard Headers <CODE><stdbool.h></CODE> |
| and <CODE><stdint.h></CODE></I>. |
| </P> |
| |
| |
| <H2>3. Acknowledgments and License</H2> |
| |
| <P> |
| The SoftFloat package was written by me, <NOBR>John R.</NOBR> Hauser. |
| <NOBR>Release 3</NOBR> of SoftFloat was a completely new implementation |
| supplanting earlier releases. |
| The project to create <NOBR>Release 3</NOBR> (now <NOBR>through 3e</NOBR>) was |
| done in the employ of the University of California, Berkeley, within the |
| Department of Electrical Engineering and Computer Sciences, first for the |
| Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab. |
| The work was officially overseen by Prof. Krste Asanovic, with funding provided |
| by these sources: |
| <BLOCKQUOTE> |
| <TABLE> |
| <COL> |
| <COL WIDTH=10> |
| <COL> |
| <TR> |
| <TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD> |
| <TD></TD> |
| <TD> |
| Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery |
| (Award #DIG07-10227), with additional support from Par Lab affiliates Nokia, |
| NVIDIA, Oracle, and Samsung. |
| </TD> |
| </TR> |
| <TR> |
| <TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD> |
| <TD></TD> |
| <TD> |
| DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from |
| ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA, |
| Oracle, and Samsung. |
| </TD> |
| </TR> |
| </TABLE> |
| </BLOCKQUOTE> |
| </P> |
| |
| <P> |
| The following applies to the whole of SoftFloat <NOBR>Release 3e</NOBR> as well |
| as to each source file individually. |
| </P> |
| |
| <P> |
| Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the |
| University of California. |
| All rights reserved. |
| </P> |
| |
| <P> |
| Redistribution and use in source and binary forms, with or without |
| modification, are permitted provided that the following conditions are met: |
| <OL> |
| |
| <LI> |
| <P> |
| Redistributions of source code must retain the above copyright notice, this |
| list of conditions, and the following disclaimer. |
| </P> |
| |
| <LI> |
| <P> |
| Redistributions in binary form must reproduce the above copyright notice, this |
| list of conditions, and the following disclaimer in the documentation and/or |
| other materials provided with the distribution. |
| </P> |
| |
| <LI> |
| <P> |
| Neither the name of the University nor the names of its contributors may be |
| used to endorse or promote products derived from this software without specific |
| prior written permission. |
| </P> |
| |
| </OL> |
| </P> |
| |
| <P> |
| THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS”, |
| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE |
| DISCLAIMED. |
| IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, |
| INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
| BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE |
| OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF |
| ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| </P> |
| |
| |
| <H2>4. SoftFloat Package Directory Structure</H2> |
| |
| <P> |
| Because SoftFloat is targeted to multiple platforms, its source code is |
| slightly scattered between target-specific and target-independent directories |
| and files. |
| The supplied directory structure is as follows: |
| <BLOCKQUOTE> |
| <PRE> |
| doc |
| source |
| include |
| 8086 |
| 8086-SSE |
| ARM-VFPv2 |
| ARM-VFPv2-defaultNaN |
| build |
| template-FAST_INT64 |
| template-not-FAST_INT64 |
| Linux-386-GCC |
| Linux-386-SSE2-GCC |
| Linux-x86_64-GCC |
| Linux-ARM-VFPv2-GCC |
| Win32-MinGW |
| Win32-SSE2-MinGW |
| Win64-MinGW-w64 |
| </PRE> |
| </BLOCKQUOTE> |
| The majority of the SoftFloat sources are provided in the <CODE>source</CODE> |
| directory. |
| The <CODE>include</CODE> subdirectory contains several header files |
| (unsurprisingly), while the other subdirectories of <CODE>source</CODE> contain |
| source files that specialize the floating-point behavior to match particular |
| processor families: |
| <BLOCKQUOTE> |
| <DL> |
| <DT><CODE>8086</CODE></DT> |
| <DD> |
| Intel’s older, 8087-derived floating-point, extended to all supported |
| floating-point types |
| </DD> |
| <DT><CODE>8086-SSE</CODE></DT> |
| <DD> |
| Intel’s x86 processors with Streaming SIMD Extensions (SSE) and later |
| compatible extensions, having 8087 behavior for <NOBR>80-bit</NOBR> |
| double-extended-precision (<CODE>extFloat80_t</CODE>) and SSE behavior for |
| other floating-point types |
| </DD> |
| <DT><CODE>ARM-VFPv2</CODE></DT> |
| <DD> |
| ARM’s VFPv2 or later floating-point, with NaN payload propagation |
| </DD> |
| <DT><CODE>ARM-VFPv2-defaultNaN</CODE></DT> |
| <DD> |
| ARM’s VFPv2 or later floating-point, with the “default NaN” |
| option |
| </DD> |
| </DL> |
| </BLOCKQUOTE> |
| If other specializations are attempted, these would be expected to be other |
| subdirectories of <CODE>source</CODE> alongside the ones listed above. |
| Specialization is covered later, in <NOBR>section 5.2</NOBR>, <I>Specializing |
| Floating-Point Behavior</I>. |
| </P> |
| |
| <P> |
| The <CODE>build</CODE> directory is intended to contain a subdirectory for each |
| target platform for which a build of the SoftFloat library may be created. |
| For each build target, the target’s subdirectory is where all derived |
| object files and the completed SoftFloat library (typically |
| <CODE>softfloat.a</CODE> or <CODE>libsoftfloat.a</CODE>) are created. |
| The two <CODE>template</CODE> subdirectories are not actual build targets but |
| contain sample files for creating new target directories. |
| (The meaning of <CODE>FAST_INT64</CODE> will be explained later.) |
| </P> |
| |
| <P> |
| Ignoring the <CODE>template</CODE> directories, the supplied target directories |
| are intended to follow a naming system of |
| <NOBR><CODE><<I>execution-environment</I>>-<<I>compiler</I>></CODE></NOBR>. |
| For the example targets, |
| <NOBR><CODE><<I>execution-environment</I>></CODE></NOBR> is |
| <NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-386-SSE2</CODE></NOBR>, |
| <NOBR><CODE>Linux-x86_64</CODE></NOBR>, |
| <NOBR><CODE>Linux-ARM-VFPv2</CODE></NOBR>, <CODE>Win32</CODE>, |
| <NOBR><CODE>Win32-SSE2</CODE></NOBR>, or <CODE>Win64</CODE>, and |
| <NOBR><CODE><<I>compiler</I>></CODE></NOBR> is <CODE>GCC</CODE>, |
| <CODE>MinGW</CODE>, or <NOBR><CODE>MinGW-w64</CODE></NOBR>. |
| </P> |
| |
| <P> |
| All of the supplied target directories are merely examples that may or may not |
| be correct for compiling on any particular system. |
| Despite requests, there are currently no plans to include and maintain in the |
| SoftFloat package the build files needed for a great many users’ |
| compilation environments, which can span a huge range of operating systems, |
| compilers, and other tools. |
| </P> |
| |
| <P> |
| As supplied, each target directory contains two files: |
| <BLOCKQUOTE> |
| <PRE> |
| Makefile |
| platform.h |
| </PRE> |
| </BLOCKQUOTE> |
| The provided <CODE>Makefile</CODE> is written for GNU <CODE>make</CODE>. |
| A build of SoftFloat for the specific target is begun by executing the |
| <CODE>make</CODE> command with the target directory as the current directory. |
| A completely different build tool can be used if an appropriate |
| <CODE>Makefile</CODE> equivalent is created. |
| </P> |
| |
| <P> |
| The <CODE>platform.h</CODE> header file exists to provide a location for |
| additional C declarations specific to the build target. |
| Every C source file of SoftFloat contains a <CODE>#include</CODE> for |
| <CODE>platform.h</CODE>. |
| In many cases, the contents of <CODE>platform.h</CODE> can be as simple as one |
| or two lines of code. |
| At the other extreme, to get maximal performance from SoftFloat, it may be |
| desirable to include in header <CODE>platform.h</CODE> (directly or via |
| <CODE>#include</CODE>) declarations for numerous target-specific optimizations. |
| Such possibilities are discussed in the next section, <I>Issues for Porting |
| SoftFloat to a New Target</I>. |
| If the target’s compiler or library has bugs or other shortcomings, |
| workarounds for these issues may also be possible with target-specific |
| declarations in <CODE>platform.h</CODE>, avoiding the need to modify the main |
| SoftFloat sources. |
| </P> |
| |
| |
| <H2>5. Issues for Porting SoftFloat to a New Target</H2> |
| |
| <H3>5.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE></H3> |
| |
| <P> |
| The SoftFloat sources make use of standard headers |
| <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, which have |
| been part of the ISO C Standard Library since 1999. |
| With any recent compiler, these standard headers are likely to be supported, |
| even if the compiler does not claim complete conformance to the latest ISO C |
| Standard. |
| For older or nonstandard compilers, substitutes for |
| <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE> may need to be |
| created. |
| SoftFloat depends on these names from <CODE><stdbool.h></CODE>: |
| <BLOCKQUOTE> |
| <PRE> |
| bool |
| true |
| false |
| </PRE> |
| </BLOCKQUOTE> |
| and on these names from <CODE><stdint.h></CODE>: |
| <BLOCKQUOTE> |
| <PRE> |
| uint16_t |
| uint32_t |
| uint64_t |
| int32_t |
| int64_t |
| UINT64_C |
| INT64_C |
| uint_least8_t |
| uint_fast8_t |
| uint_fast16_t |
| uint_fast32_t |
| uint_fast64_t |
| int_fast8_t |
| int_fast16_t |
| int_fast32_t |
| int_fast64_t |
| </PRE> |
| </BLOCKQUOTE> |
| </P> |
| |
| |
| <H3>5.2. Specializing Floating-Point Behavior</H3> |
| |
| <P> |
| The IEEE Floating-Point Standard allows for some flexibility in a conforming |
| implementation, particularly concerning NaNs. |
| The SoftFloat <CODE>source</CODE> directory is supplied with some |
| <I>specialization</I> subdirectories containing possible definitions for this |
| implementation-specific behavior. |
| For example, the <CODE>8086</CODE> and <NOBR><CODE>8086-SSE</CODE></NOBR> |
| subdirectories have source files that specialize SoftFloat’s behavior to |
| match that of Intel’s x86 line of processors. |
| The files in a specialization subdirectory must determine: |
| <UL> |
| <LI> |
| whether tininess for underflow is detected before or after rounding by default; |
| <LI> |
| how signaling NaNs are distinguished from quiet NaNs; |
| <LI> |
| what (if anything) special happens when exceptions are raised; |
| <LI> |
| the default generated quiet NaNs; |
| <LI> |
| how NaNs are propagated from function inputs to output; and |
| <LI> |
| the integer results returned when conversions to integer type raise the |
| <I>invalid</I> exception. |
| </UL> |
| </P> |
| |
| <P> |
| As provided, the build process for a target expects to involve exactly |
| <EM>one</EM> specialization directory that defines <EM>all</EM> of these |
| implementation-specific details for the target. |
| A specialization directory such as <CODE>8086</CODE> is expected to contain a |
| header file called <CODE>specialize.h</CODE>, together with whatever other |
| source files are needed to complete the specialization. |
| </P> |
| |
| <P> |
| A new build target may use an existing specialization, such as the ones |
| provided by the <CODE>8086</CODE> and <NOBR><CODE>8086-SSE</CODE></NOBR> |
| subdirectories. |
| If a build target needs a new specialization, different from any existing ones, |
| it is recommended that a new specialization directory be created for this |
| purpose. |
| The <CODE>specialize.h</CODE> header file from any of the provided |
| specialization subdirectories can be used as a model for what definitions are |
| needed. |
| </P> |
| |
| |
| <H3>5.3. Macros for Build Options</H3> |
| |
| <P> |
| The SoftFloat source files adapt the floating-point implementation according to |
| several C preprocessor macros: |
| <BLOCKQUOTE> |
| <DL> |
| <DT><CODE>LITTLEENDIAN</CODE> |
| <DD> |
| Must be defined for little-endian machines; must not be defined for big-endian |
| machines. |
| <DT><CODE>INLINE</CODE> |
| <DD> |
| Specifies the sequence of tokens used to indicate that a C function should be |
| inlined. |
| If macro <CODE>INLINE_LEVEL</CODE> is defined with a value of 1 or higher, this |
| macro must be defined; otherwise, this macro is ignored and need not be |
| defined. |
| For compilers that conform to the C Standard’s rules for inline |
| functions, this macro can be defined as the single keyword <CODE>inline</CODE>. |
| For other compilers that follow a convention pre-dating the standardization of |
| <CODE>inline</CODE>, this macro may need to be defined to <CODE>extern</CODE> |
| <CODE>inline</CODE>. |
| <DT><CODE>THREAD_LOCAL</CODE> |
| <DD> |
| Can be defined to a sequence of tokens that, when appearing at the start of a |
| variable declaration, indicates to the C compiler that the variable is |
| <I>per-thread</I>, meaning that each execution thread gets its own separate |
| instance of the variable. |
| This macro is used in header <CODE>softfloat.h</CODE> in the declarations of |
| variables <CODE>softfloat_roundingMode</CODE>, |
| <CODE>softfloat_detectTininess</CODE>, <CODE>extF80_roundingPrecision</CODE>, |
| and <CODE>softfloat_exceptionFlags</CODE>. |
| If macro <CODE>THREAD_LOCAL</CODE> is left undefined, these variables will |
| default to being ordinary global variables. |
| Depending on the compiler, possible valid definitions of this macro include |
| <CODE>_Thread_local</CODE> and <CODE>__thread</CODE>. |
| </DL> |
| <DL> |
| <DT><CODE>SOFTFLOAT_ROUND_ODD</CODE> |
| <DD> |
| Can be defined to enable support for optional rounding mode |
| <CODE>softfloat_round_odd</CODE>. |
| </DL> |
| <DL> |
| <DT><CODE>INLINE_LEVEL</CODE> |
| <DD> |
| Can be defined to an integer to determine the degree of inlining requested of |
| the compiler. |
| Larger numbers request that more inlining be done. |
| If this macro is not defined or is defined to a value less <NOBR>than 1</NOBR> |
| (zero or negative), no inlining is requested. |
| The maximum effective value is no higher <NOBR>than 5</NOBR>. |
| Defining this macro to a value greater than 5 is the same as defining it |
| <NOBR>to 5</NOBR>. |
| <DT><CODE>SOFTFLOAT_FAST_INT64</CODE> |
| <DD> |
| Can be defined to indicate that the build target’s implementation of |
| <NOBR>64-bit</NOBR> arithmetic is efficient. |
| For newer <NOBR>64-bit</NOBR> processors, this macro should usually be defined. |
| For very small microprocessors whose buses and registers are <NOBR>8-bit</NOBR> |
| or <NOBR>16-bit</NOBR> in size, this macro should usually not be defined. |
| Whether this macro should be defined for a <NOBR>32-bit</NOBR> processor may |
| depend on the target machine and the applications that will use SoftFloat. |
| <DT><CODE>SOFTFLOAT_FAST_DIV32TO16</CODE> |
| <DD> |
| Can be defined to indicate that the target’s division operator |
| <NOBR>in C</NOBR> (written as <CODE>/</CODE>) is reasonably efficient for |
| dividing a <NOBR>32-bit</NOBR> unsigned integer by a <NOBR>16-bit</NOBR> |
| unsigned integer. |
| Setting this macro may affect the performance of function <CODE>f16_div</CODE>. |
| <DT><CODE>SOFTFLOAT_FAST_DIV64TO32</CODE> |
| <DD> |
| Can be defined to indicate that the target’s division operator |
| <NOBR>in C</NOBR> (written as <CODE>/</CODE>) is reasonably efficient for |
| dividing a <NOBR>64-bit</NOBR> unsigned integer by a <NOBR>32-bit</NOBR> |
| unsigned integer. |
| Setting this macro may affect the performance of division, remainder, and |
| square root operations other than <CODE>f16_div</CODE>. |
| </DL> |
| </BLOCKQUOTE> |
| </P> |
| |
| <P> |
| Following the usual custom <NOBR>for C</NOBR>, for most of these macros (all |
| except <CODE>INLINE</CODE>, <CODE>THREAD_LOCAL</CODE>, and |
| <CODE>INLINE_LEVEL</CODE>), the content of any definition is irrelevant; |
| what matters is a macro’s effect on <CODE>#ifdef</CODE> directives. |
| </P> |
| |
| <P> |
| It is recommended that any definitions of macros <CODE>LITTLEENDIAN</CODE>, |
| <CODE>INLINE</CODE>, and <CODE>THREAD_LOCAL</CODE> be made in a build |
| target’s <CODE>platform.h</CODE> header file, because these macros are |
| expected to be determined inflexibly by the target machine and compiler. |
| The other five macros select options and control optimization, and thus might |
| be better located in the target’s Makefile (or its equivalent). |
| </P> |
| |
| |
| <H3>5.4. Adapting a Template Target Directory</H3> |
| |
| <P> |
| In the <CODE>build</CODE> directory, two <CODE>template</CODE> subdirectories |
| provide models for new target directories. |
| Two different templates exist because different functions are needed in the |
| SoftFloat library depending on whether macro <CODE>SOFTFLOAT_FAST_INT64</CODE> |
| is defined. |
| If macro <CODE>SOFTFLOAT_FAST_INT64</CODE> will be defined, |
| <NOBR><CODE>template-FAST_INT64</CODE></NOBR> is the template to use; |
| otherwise, <NOBR><CODE>template-not-FAST_INT64</CODE></NOBR> is the appropriate |
| template. |
| A new target directory can be created by copying the correct template directory |
| and editing the files inside. |
| To avoid confusion, it would be wise to refrain from editing the files within a |
| template directory directly. |
| </P> |
| |
| |
| <H3>5.5. Target-Specific Optimization of Primitive Functions</H3> |
| |
| <P> |
| Header file <CODE>primitives.h</CODE> (in directory |
| <CODE>source/include</CODE>) declares macros and functions for numerous |
| underlying arithmetic operations upon which many of SoftFloat’s |
| floating-point functions are ultimately built. |
| The SoftFloat sources include implementations of all of these functions/macros, |
| written as standard C code, so a complete and correct SoftFloat library can be |
| created using only the supplied code for all functions. |
| However, for many targets, SoftFloat’s performance can be improved by |
| substituting target-specific implementations of some of the functions/macros |
| declared in <CODE>primitives.h</CODE>. |
| </P> |
| |
| <P> |
| For example, <CODE>primitives.h</CODE> declares a function called |
| <CODE>softfloat_countLeadingZeros32</CODE> that takes an unsigned |
| <NOBR>32-bit</NOBR> integer as an argument and returns the number of the |
| integer’s most-significant bits that are zeros. |
| While the SoftFloat sources include an implementation of this function written |
| in <NOBR>standard C</NOBR>, many processors can perform this same function |
| directly in only one or two machine instructions. |
| An alternative, target-specific implementation that maps to those instructions |
| is likely to be more efficient than the generic C code from the SoftFloat |
| package. |
| </P> |
| |
| <P> |
| A build target can replace the supplied version of any function or macro of |
| <CODE>primitives.h</CODE> by defining a macro with the same name in the |
| target’s <CODE>platform.h</CODE> header file. |
| For this purpose, it may be helpful for <CODE>platform.h</CODE> to |
| <CODE>#include</CODE> header file <CODE>primitiveTypes.h</CODE>, which defines |
| types used for arguments and results of functions declared in |
| <CODE>primitives.h</CODE>. |
| When a desired replacement implementation is a function, not a macro, it is |
| sufficient for <CODE>platform.h</CODE> to include the line |
| <BLOCKQUOTE> |
| <PRE> |
| #define <<I>function-name</I>> <<I>function-name</I>> |
| </PRE> |
| </BLOCKQUOTE> |
| where <NOBR><CODE><<I>function-name</I>></CODE></NOBR> is the name of the |
| function. |
| This technically defines <NOBR><CODE><<I>function-name</I>></CODE></NOBR> |
| as a macro, but one that resolves to the same name, which may then be a |
| function. |
| (A preprocessor that conforms to the C Standard is required to limit recursive |
| macro expansion from being applied more than once.) |
| </P> |
| |
| <P> |
| The supplied header file <CODE>opts-GCC.h</CODE> (in directory |
| <CODE>source/include</CODE>) provides an example of target-specific |
| optimization for the GCC compiler. |
| Each GCC target example in the <CODE>build</CODE> directory has |
| <BLOCKQUOTE> |
| <CODE>#include "opts-GCC.h"</CODE> |
| </BLOCKQUOTE> |
| in its <CODE>platform.h</CODE> header file. |
| Before <CODE>opts-GCC.h</CODE> is included, the following macros must be |
| defined (or not) to control which features are invoked: |
| <BLOCKQUOTE> |
| <DL> |
| <DT><CODE>SOFTFLOAT_BUILTIN_CLZ</CODE></DT> |
| <DD> |
| If defined, SoftFloat’s internal |
| ‘<CODE>countLeadingZeros</CODE>’ functions use intrinsics |
| <CODE>__builtin_clz</CODE> and <CODE>__builtin_clzll</CODE>. |
| </DD> |
| <DT><CODE>SOFTFLOAT_INTRINSIC_INT128</CODE></DT> |
| <DD> |
| If defined, SoftFloat makes use of GCC’s nonstandard <NOBR>128-bit</NOBR> |
| integer type <CODE>__int128</CODE>. |
| </DD> |
| </DL> |
| </BLOCKQUOTE> |
| On some machines, these improvements are observed to increase the speeds of |
| <CODE>f64_mul</CODE> and <CODE>f128_mul</CODE> by around 20 to 25%, although |
| other functions receive less dramatic boosts, or none at all. |
| Results can vary greatly across different platforms. |
| </P> |
| |
| |
| <H2>6. Testing SoftFloat</H2> |
| |
| <P> |
| SoftFloat can be tested using the <CODE>testsoftfloat</CODE> program by the |
| same author. |
| This program is part of the Berkeley TestFloat package available at the Web |
| page |
| <A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><NOBR><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></NOBR></A>. |
| The TestFloat package also has a program called <CODE>timesoftfloat</CODE> that |
| measures the speed of SoftFloat’s floating-point functions. |
| </P> |
| |
| |
| <H2>7. Providing SoftFloat as a Common Library for Applications</H2> |
| |
| <P> |
| Header file <CODE>softfloat.h</CODE> defines the SoftFloat interface as seen by |
| clients. |
| If the SoftFloat library will be made a common library for programs on a |
| system, the supplied <CODE>softfloat.h</CODE> has a couple of deficiencies for |
| this purpose: |
| <UL> |
| <LI> |
| As supplied, <CODE>softfloat.h</CODE> depends on another header, |
| <CODE>softfloat_types.h</CODE>, that is not intended for public use but which |
| must also be visible to the programmer’s compiler. |
| <LI> |
| More troubling, at the time <CODE>softfloat.h</CODE> is included in a C source |
| file, macros <CODE>SOFTFLOAT_FAST_INT64</CODE> and <CODE>THREAD_LOCAL</CODE> |
| must be defined, or not defined, consistent with how these macro were defined |
| when the SoftFloat library was built. |
| </UL> |
| In the situation that new programs may regularly <CODE>#include</CODE> header |
| file <CODE>softfloat.h</CODE>, it is recommended that a custom, self-contained |
| version of this header file be created that eliminates these issues. |
| </P> |
| |
| |
| <H2>8. Contact Information</H2> |
| |
| <P> |
| At the time of this writing, the most up-to-date information about SoftFloat |
| and the latest release can be found at the Web page |
| <A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></A>. |
| </P> |
| |
| |
| </BODY> |
| |
