doc/SoftFloat-source.html - berkeley-softfloat-3 - Git at Google


 <HTML>

 <HEAD>
 <TITLE>Berkeley SoftFloat Source Documentation</TITLE>
 </HEAD>

 <BODY>

 <H1>Berkeley SoftFloat Release 3: Source Documentation</H1>

 <P>
 John R. Hauser<BR>
 2014 _____<BR>
 </P>

 <P>
 *** REPLACE QUOTATION MARKS.
 </P>


 <H2>Contents</H2>

 <P>
 *** CHECK.<BR>
 *** FIX FORMATTING.
 </P>

 <PRE>
     Introduction
     Limitations
     Acknowledgments and License
     SoftFloat Package Directory Structure
     Issues for Porting SoftFloat to a New Target
         Standard Headers &lt;stdbool.h&gt; and &lt;stdint.h&gt;
         Specializing Floating-Point Behavior
         Macros for Build Options
         Adapting a Template Target Directory
         Target-Specific Optimization of Primitive Functions
     Testing SoftFloat
     Providing SoftFloat as a Common Library for Applications
     Contact Information
 </PRE>


 <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>&lt;stdbool.h&gt;</CODE> and
 <CODE>&lt;stdint.h&gt;</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 &lt;stdbool.h&gt; and
 &lt;stdint.h&gt;</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 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>
 <TR>
 <TD><NOBR>Par Lab:</NOBR></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><NOBR>ASPIRE Lab:</NOBR></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 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:
 <PRE>
      doc
      source
          include
          8086
      build
          template-FAST_INT64
          template-not-FAST_INT64
          Linux-386-GCC
          Linux-x86_64-GCC
          Win32-MinGW
          Win64-MinGW-w64
 </PRE>
 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> subdirectory
 contains source files that specialize the floating-point behavior to match the
 Intel x86 line of processors.
 If other specializations are attempted, these would be expected to be other
 subdirectories of <CODE>source</CODE> alongside <CODE>8086</CODE>.
 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>&lt;execution-environment&gt;-&lt;compiler&gt;</CODE></NOBR>.
 For the example targets,
 <NOBR><CODE>&lt;execution-environment&gt;</CODE></NOBR> is
 <NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-x86_64</CODE></NOBR>,
 <CODE>Win32</CODE>, or <CODE>Win64</CODE>, and
 <NOBR><CODE>&lt;compiler&gt;</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:
 <PRE>
      Makefile
      platform.h
 </PRE>
 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>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</CODE></H3>

 <P>
 The SoftFloat sources make use of standard headers
 <CODE>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</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>&lt;stdbool.h&gt;</CODE> and <CODE>&lt;stdint.h&gt;</CODE> may need to be
 created.
 SoftFloat depends on these names from <CODE>&lt;stdbool.h&gt;</CODE>:
 <PRE>
      bool
      true
      false
 </PRE>
 and on these names from <CODE>&lt;stdint.h&gt;</CODE>:
 <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>
 </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 one or more
 <I>specialization</I> subdirectories containing possible definitions for this
 implementation-specific behavior.
 For example, the <CODE>8086</CODE> subdirectory has 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 one provided
 by the <CODE>8086</CODE> subdirectory.
 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
 <CODE>64-bit</CODE> arithmetic is efficient.
 For newer <CODE>64-bit</CODE> processors, this macro should usually be defined.
 For very small microprocessors whose buses and registers are <CODE>8-bit</CODE>
 or <CODE>16-bit</CODE> in size, this macro should usually not be defined.
 Whether this macro should be defined for a <CODE>32-bit</CODE> 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 <CODE>64-bit</CODE> unsigned integer by a <CODE>32-bit</CODE>
 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,
 <CODE>template-FAST_INT64</CODE> is the template to use;
 otherwise, <CODE>template-not-FAST_INT64</CODE> 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
 <PRE>
      #define &lt;function-name&gt; &lt;function-name&gt;
 </PRE>
 where <CODE>&lt;function-name&gt;</CODE> is the name of the function.
 This technically defines <CODE>&lt;function-name&gt;</CODE> 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>
 Supplied <CODE>softfloat.h</CODE> depends on <CODE>softfloat_types.h</CODE>.
 </P>

 <PRE>
 The target-specific `softfloat.h' header file defines the SoftFloat
 interface as seen by clients.

 Unlike the actual function definitions in `softfloat.c', the declarations
 in `softfloat.h' do not use any of the types defined by the `processors'
 header file.  This is done so that clients will not have to include the
 `processors' header file in order to use SoftFloat.  Nevertheless, the
 target-specific declarations in `softfloat.h' must match what `softfloat.c'
 expects.  For example, if `int32' is defined as `int' in the `processors'
 header file, then in `softfloat.h' the output of `float32_to_int32' should
 be stated as `int', although in `softfloat.c' it is given in target-
 independent form as `int32'.
 </PRE>

 <PRE>
 *** HERE

 Porting and/or compiling SoftFloat involves the following steps:

 4. In the target-specific subdirectory, edit the files `softfloat-specialize'
    and `softfloat.h' to define the desired exception handling functions
    and mode control values.  In the `softfloat.h' header file, ensure also
    that all declarations give the proper target-specific type (such as
    `int' or `long') corresponding to the target-independent type used in
    `softfloat.c' (such as `int32').  None of the type names declared in the
    `processors' header file should appear in `softfloat.h'.

 </PRE>


 <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>

	<HTML>

	<HEAD>
	<TITLE>Berkeley SoftFloat Source Documentation</TITLE>
	</HEAD>

	<BODY>

	<H1>Berkeley SoftFloat Release 3: Source Documentation</H1>

	<P>
	John R. Hauser<BR>
	2014 _____<BR>
	</P>

	<P>
	*** REPLACE QUOTATION MARKS.
	</P>


	<H2>Contents</H2>

	<P>
	*** CHECK.<BR>
	*** FIX FORMATTING.
	</P>

	<PRE>
	Introduction
	Limitations
	Acknowledgments and License
	SoftFloat Package Directory Structure
	Issues for Porting SoftFloat to a New Target
	Standard Headers <stdbool.h> and <stdint.h>
	Specializing Floating-Point Behavior
	Macros for Build Options
	Adapting a Template Target Directory
	Target-Specific Optimization of Primitive Functions
	Testing SoftFloat
	Providing SoftFloat as a Common Library for Applications
	Contact Information
	</PRE>


	<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 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>
	<TR>
	<TD><NOBR>Par Lab:</NOBR></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><NOBR>ASPIRE Lab:</NOBR></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 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:
	<PRE>
	doc
	source
	include
	8086
	build
	template-FAST_INT64
	template-not-FAST_INT64
	Linux-386-GCC
	Linux-x86_64-GCC
	Win32-MinGW
	Win64-MinGW-w64
	</PRE>
	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> subdirectory
	contains source files that specialize the floating-point behavior to match the
	Intel x86 line of processors.
	If other specializations are attempted, these would be expected to be other
	subdirectories of <CODE>source</CODE> alongside <CODE>8086</CODE>.
	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-x86_64</CODE></NOBR>,
	<CODE>Win32</CODE>, 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:
	<PRE>
	Makefile
	platform.h
	</PRE>
	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>:
	<PRE>
	bool
	true
	false
	</PRE>
	and on these names from <CODE><stdint.h></CODE>:
	<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>
	</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 one or more
	<I>specialization</I> subdirectories containing possible definitions for this
	implementation-specific behavior.
	For example, the <CODE>8086</CODE> subdirectory has 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 one provided
	by the <CODE>8086</CODE> subdirectory.
	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
	<CODE>64-bit</CODE> arithmetic is efficient.
	For newer <CODE>64-bit</CODE> processors, this macro should usually be defined.
	For very small microprocessors whose buses and registers are <CODE>8-bit</CODE>
	or <CODE>16-bit</CODE> in size, this macro should usually not be defined.
	Whether this macro should be defined for a <CODE>32-bit</CODE> 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 <CODE>64-bit</CODE> unsigned integer by a <CODE>32-bit</CODE>
	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,
	<CODE>template-FAST_INT64</CODE> is the template to use;
	otherwise, <CODE>template-not-FAST_INT64</CODE> 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
	<PRE>
	#define <function-name> <function-name>
	</PRE>
	where <CODE><function-name></CODE> is the name of the function.
	This technically defines <CODE><function-name></CODE> 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>
	Supplied <CODE>softfloat.h</CODE> depends on <CODE>softfloat_types.h</CODE>.
	</P>

	<PRE>
	The target-specific `softfloat.h' header file defines the SoftFloat
	interface as seen by clients.

	Unlike the actual function definitions in `softfloat.c', the declarations
	in `softfloat.h' do not use any of the types defined by the `processors'
	header file. This is done so that clients will not have to include the
	`processors' header file in order to use SoftFloat. Nevertheless, the
	target-specific declarations in `softfloat.h' must match what `softfloat.c'
	expects. For example, if `int32' is defined as `int' in the `processors'
	header file, then in `softfloat.h' the output of `float32_to_int32' should
	be stated as `int', although in `softfloat.c' it is given in target-
	independent form as `int32'.
	</PRE>

	<PRE>
	*** HERE

	Porting and/or compiling SoftFloat involves the following steps:

	4. In the target-specific subdirectory, edit the files `softfloat-specialize'
	and `softfloat.h' to define the desired exception handling functions
	and mode control values. In the `softfloat.h' header file, ensure also
	that all declarations give the proper target-specific type (such as
	`int' or `long') corresponding to the target-independent type used in
	`softfloat.c' (such as `int32'). None of the type names declared in the
	`processors' header file should appear in `softfloat.h'.

	</PRE>


	<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>