1 Using the glibc microbenchmark suite
2 ====================================
4 The glibc microbenchmark suite automatically generates code for specified
5 functions, builds and calls them repeatedly for given inputs to give some
6 basic performance properties of the function.
11 The benchmark can be executed by invoking make as follows:
15 This runs each function for 10 seconds and appends its output to
16 benchtests/bench.out. To ensure that the tests are rebuilt, one could run:
20 The duration of each test can be configured setting the BENCH_DURATION variable
21 in the call to make. One should run `make bench-clean' before changing
24 $ make BENCH_DURATION=1 bench
26 The benchmark suite does function call measurements using architecture-specific
27 high precision timing instructions whenever available. When such support is
28 not available, it uses clock_gettime (CLOCK_PROCESS_CPUTIME_ID). One can force
29 the benchmark to use clock_gettime by invoking make as follows:
31 $ make USE_CLOCK_GETTIME=1 bench
33 Again, one must run `make bench-clean' before changing the measurement method.
35 Adding a function to benchtests:
36 ===============================
38 If the name of the function is `foo', then the following procedure should allow
39 one to add `foo' to the bench tests:
41 - Append the function name to the bench variable in the Makefile.
43 - Make a file called `foo-inputs` to provide the definition and input for the
44 function. The file should have some directives telling the parser script
45 about the function and then one input per line. Directives are lines that
46 have a special meaning for the parser and they begin with two hashes '##'.
47 The following directives are recognized:
49 - args: This should be assigned a colon separated list of types of the input
50 arguments. This directive may be skipped if the function does not take any
52 - ret: This should be assigned the type that the function returns. This
53 directive may be skipped if the function does not return a value.
54 - includes: This should be assigned a comma-separated list of headers that
55 need to be included to provide declarations for the function and types it
56 may need (specifically, this includes using "#include <header>").
57 - include-sources: This should be assigned a comma-separated list of source
58 files that need to be included to provide definitions of global variables
59 and functions (specifically, this includes using "#include "source").
60 - name: See following section for instructions on how to use this directive.
62 Lines beginning with a single hash '#' are treated as comments. See
63 pow-inputs for an example of an input file.
65 Multiple execution units per function:
66 =====================================
68 Some functions have distinct performance characteristics for different input
69 domains and it may be necessary to measure those separately. For example, some
70 math functions perform computations at different levels of precision (64-bit vs
71 240-bit vs 768-bit) and mixing them does not give a very useful picture of the
72 performance of these functions. One could separate inputs for these domains in
73 the same file by using the `name' directive that looks something like this:
77 See the pow-inputs file for an example of what such a partitioned input file
83 In addition to standard benchmarking of functions, one may also generate
84 custom outputs for a set of functions. This is currently used by string
85 function benchmarks where the aim is to compare performance between
86 implementations at various alignments and for various sizes.
88 To add a benchset for `foo':
90 - Add `foo' to the benchset variable.
91 - Write your bench-foo.c that prints out the measurements to stdout.
92 - On execution, a bench-foo.out is created in $(objpfx) with the contents of