1$NetBSD: timesoftfloat.txt,v 1.1 2000/06/06 08:15:11 bjh21 Exp $
2
3Documentation for the `timesoftfloat' Program of SoftFloat Release 2a
4
5John R. Hauser
61998 December 14
7
8
9-------------------------------------------------------------------------------
10Introduction
11
12The `timesoftfloat' program evaluates the speed of SoftFloat's floating-
13point routines.  Each routine can be evaluated for every relevant rounding
14mode, tininess mode, and/or rounding precision.
15
16
17-------------------------------------------------------------------------------
18Contents
19
20    Introduction
21    Contents
22    Legal Notice
23    Executing `timesoftfloat'
24    Options
25        -help
26        -precision32, -precision64, -precision80
27        -nearesteven, -tozero, -down, -up
28        -tininessbefore, -tininessafter
29    Function Sets
30
31
32
33-------------------------------------------------------------------------------
34Legal Notice
35
36The `timesoftfloat' program was written by John R. Hauser.
37
38THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE.  Although reasonable effort
39has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT
40TIMES RESULT IN INCORRECT BEHAVIOR.  USE OF THIS SOFTWARE IS RESTRICTED TO
41PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY
42AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE.
43
44
45-------------------------------------------------------------------------------
46Executing `timesoftfloat'
47
48The `timesoftfloat' program is intended to be invoked from a command line
49interpreter as follows:
50
51    timesoftfloat [<option>...] <function>
52
53Here square brackets ([]) indicate optional items, while angled brackets
54(<>) denote parameters to be filled in.  The `<function>' argument is
55the name of the SoftFloat routine to evaluate, such as `float32_add' or
56`float64_to_int32'.  The allowed options are detailed in the next section,
57_Options_.  If `timesoftfloat' is executed without any arguments, a summary
58of usage is written.  It is also possible to evaluate all machine functions
59in a single invocation as explained in the section _Function_Sets_ later in
60this document.
61
62Ordinarily, a function's speed will be evaluated separately for each of
63the four rounding modes, one after the other.  If the rounding mode is not
64supposed to have any affect on the results of a function--for instance,
65some operations do not require rounding--only the nearest/even rounding mode
66is timed.  In the same way, if a function is affected by the way in which
67underflow tininess is detected, `timesoftfloat' times the function both with
68tininess detected before rounding and after rounding.  For extended double-
69precision operations affected by rounding precision control, `timesoftfloat'
70also times the function for all three rounding precision modes, one after
71the other.  Evaluation of a function can be limited to a single rounding
72mode, a single tininess mode, and/or a single rounding precision with
73appropriate options (see _Options_).
74
75For each function and mode evaluated, `timesoftfloat' reports the speed of
76the function in kops/s, or ``thousands of operations per second''.  This
77unit of measure differs from the traditional MFLOPS (``millions of floating-
78point operations per second'') only in being a factor of 1000 smaller.
79(1000 kops/s is exactly 1 MFLOPS.)  Speeds are reported in thousands instead
80of millions because software floating-point often executes at less than
811 MFLOPS.
82
83The speeds reported by `timesoftfloat' may be affected somewhat by other
84programs executing at the same time as `timesoftfloat'.
85
86Note that the remainder operations (`float32_rem', `float64_rem',
87`floatx80_rem' and `float128_rem') will be markedly slower than other
88operations, particularly for extended double precision (`floatx80') and
89quadruple precision (`float128').  This is inherent to the remainder
90function itself and is not a failing of the SoftFloat implementation.
91
92
93-------------------------------------------------------------------------------
94Options
95
96The `timesoftfloat' program accepts several command options.  If mutually
97contradictory options are given, the last one has priority.
98
99- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
100-help
101
102The `-help' option causes a summary of program usage to be written, after
103which the program exits.
104
105- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
106-precision32, -precision64, -precision80
107
108For extended double-precision functions affected by rounding precision
109control, the `-precision32' option restricts evaluation to only the cases
110in which rounding precision is equivalent to single precision.  The other
111rounding precision options are not timed.  Likewise, the `-precision64'
112and `-precision80' options fix the rounding precision equivalent to double
113precision or extended double precision, respectively.  These options are
114ignored for functions not affected by rounding precision control.
115
116- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
117-nearesteven, -tozero, -down, -up
118
119The `-nearesteven' option restricts evaluation to only the cases in which
120the rounding mode is nearest/even.  The other rounding mode options are not
121timed.  Likewise, `-tozero' forces rounding to zero; `-down' forces rounding
122down; and `-up' forces rounding up.  These options are ignored for functions
123that are exact and thus do not round.
124
125- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
126-tininessbefore, -tininessafter
127
128The `-tininessbefore' option restricts evaluation to only the cases
129detecting underflow tininess before rounding.  Tininess after rounding
130is not timed.  Likewise, `-tininessafter' forces underflow tininess to be
131detected after rounding only.  These options are ignored for functions not
132affected by the way in which underflow tininess is detected.
133
134- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
135
136
137-------------------------------------------------------------------------------
138Function Sets
139
140Just as `timesoftfloat' can test an operation for all four rounding modes in
141sequence, multiple operations can also be tested with a single invocation.
142Three sets are recognized:  `-all1', `-all2', and `-all'.  The set `-all1'
143comprises all one-operand functions; `-all2' is all two-operand functions;
144and `-all' is all functions.  A function set can be used in place of a
145function name in the command line, as in
146
147    timesoftfloat [<option>...] -all
148
149
150