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