mirror of
https://github.com/urbit/shrub.git
synced 2024-12-18 15:55:00 +03:00
577 lines
21 KiB
HTML
577 lines
21 KiB
HTML
|
|
<HTML>
|
|
|
|
<HEAD>
|
|
<TITLE>Berkeley SoftFloat Source Documentation</TITLE>
|
|
</HEAD>
|
|
|
|
<BODY>
|
|
|
|
<H1>Berkeley SoftFloat Release 3: Source Documentation</H1>
|
|
|
|
<P>
|
|
John R. Hauser<BR>
|
|
2015 February 16<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"><CODE>SoftFloat.html</CODE></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 is 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"><CODE>SoftFloat.html</CODE></A>.
|
|
</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
|
|
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 <stdbool.h> and
|
|
<stdint.h></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 is a completely new implementation
|
|
supplanting earlier releases.
|
|
This project (<NOBR>Release 3</NOBR> only, not earlier releases) 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 3</NOBR> as well
|
|
as to each source file individually.
|
|
</P>
|
|
|
|
<P>
|
|
Copyright 2011, 2012, 2013, 2014, 2015 The Regents of the University of
|
|
California (Regents).
|
|
All Rights Reserved.
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
</P>
|
|
|
|
<P>
|
|
Redistributions of source code must retain the above copyright notice, this
|
|
list of conditions, and the following two paragraphs of disclaimer.
|
|
Redistributions in binary form must reproduce the above copyright notice, this
|
|
list of conditions, and the following two paragraphs of disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
Neither the name of the Regents nor the names of its contributors may be used
|
|
to endorse or promote products derived from this software without specific
|
|
prior written permission.
|
|
</P>
|
|
|
|
<P>
|
|
IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL,
|
|
INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF
|
|
THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS BEEN
|
|
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
</P>
|
|
|
|
<P>
|
|
REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
|
|
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS
|
|
PROVIDED "<NOBR>AS IS</NOBR>".
|
|
REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
|
|
ENHANCEMENTS, OR MODIFICATIONS.
|
|
</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
|
|
build
|
|
template-FAST_INT64
|
|
template-not-FAST_INT64
|
|
Linux-386-GCC
|
|
Linux-386-SSE2-GCC
|
|
Linux-x86_64-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 of <CODE>source</CODE> contains several
|
|
header files (unsurprisingly), while the <CODE>8086</CODE> and
|
|
<NOBR><CODE>8086-SSE</CODE></NOBR> subdirectories contain source files that
|
|
specialize the floating-point behavior to match the Intel x86 line of
|
|
processors.
|
|
The files in directory <CODE>8086</CODE> give floating-point behavior
|
|
consistent solely with Intel’s older, 8087-derived floating-point, while
|
|
those in <NOBR><CODE>8086-SSE</CODE></NOBR> update the behavior of the
|
|
non-extended formats (<CODE>float32_t</CODE>, <CODE>float64_t</CODE>, and
|
|
<CODE>float128_t</CODE>) to mirror Intel’s more recent Streaming SIMD
|
|
Extensions (SSE) and other compatible extensions.
|
|
If other specializations are attempted, these would be expected to be other
|
|
subdirectories of <CODE>source</CODE> alongside <CODE>8086</CODE> and
|
|
<NOBR><CODE>8086-SSE</CODE></NOBR>.
|
|
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><execution-environment>-<compiler></CODE></NOBR>.
|
|
For the example targets,
|
|
<NOBR><CODE><execution-environment></CODE></NOBR> is
|
|
<NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-386-SSE2</CODE></NOBR>,
|
|
<NOBR><CODE>Linux-x86_64</CODE></NOBR>, <CODE>Win32</CODE>,
|
|
<NOBR><CODE>Win32-SSE2</CODE></NOBR>, or <CODE>Win64</CODE>, and
|
|
<NOBR><CODE><compiler></CODE></NOBR> is <CODE>GCC</CODE>,
|
|
<CODE>MinGW</CODE>, or <NOBR><CODE>MinGW-w64</CODE></NOBR>.
|
|
</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>
|
|
what (if anything) special happens when exceptions are raised;
|
|
<LI>
|
|
how signaling NaNs are distinguished from quiet NaNs;
|
|
<LI>
|
|
the default generated quiet NaNs; and
|
|
<LI>
|
|
how NaNs are propagated from function inputs to output.
|
|
</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 subdirectory be created in the
|
|
<CODE>source</CODE> directory 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
|
|
a few 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>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_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.
|
|
<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>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 some compilers, this macro can be defined as the single keyword
|
|
<CODE>inline</CODE>.
|
|
Historically, the <CODE>gcc</CODE> compiler has required that this macro be
|
|
defined to <CODE>extern</CODE> <CODE>inline</CODE>.
|
|
</DL>
|
|
</BLOCKQUOTE>
|
|
</P>
|
|
|
|
<P>
|
|
Following the usual custom <NOBR>for C</NOBR>, for the first three macros (all
|
|
except <CODE>INLINE_LEVEL</CODE> and <CODE>INLINE</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> and
|
|
<CODE>INLINE</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 three macros control optimization and 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
|
|
built 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 maximal number of
|
|
the integer’s most-significant bits that are all 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 <function-name> <function-name>
|
|
</PRE>
|
|
</BLOCKQUOTE>
|
|
where <NOBR><CODE><function-name></CODE></NOBR> is the name of the
|
|
function.
|
|
This technically defines <NOBR><CODE><function-name></CODE></NOBR> as a
|
|
macro, but one that resolves to the same name, which may then be a function.
|
|
(A preprocessor conforming to the C Standard must limit recursive macro
|
|
expansion from being applied more than once.)
|
|
</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"><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></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
|
|
particular 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, macro <CODE>SOFTFLOAT_FAST_INT64</CODE> must be defined, or not
|
|
defined, consistent with whether this macro was 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"><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></A>.
|
|
</P>
|
|
|
|
|
|
</BODY>
|
|
|