.\"
.\" @(#)lmbench.man	2.0 98/04/24
.\"
.\"   lmbench - benchmarking toolbox
.\"
.\"   Copyright (C) 1998  Carl Staelin and Larry McVoy
.\"   E-mail: staelin@hpl.hp.com
.\"
.TH "LMBENCH" 3 "$Date$" "(c)1998 Larry McVoy" "LMBENCH"
.SH "NAME"
lmbench \- benchmarking toolbox
.SH "SYNOPSIS"
.ft C
#include "lmbench.h"
.br
BENCH(loop_body, enough)
.br
BENCH1(loop_body, enough)
.br
uint64	get_n();
.br
void	milli(char *s, uint64 n);
.br
void	micro(char *s, uint64 n);
.br
void	nano(char *s, uint64 n);
.br
void	mb(uint64 bytes);
.br
void	kb(uint64 bytes);
.ft R
.SH "DESCRIPTION"
Creating benchmarks using the 
.I lmbench 
timing harness is easy.
Since it is so easy to measure performance using 
.I lmbench , 
it is possible to quickly answer questions that arise during system
design, development, or tuning.  For example, image processing 
.P
There are two attributes that are critical for performance, latency 
and bandwidth, and 
.I lmbench's 
timing harness makes it easy to measure and report results for both.  
The measurement interface, 
.B BENCH 
and 
.BR BENCH1 , 
are identical, but the reporting functions are different.
Latency is usually important for frequently executed operations, and
bandwidth is usually important when moving large chunks of data.
.P
There are a number of factors to consider when building benchmarks.
.P
The timing harness requires that the benchmarked operation
be idempotent so that it can be repeated indefinitely.
.P
The timing subsystem includes two macros, 
.B BENCH 
and 
.BR BENCH1 ,
which provide a uniform method for conducting experiments.  
.B BENCH1
does one experiment and saves the result, while 
.B BENCH 
does eleven
experiments and saves the median result.
.TP
.B "BENCH(loop_body, enough)"
measures the performance of 
.I loop_body
repeatedly and report the median result.
.TP
.B "BENCH1(loop_body, enough)"
measures the performance of 
.I loop_body
once.
.TP
.B "uint64	get_n()"
returns the number of times 
.I loop_body
was executed during the timing interval.
.TP
.B "void	milli(char *s, uint64 n)"
print out the time per operation in milli-seconds.  
.I n 
is the number of operations during the timing interval, which is passed 
as a parameter because each
.I loop_body
can contain several operations.
.TP
.B "void	micro(char *s, uint64 n)"
print the time per opertaion in micro-seconds.
.TP
.B "void	nano(char *s, uint64 n)"
print the time per operation in nano-seconds.
.TP
.B "void	mb(uint64 bytes)"
print the bandwidth in megabytes per second.
.TP
.B "void	kb(uint64 bytes)"
print the bandwidth in kilobytes per second.
.SH "USING lmbench"
Here is an example of a simple benchmark that measures the latency
of the random number generator 
.BR lrand48() :
.ft C
.IP
#include "lmbench.h"
.br
int
.br
main(int argc, char *argv[])
.br
{
.br
	BENCH(lrand48(), 0);
.br
	micro("lrand48()", get_n());
.br
	exit(0);
.br
}
.ft R
.br
.P
Here is a simple benchmark that measures and reports the bandwidth of 
.BR copy() :
.ft C
.IP 
#include "lmbench.h"
.br
int
.br
main(int argc, char *argv[])
.br
{
.br
	char	*a = malloc(1024 * 1024);
.br
	char	*b = malloc(1024 * 1024);
.br
	BENCH(bcopy(a, b, 1024*1024), 0);
.br
	mb(get_n()*1024*1024);
.br
	exit(0);
.br
}
.ft R
.SH "VARIABLES"
There are three environment variables that can be used to modify the 
.I lmbench
timing subsystem: ENOUGH, TIMING_O, and LOOP_O.
.SH "FUTURES"
Development of 
.I lmbench 
is continuing.  
.SH "SEE ALSO"
lmbench(8), timing(3), reporting(3), results(3).
.SH "AUTHOR"
Carl Staelin and Larry McVoy.
.PP
Comments, suggestions, and bug reports are always welcome.