115144b0fSOlivier Houchard$NetBSD: timesoftfloat.txt,v 1.1 2000/06/06 08:15:11 bjh21 Exp $ 215144b0fSOlivier Houchard 315144b0fSOlivier HouchardDocumentation for the `timesoftfloat' Program of SoftFloat Release 2a 415144b0fSOlivier Houchard 515144b0fSOlivier HouchardJohn R. Hauser 615144b0fSOlivier Houchard1998 December 14 715144b0fSOlivier Houchard 815144b0fSOlivier Houchard 915144b0fSOlivier Houchard------------------------------------------------------------------------------- 1015144b0fSOlivier HouchardIntroduction 1115144b0fSOlivier Houchard 1215144b0fSOlivier HouchardThe `timesoftfloat' program evaluates the speed of SoftFloat's floating- 1315144b0fSOlivier Houchardpoint routines. Each routine can be evaluated for every relevant rounding 1415144b0fSOlivier Houchardmode, tininess mode, and/or rounding precision. 1515144b0fSOlivier Houchard 1615144b0fSOlivier Houchard 1715144b0fSOlivier Houchard------------------------------------------------------------------------------- 1815144b0fSOlivier HouchardContents 1915144b0fSOlivier Houchard 2015144b0fSOlivier Houchard Introduction 2115144b0fSOlivier Houchard Contents 2215144b0fSOlivier Houchard Legal Notice 2315144b0fSOlivier Houchard Executing `timesoftfloat' 2415144b0fSOlivier Houchard Options 2515144b0fSOlivier Houchard -help 2615144b0fSOlivier Houchard -precision32, -precision64, -precision80 2715144b0fSOlivier Houchard -nearesteven, -tozero, -down, -up 2815144b0fSOlivier Houchard -tininessbefore, -tininessafter 2915144b0fSOlivier Houchard Function Sets 3015144b0fSOlivier Houchard 3115144b0fSOlivier Houchard 3215144b0fSOlivier Houchard 3315144b0fSOlivier Houchard------------------------------------------------------------------------------- 3415144b0fSOlivier HouchardLegal Notice 3515144b0fSOlivier Houchard 3615144b0fSOlivier HouchardThe `timesoftfloat' program was written by John R. Hauser. 3715144b0fSOlivier Houchard 3815144b0fSOlivier HouchardTHIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort 3915144b0fSOlivier Houchardhas been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT 4015144b0fSOlivier HouchardTIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO 4115144b0fSOlivier HouchardPERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY 4215144b0fSOlivier HouchardAND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. 4315144b0fSOlivier Houchard 4415144b0fSOlivier Houchard 4515144b0fSOlivier Houchard------------------------------------------------------------------------------- 4615144b0fSOlivier HouchardExecuting `timesoftfloat' 4715144b0fSOlivier Houchard 4815144b0fSOlivier HouchardThe `timesoftfloat' program is intended to be invoked from a command line 4915144b0fSOlivier Houchardinterpreter as follows: 5015144b0fSOlivier Houchard 5115144b0fSOlivier Houchard timesoftfloat [<option>...] <function> 5215144b0fSOlivier Houchard 5315144b0fSOlivier HouchardHere square brackets ([]) indicate optional items, while angled brackets 5415144b0fSOlivier Houchard(<>) denote parameters to be filled in. The `<function>' argument is 5515144b0fSOlivier Houchardthe name of the SoftFloat routine to evaluate, such as `float32_add' or 5615144b0fSOlivier Houchard`float64_to_int32'. The allowed options are detailed in the next section, 5715144b0fSOlivier Houchard_Options_. If `timesoftfloat' is executed without any arguments, a summary 5815144b0fSOlivier Houchardof usage is written. It is also possible to evaluate all machine functions 5915144b0fSOlivier Houchardin a single invocation as explained in the section _Function_Sets_ later in 6015144b0fSOlivier Houchardthis document. 6115144b0fSOlivier Houchard 629c353fa4STom HukinsOrdinarily, a function's speed will be evaluated separately for each of 6315144b0fSOlivier Houchardthe four rounding modes, one after the other. If the rounding mode is not 6415144b0fSOlivier Houchardsupposed to have any affect on the results of a function--for instance, 6515144b0fSOlivier Houchardsome operations do not require rounding--only the nearest/even rounding mode 6615144b0fSOlivier Houchardis timed. In the same way, if a function is affected by the way in which 6715144b0fSOlivier Houchardunderflow tininess is detected, `timesoftfloat' times the function both with 6815144b0fSOlivier Houchardtininess detected before rounding and after rounding. For extended double- 6915144b0fSOlivier Houchardprecision operations affected by rounding precision control, `timesoftfloat' 7015144b0fSOlivier Houchardalso times the function for all three rounding precision modes, one after 7115144b0fSOlivier Houchardthe other. Evaluation of a function can be limited to a single rounding 7215144b0fSOlivier Houchardmode, a single tininess mode, and/or a single rounding precision with 7315144b0fSOlivier Houchardappropriate options (see _Options_). 7415144b0fSOlivier Houchard 7515144b0fSOlivier HouchardFor each function and mode evaluated, `timesoftfloat' reports the speed of 7615144b0fSOlivier Houchardthe function in kops/s, or ``thousands of operations per second''. This 7715144b0fSOlivier Houchardunit of measure differs from the traditional MFLOPS (``millions of floating- 7815144b0fSOlivier Houchardpoint operations per second'') only in being a factor of 1000 smaller. 7915144b0fSOlivier Houchard(1000 kops/s is exactly 1 MFLOPS.) Speeds are reported in thousands instead 8015144b0fSOlivier Houchardof millions because software floating-point often executes at less than 8115144b0fSOlivier Houchard1 MFLOPS. 8215144b0fSOlivier Houchard 8315144b0fSOlivier HouchardThe speeds reported by `timesoftfloat' may be affected somewhat by other 8415144b0fSOlivier Houchardprograms executing at the same time as `timesoftfloat'. 8515144b0fSOlivier Houchard 8615144b0fSOlivier HouchardNote that the remainder operations (`float32_rem', `float64_rem', 8715144b0fSOlivier Houchard`floatx80_rem' and `float128_rem') will be markedly slower than other 8815144b0fSOlivier Houchardoperations, particularly for extended double precision (`floatx80') and 8915144b0fSOlivier Houchardquadruple precision (`float128'). This is inherent to the remainder 9015144b0fSOlivier Houchardfunction itself and is not a failing of the SoftFloat implementation. 9115144b0fSOlivier Houchard 9215144b0fSOlivier Houchard 9315144b0fSOlivier Houchard------------------------------------------------------------------------------- 9415144b0fSOlivier HouchardOptions 9515144b0fSOlivier Houchard 9615144b0fSOlivier HouchardThe `timesoftfloat' program accepts several command options. If mutually 9715144b0fSOlivier Houchardcontradictory options are given, the last one has priority. 9815144b0fSOlivier Houchard 9915144b0fSOlivier Houchard- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10015144b0fSOlivier Houchard-help 10115144b0fSOlivier Houchard 10215144b0fSOlivier HouchardThe `-help' option causes a summary of program usage to be written, after 10315144b0fSOlivier Houchardwhich the program exits. 10415144b0fSOlivier Houchard 10515144b0fSOlivier Houchard- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10615144b0fSOlivier Houchard-precision32, -precision64, -precision80 10715144b0fSOlivier Houchard 10815144b0fSOlivier HouchardFor extended double-precision functions affected by rounding precision 10915144b0fSOlivier Houchardcontrol, the `-precision32' option restricts evaluation to only the cases 11015144b0fSOlivier Houchardin which rounding precision is equivalent to single precision. The other 11115144b0fSOlivier Houchardrounding precision options are not timed. Likewise, the `-precision64' 11215144b0fSOlivier Houchardand `-precision80' options fix the rounding precision equivalent to double 11315144b0fSOlivier Houchardprecision or extended double precision, respectively. These options are 11415144b0fSOlivier Houchardignored for functions not affected by rounding precision control. 11515144b0fSOlivier Houchard 11615144b0fSOlivier Houchard- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11715144b0fSOlivier Houchard-nearesteven, -tozero, -down, -up 11815144b0fSOlivier Houchard 11915144b0fSOlivier HouchardThe `-nearesteven' option restricts evaluation to only the cases in which 12015144b0fSOlivier Houchardthe rounding mode is nearest/even. The other rounding mode options are not 12115144b0fSOlivier Houchardtimed. Likewise, `-tozero' forces rounding to zero; `-down' forces rounding 12215144b0fSOlivier Houcharddown; and `-up' forces rounding up. These options are ignored for functions 12315144b0fSOlivier Houchardthat are exact and thus do not round. 12415144b0fSOlivier Houchard 12515144b0fSOlivier Houchard- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12615144b0fSOlivier Houchard-tininessbefore, -tininessafter 12715144b0fSOlivier Houchard 12815144b0fSOlivier HouchardThe `-tininessbefore' option restricts evaluation to only the cases 12915144b0fSOlivier Houcharddetecting underflow tininess before rounding. Tininess after rounding 13015144b0fSOlivier Houchardis not timed. Likewise, `-tininessafter' forces underflow tininess to be 13115144b0fSOlivier Houcharddetected after rounding only. These options are ignored for functions not 13215144b0fSOlivier Houchardaffected by the way in which underflow tininess is detected. 13315144b0fSOlivier Houchard 13415144b0fSOlivier Houchard- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13515144b0fSOlivier Houchard 13615144b0fSOlivier Houchard 13715144b0fSOlivier Houchard------------------------------------------------------------------------------- 13815144b0fSOlivier HouchardFunction Sets 13915144b0fSOlivier Houchard 14015144b0fSOlivier HouchardJust as `timesoftfloat' can test an operation for all four rounding modes in 14115144b0fSOlivier Houchardsequence, multiple operations can also be tested with a single invocation. 14215144b0fSOlivier HouchardThree sets are recognized: `-all1', `-all2', and `-all'. The set `-all1' 14315144b0fSOlivier Houchardcomprises all one-operand functions; `-all2' is all two-operand functions; 14415144b0fSOlivier Houchardand `-all' is all functions. A function set can be used in place of a 14515144b0fSOlivier Houchardfunction name in the command line, as in 14615144b0fSOlivier Houchard 14715144b0fSOlivier Houchard timesoftfloat [<option>...] -all 14815144b0fSOlivier Houchard 14915144b0fSOlivier Houchard 150