SoftFloat-source.html@ 99863

Last change on this file since 99863 was 94480, checked in by vboxsync, 3 years ago
libs/softfloat-3e: Copied from vendor branch (SoftFloat-3e.zip, md5: 7dac954ea4aed0697cbfee800ba4f492). bugref:9898
Property svn:eol-style set to `native` Property svn:mime-type set to `text/html`
File size: 24.5 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/softfloat-3e/doc/SoftFloat-source.html@ 99863

Download in other formats: