1129203Scognet$NetBSD: timesoftfloat.txt,v 1.1 2000/06/06 08:15:11 bjh21 Exp $ 2129203Scognet$FreeBSD: releng/11.0/lib/libc/softfloat/timesoftfloat.txt 129203 2004-05-14 12:13:06Z cognet $ 3129203Scognet 4129203ScognetDocumentation for the `timesoftfloat' Program of SoftFloat Release 2a 5129203Scognet 6129203ScognetJohn R. Hauser 7129203Scognet1998 December 14 8129203Scognet 9129203Scognet 10129203Scognet------------------------------------------------------------------------------- 11129203ScognetIntroduction 12129203Scognet 13129203ScognetThe `timesoftfloat' program evaluates the speed of SoftFloat's floating- 14129203Scognetpoint routines. Each routine can be evaluated for every relevant rounding 15129203Scognetmode, tininess mode, and/or rounding precision. 16129203Scognet 17129203Scognet 18129203Scognet------------------------------------------------------------------------------- 19129203ScognetContents 20129203Scognet 21129203Scognet Introduction 22129203Scognet Contents 23129203Scognet Legal Notice 24129203Scognet Executing `timesoftfloat' 25129203Scognet Options 26129203Scognet -help 27129203Scognet -precision32, -precision64, -precision80 28129203Scognet -nearesteven, -tozero, -down, -up 29129203Scognet -tininessbefore, -tininessafter 30129203Scognet Function Sets 31129203Scognet 32129203Scognet 33129203Scognet 34129203Scognet------------------------------------------------------------------------------- 35129203ScognetLegal Notice 36129203Scognet 37129203ScognetThe `timesoftfloat' program was written by John R. Hauser. 38129203Scognet 39129203ScognetTHIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 40129203Scognethas been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 41129203ScognetTIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 42129203ScognetPERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 43129203ScognetAND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 44129203Scognet 45129203Scognet 46129203Scognet------------------------------------------------------------------------------- 47129203ScognetExecuting `timesoftfloat' 48129203Scognet 49129203ScognetThe `timesoftfloat' program is intended to be invoked from a command line 50129203Scognetinterpreter as follows: 51129203Scognet 52129203Scognet timesoftfloat [<option>...] <function> 53129203Scognet 54129203ScognetHere square brackets ([]) indicate optional items, while angled brackets 55129203Scognet(<>) denote parameters to be filled in. The `<function>' argument is 56129203Scognetthe name of the SoftFloat routine to evaluate, such as `float32_add' or 57129203Scognet`float64_to_int32'. The allowed options are detailed in the next section, 58129203Scognet_Options_. If `timesoftfloat' is executed without any arguments, a summary 59129203Scognetof usage is written. It is also possible to evaluate all machine functions 60129203Scognetin a single invocation as explained in the section _Function_Sets_ later in 61129203Scognetthis document. 62129203Scognet 63129203ScognetOrdinarily, a function's speed will be evaulated separately for each of 64129203Scognetthe four rounding modes, one after the other. If the rounding mode is not 65129203Scognetsupposed to have any affect on the results of a function--for instance, 66129203Scognetsome operations do not require rounding--only the nearest/even rounding mode 67129203Scognetis timed. In the same way, if a function is affected by the way in which 68129203Scognetunderflow tininess is detected, `timesoftfloat' times the function both with 69129203Scognettininess detected before rounding and after rounding. For extended double- 70129203Scognetprecision operations affected by rounding precision control, `timesoftfloat' 71129203Scognetalso times the function for all three rounding precision modes, one after 72129203Scognetthe other. Evaluation of a function can be limited to a single rounding 73129203Scognetmode, a single tininess mode, and/or a single rounding precision with 74129203Scognetappropriate options (see _Options_). 75129203Scognet 76129203ScognetFor each function and mode evaluated, `timesoftfloat' reports the speed of 77129203Scognetthe function in kops/s, or ``thousands of operations per second''. This 78129203Scognetunit of measure differs from the traditional MFLOPS (``millions of floating- 79129203Scognetpoint operations per second'') only in being a factor of 1000 smaller. 80129203Scognet(1000 kops/s is exactly 1 MFLOPS.) Speeds are reported in thousands instead 81129203Scognetof millions because software floating-point often executes at less than 82129203Scognet1 MFLOPS. 83129203Scognet 84129203ScognetThe speeds reported by `timesoftfloat' may be affected somewhat by other 85129203Scognetprograms executing at the same time as `timesoftfloat'. 86129203Scognet 87129203ScognetNote that the remainder operations (`float32_rem', `float64_rem', 88129203Scognet`floatx80_rem' and `float128_rem') will be markedly slower than other 89129203Scognetoperations, particularly for extended double precision (`floatx80') and 90129203Scognetquadruple precision (`float128'). This is inherent to the remainder 91129203Scognetfunction itself and is not a failing of the SoftFloat implementation. 92129203Scognet 93129203Scognet 94129203Scognet------------------------------------------------------------------------------- 95129203ScognetOptions 96129203Scognet 97129203ScognetThe `timesoftfloat' program accepts several command options. If mutually 98129203Scognetcontradictory options are given, the last one has priority. 99129203Scognet 100129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 101129203Scognet-help 102129203Scognet 103129203ScognetThe `-help' option causes a summary of program usage to be written, after 104129203Scognetwhich the program exits. 105129203Scognet 106129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 107129203Scognet-precision32, -precision64, -precision80 108129203Scognet 109129203ScognetFor extended double-precision functions affected by rounding precision 110129203Scognetcontrol, the `-precision32' option restricts evaluation to only the cases 111129203Scognetin which rounding precision is equivalent to single precision. The other 112129203Scognetrounding precision options are not timed. Likewise, the `-precision64' 113129203Scognetand `-precision80' options fix the rounding precision equivalent to double 114129203Scognetprecision or extended double precision, respectively. These options are 115129203Scognetignored for functions not affected by rounding precision control. 116129203Scognet 117129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 118129203Scognet-nearesteven, -tozero, -down, -up 119129203Scognet 120129203ScognetThe `-nearesteven' option restricts evaluation to only the cases in which 121129203Scognetthe rounding mode is nearest/even. The other rounding mode options are not 122129203Scognettimed. Likewise, `-tozero' forces rounding to zero; `-down' forces rounding 123129203Scognetdown; and `-up' forces rounding up. These options are ignored for functions 124129203Scognetthat are exact and thus do not round. 125129203Scognet 126129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 127129203Scognet-tininessbefore, -tininessafter 128129203Scognet 129129203ScognetThe `-tininessbefore' option restricts evaluation to only the cases 130129203Scognetdetecting underflow tininess before rounding. Tininess after rounding 131129203Scognetis not timed. Likewise, `-tininessafter' forces underflow tininess to be 132129203Scognetdetected after rounding only. These options are ignored for functions not 133129203Scognetaffected by the way in which underflow tininess is detected. 134129203Scognet 135129203Scognet- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 136129203Scognet 137129203Scognet 138129203Scognet------------------------------------------------------------------------------- 139129203ScognetFunction Sets 140129203Scognet 141129203ScognetJust as `timesoftfloat' can test an operation for all four rounding modes in 142129203Scognetsequence, multiple operations can also be tested with a single invocation. 143129203ScognetThree sets are recognized: `-all1', `-all2', and `-all'. The set `-all1' 144129203Scognetcomprises all one-operand functions; `-all2' is all two-operand functions; 145129203Scognetand `-all' is all functions. A function set can be used in place of a 146129203Scognetfunction name in the command line, as in 147129203Scognet 148129203Scognet timesoftfloat [<option>...] -all 149129203Scognet 150129203Scognet 151