lib/libc/softfloat/timesoftfloat.txt

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