LMBENCH(3)

NAME
lmbench - benchmarking toolbox

SYNOPSIS
#include "lmbench.h"
BENCH(loop_body, enough)
BENCH1(loop_body, enough)
uint64    get_n();
void    milli(char *s, uint64 n);
void    micro(char *s, uint64 n);
void    nano(char *s, uint64 n);
void    mb(uint64 bytes);
void    kb(uint64 bytes);

DESCRIPTION
Creating benchmarks using the lmbench timing harness is easy. Since it is so easy to measure performance using lmbench , it is possible to quickly answer questions that arise during system design, development, or tuning. For example, image processing

There are two attributes that are critical for performance, latency and bandwidth, and lmbench's timing harness makes it easy to measure and report results for both. The measurement interface, BENCH and 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.

There are a number of factors to consider when building benchmarks.

The timing harness requires that the benchmarked operation be idempotent so that it can be repeated indefinitely.

The timing subsystem includes two macros, BENCH and BENCH1, which provide a uniform method for conducting experiments. BENCH1 does one experiment and saves the result, while BENCH does eleven experiments and saves the median result.

BENCH(loop_body, enough)
    measures the performance of loop_body repeatedly and report the median result.

BENCH1(loop_body, enough)
    measures the performance of loop_body once.

uint64	get_n()
    returns the number of times loop_body was executed during the timing interval.

void	milli(char *s, uint64 n)
    print out the time per operation in milli-seconds. n is the number of operations during the timing interval, which is passed as a parameter because each loop_body can contain several operations.

void	micro(char *s, uint64 n)
    print the time per opertaion in micro-seconds.

void	nano(char *s, uint64 n)
    print the time per operation in nano-seconds.

void	mb(uint64 bytes)
    print the bandwidth in megabytes per second.

void	kb(uint64 bytes)
    print the bandwidth in kilobytes per second.

USING lmbench
Here is an example of a simple benchmark that measures the latency of the random number generator lrand48():

    #include "lmbench.h"
    int
    main(int argc, char *argv[])
    {
        BENCH(lrand48(), 0);
        micro("lrand48()", get_n());
        exit(0);
    }

Here is a simple benchmark that measures and reports the bandwidth of copy():

    #include "lmbench.h"
    int
    main(int argc, char *argv[])
    {
        char    *a = malloc(1024 * 1024);
        char    *b = malloc(1024 * 1024);
        BENCH(bcopy(a, b, 1024*1024), 0);
        mb(get_n()*1024*1024);
        exit(0);
    }

VARIABLES
There are three environment variables that can be used to modify the lmbench timing subsystem: ENOUGH, TIMING_O, and LOOP_O.

FUTURES
Development of lmbench is continuing.

SEE ALSO
lmbench(8), timing(3), reporting(3), results(3).

AUTHOR
Carl Staelin and Larry McVoy.

Comments, suggestions, and bug reports are always welcome.