TestFloat-source.html

Last change on this file was 94551, checked in by vboxsync, 3 years ago
libs/softfloat: Copied TestFloat-3e from vendor branch and to testfloat subdir. bugref:9898
Property svn:eol-style set to `native` Property svn:mime-type set to `text/html`
File size: 23.3 KB

Line
1
2	<HTML>
3
4	<HEAD>
5	<TITLE>Berkeley TestFloat Source Documentation</TITLE>
6	</HEAD>
7
8	<BODY>
9
10	<H1>Berkeley TestFloat 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. TestFloat Package Directory Structure</TD></TR>
28	<TR><TD COLSPAN=2>5. Dependence on Berkeley SoftFloat</TD></TR>
29	<TR><TD COLSPAN=2>6. Issues for Porting TestFloat to a New Target</TD></TR>
30	<TR>
31	<TD></TD>
32	<TD>6.1. Standard Headers <CODE><stdbool.h></CODE> and
33	<CODE><stdint.h></CODE></TD>
34	</TR>
35	<TR><TD></TD><TD>6.2. Standard Header <CODE><fenv.h></CODE></TD></TR>
36	<TR><TD></TD><TD>6.3. Macros for Build Options</TD></TR>
37	<TR><TD></TD><TD>6.4. Specializing the <CODE>testfloat</CODE> Program</TD></TR>
38	<TR><TD></TD><TD>6.5. Improving the Random Number Functions</TD></TR>
39	<TR><TD COLSPAN=2>7. Contact Information</TD></TR>
40	</TABLE>
41	</BLOCKQUOTE>
42
43
44	<H2>1. Introduction</H2>
45
46	<P>
47	This document gives information needed for compiling and/or porting Berkeley
48	TestFloat, a small collection of programs for testing that an implementation of
49	binary floating-point conforms to the IEEE Standard for Floating-Point
50	Arithmetic.
51	For basic documentation about TestFloat refer to
52	<A HREF="TestFloat-general.html"><NOBR><CODE>TestFloat-general.html</CODE></NOBR></A>.
53	</P>
54
55	<P>
56	The source code for TestFloat is intended to be relatively machine-independent.
57	Most programs in the TestFloat package should be compilable with any
58	ISO-Standard C compiler that also supports <NOBR>64-bit</NOBR> integers.
59	If the all-in-one <CODE>testfloat</CODE> program will be used to test a new
60	floating-point implementation, additional effort will likely be required to
61	retarget that program to invoke the new floating-point operations.
62	TestFloat has been successfully compiled with the GNU C Compiler
63	(<CODE>gcc</CODE>) for several platforms.
64	</P>
65
66	<P>
67	<NOBR>Release 3</NOBR> of TestFloat was a complete rewrite relative to
68	<NOBR>Release 2c</NOBR> or earlier.
69	The current version of TestFloat is <NOBR>Release 3e</NOBR>.
70	</P>
71
72	<P>
73	TestFloat depends on Berkeley SoftFloat, which is a software implementation of
74	binary floating-point that conforms to the IEEE Standard for Floating-Point
75	Arithmetic.
76	SoftFloat is not included with the TestFloat sources.
77	It can be obtained from the Web page
78	<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></A>.
79	</P>
80
81
82	<H2>2. Limitations</H2>
83
84	<P>
85	TestFloat assumes the computer has an addressable byte size of either 8 or
86	<NOBR>16 bits</NOBR>.
87	(Nearly all computers in use today have <NOBR>8-bit</NOBR> bytes.)
88	</P>
89
90	<P>
91	TestFloat is written entirely <NOBR>in C</NOBR>.
92	The C compiler used must conform at a minimum to the 1989 ANSI standard for the
93	C language (same as the 1990 ISO standard) and must in addition support basic
94	arithmetic on <NOBR>64-bit</NOBR> integers.
95	Earlier releases of TestFloat were capable of testing <NOBR>32-bit</NOBR>
96	single-precision and <NOBR>64-bit</NOBR> double-precision floating-point
97	without requiring compiler support for <NOBR>64-bit</NOBR> integers, but this
98	option is not supported starting with <NOBR>Release 3</NOBR>.
99	Since 1999, ISO standards for C have mandated compiler support for
100	<NOBR>64-bit</NOBR> integers.
101	A compiler conforming to the 1999 C Standard or later is recommended but not
102	strictly required.
103	</P>
104
105	<P>
106	<NOBR>C Standard</NOBR> header files <CODE><stdbool.h></CODE> and
107	<CODE><stdint.h></CODE> are required for defining standard Boolean and
108	integer types.
109	If these headers are not supplied with the C compiler, minimal substitutes must
110	be provided.
111	TestFloat’s dependence on these headers is detailed later in
112	<NOBR>section 6.1</NOBR>, <I>Standard Headers <CODE><stdbool.h></CODE>
113	and <CODE><stdint.h></CODE></I>.
114	</P>
115
116
117	<H2>3. Acknowledgments and License</H2>
118
119	<P>
120	The TestFloat package was written by me, <NOBR>John R.</NOBR> Hauser.
121	<NOBR>Release 3</NOBR> of TestFloat was a completely new implementation
122	supplanting earlier releases.
123	The project to create <NOBR>Release 3</NOBR> (now <NOBR>through 3e</NOBR>) was
124	done in the employ of the University of California, Berkeley, within the
125	Department of Electrical Engineering and Computer Sciences, first for the
126	Parallel Computing Laboratory (Par Lab) and then for the ASPIRE Lab.
127	The work was officially overseen by Prof. Krste Asanovic, with funding provided
128	by these sources:
129	<BLOCKQUOTE>
130	<TABLE>
131	<COL>
132	<COL WIDTH=10>
133	<COL>
134	<TR>
135	<TD VALIGN=TOP><NOBR>Par Lab:</NOBR></TD>
136	<TD></TD>
137	<TD>
138	Microsoft (Award #024263), Intel (Award #024894), and U.C. Discovery
139	(Award #DIG07-10227), with additional support from Par Lab affiliates Nokia,
140	NVIDIA, Oracle, and Samsung.
141	</TD>
142	</TR>
143	<TR>
144	<TD VALIGN=TOP><NOBR>ASPIRE Lab:</NOBR></TD>
145	<TD></TD>
146	<TD>
147	DARPA PERFECT program (Award #HR0011-12-2-0016), with additional support from
148	ASPIRE industrial sponsor Intel and ASPIRE affiliates Google, Nokia, NVIDIA,
149	Oracle, and Samsung.
150	</TD>
151	</TR>
152	</TABLE>
153	</BLOCKQUOTE>
154	</P>
155
156	<P>
157	The following applies to the whole of TestFloat <NOBR>Release 3e</NOBR> as well
158	as to each source file individually.
159	</P>
160
161	<P>
162	Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 The Regents of the
163	University of California.
164	All rights reserved.
165	</P>
166
167	<P>
168	Redistribution and use in source and binary forms, with or without
169	modification, are permitted provided that the following conditions are met:
170	<OL>
171
172	<LI>
173	<P>
174	Redistributions of source code must retain the above copyright notice, this
175	list of conditions, and the following disclaimer.
176	</P>
177
178	<LI>
179	<P>
180	Redistributions in binary form must reproduce the above copyright notice, this
181	list of conditions, and the following disclaimer in the documentation and/or
182	other materials provided with the distribution.
183	</P>
184
185	<LI>
186	<P>
187	Neither the name of the University nor the names of its contributors may be
188	used to endorse or promote products derived from this software without specific
189	prior written permission.
190	</P>
191
192	</OL>
193	</P>
194
195	<P>
196	THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS”,
197	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
198	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE
199	DISCLAIMED.
200	IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
201	INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
202	BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
203	DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
204	LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
205	OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
206	ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
207	</P>
208
209
210	<H2>4. TestFloat Package Directory Structure</H2>
211
212	<P>
213	Because TestFloat is targeted to multiple platforms, its source code is
214	slightly scattered between target-specific and target-independent directories
215	and files.
216	The supplied directory structure is as follows:
217	<BLOCKQUOTE>
218	<PRE>
219	doc
220	source
221	subj-C
222	build
223	template
224	Linux-386-GCC
225	Linux-386-SSE2-GCC
226	Linux-x86_64-GCC
227	Linux-ARM-VFPv2-GCC
228	Win32-MinGW
229	Win32-SSE2-MinGW
230	Win64-MinGW-w64
231	</PRE>
232	</BLOCKQUOTE>
233	The majority of the TestFloat sources are provided in the <CODE>source</CODE>
234	directory.
235	The <NOBR><CODE>subj-C</CODE></NOBR> subdirectory contains the sources that
236	configure the all-in-one <CODE>testfloat</CODE> program to test the C
237	compiler’s implementation of the standard C types <CODE>float</CODE>,
238	<CODE>double</CODE>, and possibly <CODE>long</CODE> <CODE>double</CODE>.
239	The ‘<CODE>subj</CODE>’ in <NOBR><CODE>subj-C</CODE></NOBR> is an
240	abbreviation of <I>subject</I>, referring to the floating-point that is the
241	subject of the test.
242	If <CODE>testfloat</CODE> is retargeted to test other floating-point
243	implementations, the corresponding source files would be expected to be in
244	other subdirectories alongside <NOBR><CODE>subj-C</CODE></NOBR>, with names of
245	the form <NOBR><CODE>subj-<<I>target</I>></CODE></NOBR>.
246	More about retargeting <CODE>testfloat</CODE> is found in
247	<NOBR>section 6.4</NOBR>, <I>Specializing the <CODE>testfloat</CODE>
248	Program</I>.
249	</P>
250
251	<P>
252	The <CODE>build</CODE> directory is intended to contain a subdirectory for each
253	target platform for which builds of the TestFloat programs may be created.
254	For each build target, the target’s subdirectory is where all derived
255	object files and the completed TestFloat executables are created.
256	The <CODE>template</CODE> subdirectory is not an actual build target but
257	contains sample files for creating new target directories.
258	</P>
259
260	<P>
261	Ignoring the <CODE>template</CODE> directory, the supplied target directories
262	are intended to follow a naming system of
263	<NOBR><CODE><<I>execution-environment</I>>-<<I>compiler</I>></CODE></NOBR>.
264	For the example targets,
265	<NOBR><CODE><<I>execution-environment</I>></CODE></NOBR> is
266	<NOBR><CODE>Linux-386</CODE></NOBR>, <NOBR><CODE>Linux-386-SSE2</CODE></NOBR>,
267	<NOBR><CODE>Linux-x86_64</CODE></NOBR>,
268	<NOBR><CODE>Linux-ARM-VFPv2</CODE></NOBR>, <CODE>Win32</CODE>,
269	<NOBR><CODE>Win32-SSE2</CODE></NOBR>, or <CODE>Win64</CODE>, and
270	<NOBR><CODE><<I>compiler</I>></CODE></NOBR> is <CODE>GCC</CODE>,
271	<CODE>MinGW</CODE>, or <NOBR><CODE>MinGW-w64</CODE></NOBR>.
272	</P>
273
274	<P>
275	All of the supplied target directories are merely examples that may or may not
276	be correct for compiling on any particular system.
277	There are currently no plans to include and maintain in the TestFloat package
278	the build files needed for a great many users’ compilation environments,
279	which can span a huge range of operating systems, compilers, and other tools.
280	</P>
281
282	<P>
283	As supplied, each target directory contains two files:
284	<BLOCKQUOTE>
285	<PRE>
286	Makefile
287	platform.h
288	</PRE>
289	</BLOCKQUOTE>
290	The provided <CODE>Makefile</CODE> is written for GNU <CODE>make</CODE>.
291	A build of TestFloat for the specific target is begun by executing the
292	<CODE>make</CODE> command with the target directory as the current directory.
293	A completely different build tool can be used if an appropriate
294	<CODE>Makefile</CODE> equivalent is created.
295	</P>
296
297	<P>
298	The <CODE>platform.h</CODE> header file exists to provide a location for
299	additional C declarations specific to the build target.
300	Every C source file of TestFloat contains a <CODE>#include</CODE> for
301	<CODE>platform.h</CODE>.
302	In many cases, the contents of <CODE>platform.h</CODE> can be as simple as one
303	or two lines of code.
304	If the target’s compiler or library has bugs or other shortcomings,
305	workarounds for these issues may be possible with target-specific declarations
306	in <CODE>platform.h</CODE>, without the need to modify the main TestFloat
307	sources.
308	</P>
309
310	<P>
311	It may not be necessary to build all of the TestFloat programs.
312	For testing a floating-point implementation, typically
313	<CODE>testfloat_gen</CODE> and <CODE>testfloat</CODE> will not both be used,
314	and <CODE>testfloat_ver</CODE> may not be needed either.
315	The Makefile (or equivalent) can be modified not to create unneeded programs.
316	This may be especially relevant for the all-in-one test program
317	<CODE>testfloat</CODE>, which might not build without special attention.
318	</P>
319
320
321	<H2>5. Dependence on Berkeley SoftFloat</H2>
322
323	<P>
324	In addition to the distributed sources, TestFloat depends on the existence of a
325	compatible Berkeley SoftFloat library and the corresponding header file
326	<CODE>softfloat.h</CODE>.
327	As mentioned earlier, SoftFloat is a separate package available at Web page
328	<A HREF="http://www.jhauser.us/arithmetic/SoftFloat.html"><NOBR><CODE>http://www.jhauser.us/arithmetic/SoftFloat.html</CODE></NOBR></A>.
329	The SoftFloat library must be compiled before the TestFloat programs can be
330	built.
331	In the example Makefiles, the locations of the SoftFloat header files and
332	pre-compiled library are specified by these macros:
333	<BLOCKQUOTE>
334	<DL>
335	<DT><CODE>SOFTFLOAT_INCLUDE_DIR</CODE>
336	<DD>
337	The path of the directory containing <CODE>softfloat.h</CODE>, as well as other
338	nonstandard header files referenced by <CODE>softfloat.h</CODE>, if any.
339	<DT><CODE>SOFTFLOAT_H</CODE>
340	<DD>
341	A list of the full paths of all SoftFloat header files needed by SoftFloat
342	clients. This list must include <CODE>softfloat.h</CODE> and may also include
343	other header files referenced by <CODE>softfloat.h</CODE>, such as
344	<CODE>softfloat_types.h</CODE>.
345	This macro is used only to establish build dependencies between the SoftFloat
346	header files and TestFloat’s source files, in case the SoftFloat header
347	files are changed.
348	<DT><CODE>SOFTFLOAT_LIB</CODE>
349	<DD>
350	The full path of the compiled SoftFloat library (usually
351	<CODE>softfloat.a</CODE> or <CODE>libsoftfloat.a</CODE>).
352	</DL>
353	</BLOCKQUOTE>
354	</P>
355
356
357	<H2>6. Issues for Porting TestFloat to a New Target</H2>
358
359	<H3>6.1. Standard Headers <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE></H3>
360
361	<P>
362	The TestFloat sources make use of standard headers
363	<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>, which have
364	been part of the ISO C Standard Library since 1999.
365	With any recent compiler, these standard headers are likely to be supported,
366	even if the compiler does not claim complete conformance to the latest ISO C
367	Standard.
368	For older or nonstandard compilers, substitutes for
369	<CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE> may need to be
370	created.
371	TestFloat depends on these names from <CODE><stdbool.h></CODE>:
372	<BLOCKQUOTE>
373	<PRE>
374	bool
375	true
376	false
377	</PRE>
378	</BLOCKQUOTE>
379	and on these names from <CODE><stdint.h></CODE>:
380	<BLOCKQUOTE>
381	<PRE>
382	uint16_t
383	uint32_t
384	uint64_t
385	int32_t
386	int64_t
387	UINT64_C
388	INT64_C
389	uint_least8_t
390	uint_fast8_t
391	uint_fast16_t
392	uint_fast32_t
393	uint_fast64_t
394	int_fast8_t
395	int_fast16_t
396	int_fast32_t
397	int_fast64_t
398	</PRE>
399	</BLOCKQUOTE>
400	</P>
401
402
403	<H3>6.2. Standard Header <CODE><fenv.h></CODE></H3>
404
405	<P>
406	Because the supplied all-in-one <CODE>testfloat</CODE> program tests the
407	floating-point operations of the C language, it uses the facilities provided by
408	standard C header <CODE><fenv.h></CODE> to access the floating-point
409	environment of C, in particular to set the rounding mode and to access the
410	floating-point exception flags.
411	Like <CODE><stdbool.h></CODE> and <CODE><stdint.h></CODE>,
412	<CODE><fenv.h></CODE> has been part of the ISO C Standard Library since
413	1999, but older or nonstandard C compilers may not support it.
414	</P>
415
416	<P>
417	Some form of standard header <CODE><fenv.h></CODE> is needed only if the
418	<CODE>testfloat</CODE> program is wanted <EM>and</EM> the program will not be
419	retargeted to invoke a floating-point implementation in a way that bypasses the
420	standard C environment.
421	Typically, if <CODE>testfloat</CODE> is wanted, it will be retargeted to invoke
422	a new floating-point implementation directly, making
423	<CODE><fenv.h></CODE> irrelevant.
424	For more about retargeting <CODE>testfloat</CODE>, see <NOBR>section 6.4</NOBR>
425	below, <I>Specializing the <CODE>testfloat</CODE> Program</I>.
426	</P>
427
428
429	<H3>6.3. Macros for Build Options</H3>
430
431	<P>
432	The TestFloat source files are affected by several C preprocessor macros:
433	<BLOCKQUOTE>
434	<DL>
435	<DT><CODE>LITTLEENDIAN</CODE>
436	<DD>
437	Must be defined for little-endian machines;
438	must not be defined for big-endian machines.
439	<DT><CODE>INLINE</CODE>
440	<DD>
441	Can be defined to a sequence of tokens used to indicate that a C function
442	should be inlined.
443	If the compiler does not support the inlining of functions, this macro must not
444	be defined.
445	For compilers that conform to the C Standard’s rules for inline
446	functions, this macro can be defined as the single keyword <CODE>inline</CODE>.
447	For other compilers that follow a convention pre-dating the standardization of
448	<CODE>inline</CODE>, this macro may need to be defined to <CODE>extern</CODE>
449	<CODE>inline</CODE>.
450	<DT><CODE>THREAD_LOCAL</CODE>
451	<DD>
452	Can be defined to a sequence of tokens that, when appearing at the start of a
453	variable declaration, indicates to the C compiler that the variable is
454	<I>per-thread</I>, meaning that each execution thread gets its own separate
455	instance of the variable.
456	This macro is used in the supplied version of Berkeley SoftFloat’s header
457	<CODE>softfloat.h</CODE>, in the declarations of variables
458	<CODE>softfloat_roundingMode</CODE>, <CODE>softfloat_detectTininess</CODE>,
459	<CODE>extF80_roundingPrecision</CODE>, and
460	<CODE>softfloat_exceptionFlags</CODE>.
461	To use the supplied, unmodified header <CODE>softfloat.h</CODE>, this macro
462	must be defined (or not defined) the same as when the SoftFloat library was
463	built.
464	</DL>
465	<DL>
466	<DT><CODE>FLOAT16</CODE>
467	<DD>
468	Must be defined if the TestFloat programs are to support the
469	<NOBR>16-bit</NOBR> half-precision floating-point format.
470	<DT><CODE>FLOAT64</CODE>
471	<DD>
472	Must be defined if the TestFloat programs are to support the
473	<NOBR>64-bit</NOBR> double-precision floating-point format.
474	<DT><CODE>EXTFLOAT80</CODE>
475	<DD>
476	Must be defined if the TestFloat programs are to support the
477	<NOBR>80-bit</NOBR> double-extended-precision floating-point format.
478	<DT><CODE>FLOAT128</CODE>
479	<DD>
480	Must be defined if the TestFloat programs are to support the
481	<NOBR>128-bit</NOBR> quadruple-precision floating-point format.
482	<DT><CODE>FLOAT_ROUND_ODD</CODE>
483	<DD>
484	Must be defined if the TestFloat programs are to support rounding to odd
485	(jamming).
486	To be useful, this option also requires that the Berkeley SoftFloat library was
487	compiled with macro <CODE>SOFTFLOAT_ROUND_ODD</CODE> defined.
488	</DL>
489	</BLOCKQUOTE>
490	Following the usual custom <NOBR>for C</NOBR>, for all the macros except
491	<CODE>INLINE</CODE> and <CODE>THREAD_LOCAL</CODE>, the content of a
492	macro’s definition is irrelevant;
493	what matters is a macro’s effect on <CODE>#ifdef</CODE> directives.
494	</P>
495
496	<P>
497	It is recommended that any definition of macros <CODE>LITTLEENDIAN</CODE>,
498	<CODE>INLINE</CODE>, and <CODE>THREAD_LOCAL</CODE> be made in a build
499	target’s <CODE>platform.h</CODE> header file, because these macros are
500	expected to be determined inflexibly by the target machine and compiler.
501	The other five macros select build options, and hence might be better located
502	in the target’s Makefile (or its equivalent).
503	</P>
504
505
506	<H3>6.4. Specializing the <CODE>testfloat</CODE> Program</H3>
507
508	<P>
509	The supplied sources for the all-in-one <CODE>testfloat</CODE> program cause
510	<CODE>testfloat</CODE> to test the C compiler’s <CODE>float</CODE> and
511	<CODE>double</CODE> types for C operations <CODE>+</CODE>, <CODE>-</CODE>,
512	<CODE>*</CODE>, <CODE>/</CODE>, etc.
513	The supplied version is also capable of testing C type <CODE>long</CODE>
514	<CODE>double</CODE> if the sources are compiled with one of these macros
515	defined:
516	<BLOCKQUOTE>
517	<DL>
518	<DT><CODE>LONG_DOUBLE_IS_EXTFLOAT80</CODE>
519	<DD>
520	Indicates that type <CODE>long</CODE> <CODE>double</CODE> is
521	<NOBR>80-bit</NOBR> double-extended-precision floating-point.
522	<DT><CODE>LONG_DOUBLE_IS_FLOAT128</CODE>
523	<DD>
524	Indicates that type <CODE>long</CODE> <CODE>double</CODE> is
525	<NOBR>128-bit</NOBR> quadruple-precision floating-point.
526	</DL>
527	</BLOCKQUOTE>
528	By default, <CODE>testfloat</CODE> assumes that only the IEEE Standard’s
529	original four rounding modes (<CODE>near_even</CODE>, <CODE>minMag</CODE>,
530	<CODE>min</CODE>, and <CODE>max</CODE>) are supported by the floating-point
531	being tested.
532	For other rounding modes, additional macro can be defined:
533	<BLOCKQUOTE>
534	<DL>
535	<DT><CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE>
536	<DD>
537	Indicates that the subject floating-point supports rounding mode
538	<CODE>near_maxMag</CODE> (nearest/away).
539	<DT><CODE>SUBJFLOAT_ROUND_ODD</CODE>
540	<DD>
541	Indicates that the subject floating-point supports rounding mode
542	<CODE>odd</CODE> (jamming).
543	</DL>
544	</BLOCKQUOTE>
545	</P>
546
547	<P>
548	To test a new and/or different implementation of floating-point,
549	<CODE>testfloat</CODE> must normally be retargeted to invoke this other
550	floating-point instead of C’s floating-point.
551	Two source files define the functions that <CODE>testfloat</CODE> uses to
552	invoke floating-point operations for testing:
553	<BLOCKQUOTE>
554	<PRE>
555	subjfloat_config.h
556	subjfloat.c
557	</PRE>
558	</BLOCKQUOTE>
559	For the default target of testing C’s floating-point, these files are
560	contained in directory <NOBR><CODE>source/subj-C</CODE></NOBR> as discussed
561	earlier.
562	For a different subject floating-point, it is recommended that appropriate
563	versions of <CODE>subjfloat_config.h</CODE> and <CODE>subjfloat.c</CODE> be
564	stored in a sibling <NOBR><CODE>subj-<<I>target</I>></CODE></NOBR>
565	directory, where <CODE><<I>target</I>></CODE> names the particular
566	target.
567	</P>
568
569	<P>
570	Header file <CODE>subjfloat_config.h</CODE> defines a macro of the form
571	<CODE>SUBJ_*</CODE> for each subject function supported.
572	For example, if function <CODE>subj_f32_add</CODE> exists to perform
573	<NOBR>32-bit</NOBR> floating-point addition, then
574	<CODE>subjfloat_config.h</CODE> should have a definition for macro
575	<CODE>SUBJ_F32_ADD</CODE>.
576	The actual function <CODE>subj_f32_add</CODE> is expected to be defined in
577	<CODE>subjfloat.c</CODE>, along with all other subject functions.
578	A common header file, <CODE>subjfloat.h</CODE>, (not target-specific) provides
579	prototype declarations for all possible subject functions that
580	<CODE>testfloat</CODE> may be compiled to test, whether actually existing or
581	not.
582	(There is no penalty for the header to declare prototypes of nonexistent
583	functions that are never called.)
584	For a specific build of <CODE>testfloat</CODE>, the <CODE>-list</CODE> option
585	will list all subject functions that the <CODE>testfloat</CODE> program is able
586	to invoke and thus test.
587	</P>
588
589	<P>
590	In the source code as supplied, macros <CODE>LONG_DOUBLE_IS_EXTFLOAT80</CODE>
591	and <CODE>LONG_DOUBLE_IS_FLOAT128</CODE> affect only the target-specific source
592	files in <NOBR><CODE>source/subj-C</CODE></NOBR>, so these macros can be
593	ignored for any other subject floating-point that does not depend on them.
594	On the other hand, macros <CODE>SUBJFLOAT_ROUND_NEAR_MAXMAG</CODE> and
595	<CODE>SUBJFLOAT_ROUND_ODD</CODE> always determine whether the
596	<CODE>testfloat</CODE> program attempts to test rounding modes
597	<CODE>near_maxMag</CODE> and <CODE>odd</CODE>, regardless of the subject
598	floating-point.
599	</P>
600
601
602	<H3>6.5. Improving the Random Number Functions</H3>
603
604	<P>
605	If you are serious about using TestFloat for testing floating-point, you should
606	consider replacing the random number functions in <CODE>random.c</CODE>.
607	The supplied random number functions are built on top of the standard C
608	<CODE>rand</CODE> function.
609	Because function <CODE>rand</CODE> is rather poor on some systems, the
610	functions in <CODE>random.c</CODE> assume very little about the quality of
611	<CODE>rand</CODE>.
612	As a result, <CODE>rand</CODE> is called more frequently than it might need to
613	be, shortening the time before random number sequences repeat, and possibly
614	wasting time as well.
615	If <CODE>rand</CODE> is better on a given target platform, or if another,
616	better random number generator is available (such as <CODE>rand48</CODE> on
617	UNIX-derived systems), TestFloat can be improved by overriding the given
618	<CODE>random.c</CODE> with a target-specific one.
619	</P>
620
621	<P>
622	Rather than modifying the supplied file <CODE>random.c</CODE>, it is
623	recommended instead that a new, alternate file be created and the
624	target’s Makefile be modified to refer to that alternate file in place of
625	<CODE>random.c</CODE>.
626	</P>
627
628
629	<H2>7. Contact Information</H2>
630
631	<P>
632	At the time of this writing, the most up-to-date information about TestFloat
633	and the latest release can be found at the Web page
634	<A HREF="http://www.jhauser.us/arithmetic/TestFloat.html"><NOBR><CODE>http://www.jhauser.us/arithmetic/TestFloat.html</CODE></NOBR></A>.
635	</P>
636
637
638	</BODY>
639

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

source: vbox/trunk/src/libs/softfloat-3e/testfloat/doc/TestFloat-source.html

Download in other formats: