]>
Commit | Line | Data |
---|---|---|
3352b62b N |
1 | $NetBSD: softfloat-source.txt,v 1.2 2006/11/24 19:46:58 christos Exp $\r |
2 | \r | |
3 | SoftFloat Release 2a Source Documentation\r | |
4 | \r | |
5 | John R. Hauser\r | |
6 | 1998 December 14\r | |
7 | \r | |
8 | \r | |
9 | -------------------------------------------------------------------------------\r | |
10 | Introduction\r | |
11 | \r | |
12 | SoftFloat is a software implementation of floating-point that conforms to\r | |
13 | the IEC/IEEE Standard for Binary Floating-Point Arithmetic. SoftFloat can\r | |
14 | support four floating-point formats: single precision, double precision,\r | |
15 | extended double precision, and quadruple precision. All operations required\r | |
16 | by the IEEE Standard are implemented, except for conversions to and from\r | |
17 | decimal. SoftFloat is distributed in the form of C source code, so a\r | |
18 | C compiler is needed to compile the code. Support for the extended double-\r | |
19 | precision and quadruple-precision formats is dependent on the C compiler\r | |
20 | implementing a 64-bit integer type.\r | |
21 | \r | |
22 | This document gives information needed for compiling and/or porting\r | |
23 | SoftFloat.\r | |
24 | \r | |
25 | The source code for SoftFloat is intended to be relatively machine-\r | |
26 | independent and should be compilable using any ISO/ANSI C compiler. At the\r | |
27 | time of this writing, SoftFloat has been successfully compiled with the GNU\r | |
28 | C Compiler (`gcc') for several platforms.\r | |
29 | \r | |
30 | \r | |
31 | -------------------------------------------------------------------------------\r | |
32 | Limitations\r | |
33 | \r | |
34 | SoftFloat as written requires an ISO/ANSI-style C compiler. No attempt has\r | |
35 | been made to accommodate compilers that are not ISO-conformant. Older ``K&R-\r | |
36 | style'' compilers are not adequate for compiling SoftFloat. All testing I\r | |
37 | have done so far has been with the GNU C Compiler. Compilation with other\r | |
38 | compilers should be possible but has not been tested.\r | |
39 | \r | |
40 | The SoftFloat sources assume that source code file names can be longer than\r | |
41 | 8 characters. In order to compile under an MS-DOS-type system, many of the\r | |
42 | source files will need to be renamed, and the source and makefiles edited\r | |
43 | appropriately. Once compiled, the SoftFloat binary does not depend on the\r | |
44 | existence of long file names.\r | |
45 | \r | |
46 | The underlying machine is assumed to be binary with a word size that is a\r | |
47 | power of 2. Bytes are 8 bits. Support for the extended double-precision\r | |
48 | and quadruple-precision formats depends on the C compiler implementing\r | |
49 | a 64-bit integer type. If the largest integer type supported by the\r | |
50 | C compiler is 32 bits, SoftFloat is limited to the single- and double-\r | |
51 | precision formats.\r | |
52 | \r | |
53 | \r | |
54 | -------------------------------------------------------------------------------\r | |
55 | Contents\r | |
56 | \r | |
57 | Introduction\r | |
58 | Limitations\r | |
59 | Contents\r | |
60 | Legal Notice\r | |
61 | SoftFloat Source Directory Structure\r | |
62 | SoftFloat Source Files\r | |
63 | processors/*.h\r | |
64 | softfloat/bits*/*/softfloat.h\r | |
65 | softfloat/bits*/*/milieu.h\r | |
66 | softfloat/bits*/*/softfloat-specialize\r | |
67 | softfloat/bits*/softfloat-macros\r | |
68 | softfloat/bits*/softfloat.c\r | |
69 | Steps to Creating a `softfloat.o'\r | |
70 | Making `softfloat.o' a Library\r | |
71 | Testing SoftFloat\r | |
72 | Timing SoftFloat\r | |
73 | Compiler Options and Efficiency\r | |
74 | Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'\r | |
75 | Contact Information\r | |
76 | \r | |
77 | \r | |
78 | \r | |
79 | -------------------------------------------------------------------------------\r | |
80 | Legal Notice\r | |
81 | \r | |
82 | SoftFloat was written by John R. Hauser. This work was made possible in\r | |
83 | part by the International Computer Science Institute, located at Suite 600,\r | |
84 | 1947 Center Street, Berkeley, California 94704. Funding was partially\r | |
85 | provided by the National Science Foundation under grant MIP-9311980. The\r | |
86 | original version of this code was written as part of a project to build\r | |
87 | a fixed-point vector processor in collaboration with the University of\r | |
88 | California at Berkeley, overseen by Profs. Nelson Morgan and John Wawrzynek.\r | |
89 | \r | |
90 | THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort\r | |
91 | has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT\r | |
92 | TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO\r | |
93 | PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY\r | |
94 | AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE.\r | |
95 | \r | |
96 | \r | |
97 | -------------------------------------------------------------------------------\r | |
98 | SoftFloat Source Directory Structure\r | |
99 | \r | |
100 | Because SoftFloat is targeted to multiple platforms, its source code\r | |
101 | is slightly scattered between target-specific and target-independent\r | |
102 | directories and files. The directory structure is as follows:\r | |
103 | \r | |
104 | processors\r | |
105 | softfloat\r | |
106 | bits64\r | |
107 | templates\r | |
108 | 386-Win32-gcc\r | |
109 | SPARC-Solaris-gcc\r | |
110 | bits32\r | |
111 | templates\r | |
112 | 386-Win32-gcc\r | |
113 | SPARC-Solaris-gcc\r | |
114 | \r | |
115 | The two topmost directories and their contents are:\r | |
116 | \r | |
117 | softfloat - Most of the source code needed for SoftFloat.\r | |
118 | processors - Target-specific header files that are not specific to\r | |
119 | SoftFloat.\r | |
120 | \r | |
121 | The `softfloat' directory is further split into two parts:\r | |
122 | \r | |
123 | bits64 - SoftFloat implementation using 64-bit integers.\r | |
124 | bits32 - SoftFloat implementation using only 32-bit integers.\r | |
125 | \r | |
126 | Within these directories are subdirectories for each of the targeted\r | |
127 | platforms. The SoftFloat source code is distributed with targets\r | |
128 | `386-Win32-gcc' and `SPARC-Solaris-gcc' (and perhaps others) already\r | |
129 | prepared for both the 32-bit and 64-bit implementations. Source files that\r | |
130 | are not within these target-specific subdirectories are intended to be\r | |
131 | target-independent.\r | |
132 | \r | |
133 | The naming convention used for the target-specific directories is\r | |
134 | `<processor>-<executable-type>-<compiler>'. The names of the supplied\r | |
135 | target directories should be interpreted as follows:\r | |
136 | \r | |
137 | <processor>:\r | |
138 | 386 - Intel 386-compatible processor.\r | |
139 | SPARC - SPARC processor (as used by Sun machines).\r | |
140 | <executable-type>:\r | |
141 | Win32 - Microsoft Win32 executable.\r | |
142 | Solaris - Sun Solaris executable.\r | |
143 | <compiler>:\r | |
144 | gcc - GNU C Compiler.\r | |
145 | \r | |
146 | You do not need to maintain this convention if you do not want to.\r | |
147 | \r | |
148 | Alongside the supplied target-specific directories is a `templates'\r | |
149 | directory containing a set of ``generic'' target-specific source files. A\r | |
150 | new target directory can be created by copying the `templates' directory and\r | |
151 | editing the files inside. (Complete instructions for porting SoftFloat to a\r | |
152 | new target are in the section _Steps_to_Creating_a_`softfloat.o'_.) Note\r | |
153 | that the `templates' directory will not work as a target directory without\r | |
154 | some editing. To avoid confusion, it would be wise to refrain from editing\r | |
155 | the files inside `templates' directly.\r | |
156 | \r | |
157 | \r | |
158 | -------------------------------------------------------------------------------\r | |
159 | SoftFloat Source Files\r | |
160 | \r | |
161 | The purpose of each source file is described below. In the following,\r | |
162 | the `*' symbol is used in place of the name of a specific target, such as\r | |
163 | `386-Win32-gcc' or `SPARC-Solaris-gcc', or in place of some other text, as\r | |
164 | in `bits*' for either `bits32' or `bits64'.\r | |
165 | \r | |
166 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
167 | processors/*.h\r | |
168 | \r | |
169 | The target-specific `processors' header file defines integer types\r | |
170 | of various sizes, and also defines certain C preprocessor macros that\r | |
171 | characterize the target. The two examples supplied are `386-gcc.h' and\r | |
172 | `SPARC-gcc.h'. The naming convention used for processor header files is\r | |
173 | `<processor>-<compiler>.h'.\r | |
174 | \r | |
175 | If 64-bit integers are supported by the compiler, the macro name `BITS64'\r | |
176 | should be defined here along with the corresponding 64-bit integer\r | |
177 | types. In addition, the function-like macro `LIT64' must be defined for\r | |
178 | constructing 64-bit integer literals (constants). The `LIT64' macro is used\r | |
179 | consistently in the SoftFloat code to annotate 64-bit literals.\r | |
180 | \r | |
181 | If `BITS64' is not defined, only the 32-bit version of SoftFloat can be\r | |
182 | compiled. If `BITS64' _is_ defined, either can be compiled.\r | |
183 | \r | |
184 | If an inlining attribute (such as an `inline' keyword) is provided by the\r | |
185 | compiler, the macro `INLINE' should be defined to the appropriate keyword.\r | |
186 | If not, `INLINE' can be set to the keyword `static'. The `INLINE' macro\r | |
187 | appears in the SoftFloat source code before every function that should\r | |
188 | be inlined by the compiler. SoftFloat depends on inlining to obtain\r | |
189 | good speed. Even if inlining cannot be forced with a language keyword,\r | |
190 | the compiler may still be able to perform inlining on its own as an\r | |
191 | optimization. If a command-line option is needed to convince the compiler\r | |
192 | to perform this optimization, this should be assured in the makefile. (See\r | |
193 | the section _Compiler_Options_and_Efficiency_ below.)\r | |
194 | \r | |
195 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
196 | softfloat/bits*/*/softfloat.h\r | |
197 | \r | |
198 | The target-specific `softfloat.h' header file defines the SoftFloat\r | |
199 | interface as seen by clients.\r | |
200 | \r | |
201 | Unlike the actual function definitions in `softfloat.c', the declarations\r | |
202 | in `softfloat.h' do not use any of the types defined by the `processors'\r | |
203 | header file. This is done so that clients will not have to include the\r | |
204 | `processors' header file in order to use SoftFloat. Nevertheless, the\r | |
205 | target-specific declarations in `softfloat.h' must match what `softfloat.c'\r | |
206 | expects. For example, if `int32' is defined as `int' in the `processors'\r | |
207 | header file, then in `softfloat.h' the output of `float32_to_int32' should\r | |
208 | be stated as `int', although in `softfloat.c' it is given in target-\r | |
209 | independent form as `int32'.\r | |
210 | \r | |
211 | For the `bits64' implementation of SoftFloat, the macro names `FLOATX80' and\r | |
212 | `FLOAT128' must be defined in order for the extended double-precision and\r | |
213 | quadruple-precision formats to be enabled in the code. Conversely, either\r | |
214 | or both of the extended formats can be disabled by simply removing the\r | |
215 | `#define' of the respective macro. When an extended format is not enabled,\r | |
216 | none of the functions that either input or output the format are defined,\r | |
217 | and no space is taken up in `softfloat.o' by such functions. There is no\r | |
218 | provision for disabling the usual single- and double-precision formats.\r | |
219 | \r | |
220 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
221 | softfloat/bits*/*/milieu.h\r | |
222 | \r | |
223 | The target-specific `milieu.h' header file provides declarations that are\r | |
224 | needed to compile SoftFloat. In addition, deviations from ISO/ANSI C by\r | |
225 | the compiler (such as names not properly declared in system header files)\r | |
226 | are corrected in this header if possible.\r | |
227 | \r | |
228 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
229 | softfloat/bits*/*/softfloat-specialize\r | |
230 | \r | |
231 | This target-specific C source fragment defines:\r | |
232 | \r | |
233 | -- whether tininess for underflow is detected before or after rounding by\r | |
234 | default;\r | |
235 | -- what (if anything) special happens when exceptions are raised;\r | |
236 | -- how signaling NaNs are distinguished from quiet NaNs;\r | |
237 | -- the default generated quiet NaNs; and\r | |
238 | -- how NaNs are propagated from function inputs to output.\r | |
239 | \r | |
240 | These details are not decided by the IEC/IEEE Standard. This fragment is\r | |
241 | included verbatim within `softfloat.c' when SoftFloat is compiled.\r | |
242 | \r | |
243 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
244 | softfloat/bits*/softfloat-macros\r | |
245 | \r | |
246 | This target-independent C source fragment defines a number of arithmetic\r | |
247 | functions used as primitives within the `softfloat.c' source. Most of the\r | |
248 | functions defined here are intended to be inlined for efficiency. This\r | |
249 | fragment is included verbatim within `softfloat.c' when SoftFloat is\r | |
250 | compiled.\r | |
251 | \r | |
252 | Target-specific variations on this file are possible. See the section\r | |
253 | _Processor-Specific_Optimization_of_`softfloat.c'_Using_`softfloat-macros'_\r | |
254 | below.\r | |
255 | \r | |
256 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
257 | softfloat/bits*/softfloat.c\r | |
258 | \r | |
259 | The target-independent `softfloat.c' source file contains the body of the\r | |
260 | SoftFloat implementation.\r | |
261 | \r | |
262 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\r | |
263 | \r | |
264 | The inclusion of the files above within each other (using `#include') can be\r | |
265 | shown graphically as follows:\r | |
266 | \r | |
267 | softfloat/bits*/softfloat.c\r | |
268 | softfloat/bits*/*/milieu.h\r | |
269 | processors/*.h\r | |
270 | softfloat/bits*/*/softfloat.h\r | |
271 | softfloat/bits*/*/softfloat-specialize\r | |
272 | softfloat/bits*/softfloat-macros\r | |
273 | \r | |
274 | Note in particular that `softfloat.c' does not include the `processors'\r | |
275 | header file directly. Rather, `softfloat.c' includes the target-specific\r | |
276 | `milieu.h' header file, which in turn includes the processor header file.\r | |
277 | \r | |
278 | \r | |
279 | -------------------------------------------------------------------------------\r | |
280 | Steps to Creating a `softfloat.o'\r | |
281 | \r | |
282 | Porting and/or compiling SoftFloat involves the following steps:\r | |
283 | \r | |
284 | 1. If one does not already exist, create an appropriate `.h' file in the\r | |
285 | `processors' directory.\r | |
286 | \r | |
287 | 2. If `BITS64' is defined in the `processors' header file, choose whether\r | |
288 | to compile the 32-bit or 64-bit implementation of SoftFloat. If\r | |
289 | `BITS64' is not defined, your only choice is the 32-bit implementation.\r | |
290 | The remaining steps occur within either the `bits32' or `bits64'\r | |
291 | subdirectories.\r | |
292 | \r | |
293 | 3. If one does not already exist, create an appropriate target-specific\r | |
294 | subdirectory by copying the given `templates' directory.\r | |
295 | \r | |
296 | 4. In the target-specific subdirectory, edit the files `softfloat-specialize'\r | |
297 | and `softfloat.h' to define the desired exception handling functions\r | |
298 | and mode control values. In the `softfloat.h' header file, ensure also\r | |
299 | that all declarations give the proper target-specific type (such as\r | |
300 | `int' or `long') corresponding to the target-independent type used in\r | |
301 | `softfloat.c' (such as `int32'). None of the type names declared in the\r | |
302 | `processors' header file should appear in `softfloat.h'.\r | |
303 | \r | |
304 | 5. In the target-specific subdirectory, edit the files `milieu.h' and\r | |
305 | `Makefile' to reflect the current environment.\r | |
306 | \r | |
307 | 6. In the target-specific subdirectory, execute `make'.\r | |
308 | \r | |
309 | For the targets that are supplied, if the expected compiler is available\r | |
310 | (usually `gcc'), it should only be necessary to execute `make' in the\r | |
311 | target-specific subdirectory.\r | |
312 | \r | |
313 | \r | |
314 | -------------------------------------------------------------------------------\r | |
315 | Making `softfloat.o' a Library\r | |
316 | \r | |
317 | SoftFloat is not made into a software library by the supplied makefile.\r | |
318 | If desired, `softfloat.o' can easily be put into its own library (in Unix,\r | |
319 | `softfloat.a') using the usual system tool (in Unix, `ar').\r | |
320 | \r | |
321 | \r | |
322 | -------------------------------------------------------------------------------\r | |
323 | Testing SoftFloat\r | |
324 | \r | |
325 | SoftFloat can be tested using the `testsoftfloat' program by the same\r | |
326 | author. The `testsoftfloat' program is part of the TestFloat package\r | |
327 | available at the Web page `http://HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/\r | |
328 | TestFloat.html'.\r | |
329 | \r | |
330 | \r | |
331 | -------------------------------------------------------------------------------\r | |
332 | Timing SoftFloat\r | |
333 | \r | |
334 | A program called `timesoftfloat' for timing the SoftFloat functions is\r | |
335 | included with the SoftFloat source code. Compiling `timesoftfloat' should\r | |
336 | pose no difficulties once `softfloat.o' exists. The supplied makefile\r | |
337 | will create a `timesoftfloat' executable by default after generating\r | |
338 | `softfloat.o'. See `timesoftfloat.txt' for documentation about using\r | |
339 | `timesoftfloat'.\r | |
340 | \r | |
341 | \r | |
342 | -------------------------------------------------------------------------------\r | |
343 | Compiler Options and Efficiency\r | |
344 | \r | |
345 | In order to get good speed with SoftFloat, it is important that the compiler\r | |
346 | inline the routines that have been marked `INLINE' in the code. Even if\r | |
347 | inlining cannot be forced by an appropriate definition of the `INLINE'\r | |
348 | macro, the compiler may still be able to perform inlining on its own as\r | |
349 | an optimization. In that case, the makefile should be edited to give the\r | |
350 | compiler whatever option is required to cause it to inline small functions.\r | |
351 | \r | |
352 | The ability of the processor to do fast shifts has been assumed. Efficiency\r | |
353 | will not be as good on processors for which this is not the case (such as\r | |
354 | the original Motorola 68000 or Intel 8086 processors).\r | |
355 | \r | |
356 | \r | |
357 | -------------------------------------------------------------------------------\r | |
358 | Processor-Specific Optimization of `softfloat.c' Using `softfloat-macros'\r | |
359 | \r | |
360 | The `softfloat-macros' source fragment defines arithmetic functions used\r | |
361 | as primitives by `softfloat.c'. This file has been written in a target-\r | |
362 | independent form. For a given target, it may be possible to improve on\r | |
363 | these functions using target-specific and/or non-ISO-C features (such\r | |
364 | as `asm' statements). For example, one of the ``macro'' functions takes\r | |
365 | two word-size integers and returns their full product in two words.\r | |
366 | This operation can be done directly in hardware on many processors; but\r | |
367 | because it is not available through standard C, the function defined in\r | |
368 | `softfloat-macros' uses four multiplies to achieve the same result.\r | |
369 | \r | |
370 | To address these shortcomings, a customized version of `softfloat-macros'\r | |
371 | can be created in any of the target-specific subdirectories. A simple\r | |
372 | modification to the target's makefile should be sufficient to ensure that\r | |
373 | the custom version is used instead of the generic one.\r | |
374 | \r | |
375 | \r | |
376 | -------------------------------------------------------------------------------\r | |
377 | Contact Information\r | |
378 | \r | |
379 | At the time of this writing, the most up-to-date information about\r | |
380 | SoftFloat and the latest release can be found at the Web page `http://\r | |
381 | HTTP.CS.Berkeley.EDU/~jhauser/arithmetic/SoftFloat.html'.\r | |
382 | \r | |
383 | \r |