lib/libc/softfloat/timesoftfloat.txt

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