diff options
Diffstat (limited to 'doc/SoftFloat-source.html')
| -rw-r--r-- | doc/SoftFloat-source.html | 99 |
1 files changed, 62 insertions, 37 deletions
diff --git a/doc/SoftFloat-source.html b/doc/SoftFloat-source.html index dff77aa..b69565f 100644 --- a/doc/SoftFloat-source.html +++ b/doc/SoftFloat-source.html @@ -7,11 +7,11 @@ <BODY> -<H1>Berkeley SoftFloat Release 3a: Source Documentation</H1> +<H1>Berkeley SoftFloat Release 3b: Source Documentation</H1> <P> John R. Hauser<BR> -2015 October 23<BR> +2016 July 22<BR> </P> @@ -53,7 +53,7 @@ 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>. +<A HREF="SoftFloat.html"><NOBR><CODE>SoftFloat.html</CODE></NOBR></A>. </P> <P> @@ -68,8 +68,8 @@ SoftFloat has been successfully compiled with the GNU C Compiler <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"><CODE>SoftFloat.html</CODE></A>. -The current version of SoftFloat is <NOBR>Release 3a</NOBR>. +<A HREF="SoftFloat.html"><NOBR><CODE>SoftFloat.html</CODE></NOBR></A>. +The current version of SoftFloat is <NOBR>Release 3b</NOBR>. </P> @@ -114,10 +114,10 @@ SoftFloat’s dependence on these headers is detailed later in 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> (and <NOBR>now 3a</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 project to create <NOBR>Release 3</NOBR> (now <NOBR>through 3b</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> @@ -148,12 +148,12 @@ Oracle, and Samsung. </P> <P> -The following applies to the whole of SoftFloat <NOBR>Release 3a</NOBR> as well +The following applies to the whole of SoftFloat <NOBR>Release 3b</NOBR> as well as to each source file individually. </P> <P> -Copyright 2011, 2012, 2013, 2014, 2015 The Regents of the University of +Copyright 2011, 2012, 2013, 2014, 2015, 2016 The Regents of the University of California. All rights reserved. </P> @@ -236,9 +236,9 @@ 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. +non-extended formats (<CODE>float16_t</CODE>, <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>. @@ -370,9 +370,12 @@ 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 +the default generated quiet NaNs; <LI> -how NaNs are propagated from function inputs to output. +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> @@ -418,6 +421,13 @@ 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 @@ -425,7 +435,7 @@ Can be defined to indicate that the target’s division operator 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. +square root operations other than <CODE>f16_div</CODE>. <DT><CODE>INLINE_LEVEL</CODE> <DD> Can be defined to an integer to determine the degree of inlining requested of @@ -443,26 +453,41 @@ 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 +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>. -Historically, the <CODE>gcc</CODE> compiler has required that this macro 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> </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; +Following the usual custom <NOBR>for C</NOBR>, for the first four macros (all +except <CODE>INLINE_LEVEL</CODE>, <CODE>INLINE</CODE>, and +<CODE>THREAD_LOCAL</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. +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 three macros control optimization and might be better located in the target’s Makefile (or its equivalent). </P> @@ -496,7 +521,7 @@ 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. +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>. @@ -505,8 +530,8 @@ declared in <CODE>primitives.h</CODE>. <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. +<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. @@ -534,7 +559,7 @@ 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 +(A preprocessor that conforms to the C Standard must limit recursive macro expansion from being applied more than once.) </P> @@ -546,7 +571,7 @@ 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>. +<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> @@ -566,10 +591,10 @@ 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. +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 @@ -582,7 +607,7 @@ version of this header file be created that eliminates these issues. <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>. +<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></A>. </P> |