Back to home page

glibc Cross Reference

 
 

    


0001 Using the glibc microbenchmark suite
0002 ====================================
0003 
0004 The glibc microbenchmark suite automatically generates code for specified
0005 functions, builds and calls them repeatedly for given inputs to give some
0006 basic performance properties of the function.
0007 
0008 Running the benchmark:
0009 =====================
0010 
0011 The benchmark can be executed by invoking make as follows:
0012 
0013   $ make bench
0014 
0015 This runs each function for 10 seconds and appends its output to
0016 benchtests/bench.out.  To ensure that the tests are rebuilt, one could run:
0017 
0018   $ make bench-clean
0019 
0020 The duration of each test can be configured setting the BENCH_DURATION variable
0021 in the call to make.  One should run `make bench-clean' before changing
0022 BENCH_DURATION.
0023 
0024   $ make BENCH_DURATION=1 bench
0025 
0026 The benchmark suite does function call measurements using architecture-specific
0027 high precision timing instructions whenever available.  When such support is
0028 not available, it uses clock_gettime (CLOCK_PROCESS_CPUTIME_ID).  One can force
0029 the benchmark to use clock_gettime by invoking make as follows:
0030 
0031   $ make USE_CLOCK_GETTIME=1 bench
0032 
0033 Again, one must run `make bench-clean' before changing the measurement method.
0034 
0035 Adding a function to benchtests:
0036 ===============================
0037 
0038 If the name of the function is `foo', then the following procedure should allow
0039 one to add `foo' to the bench tests:
0040 
0041 - Append the function name to the bench variable in the Makefile.
0042 
0043 - Make a file called `foo-inputs` to provide the definition and input for the
0044   function.  The file should have some directives telling the parser script
0045   about the function and then one input per line.  Directives are lines that
0046   have a special meaning for the parser and they begin with two hashes '##'.
0047   The following directives are recognized:
0048 
0049   - args: This should be assigned a colon separated list of types of the input
0050     arguments.  This directive may be skipped if the function does not take any
0051     inputs.  One may identify output arguments by nesting them in <>.  The
0052     generator will create variables to get outputs from the calling function.
0053   - ret: This should be assigned the type that the function returns.  This
0054     directive may be skipped if the function does not return a value.
0055   - includes: This should be assigned a comma-separated list of headers that
0056     need to be included to provide declarations for the function and types it
0057     may need (specifically, this includes using "#include <header>").
0058   - include-sources: This should be assigned a comma-separated list of source
0059     files that need to be included to provide definitions of global variables
0060     and functions (specifically, this includes using "#include "source").
0061   - name: See following section for instructions on how to use this directive.
0062 
0063   Lines beginning with a single hash '#' are treated as comments.  See
0064   pow-inputs for an example of an input file.
0065 
0066 Multiple execution units per function:
0067 =====================================
0068 
0069 Some functions have distinct performance characteristics for different input
0070 domains and it may be necessary to measure those separately.  For example, some
0071 math functions perform computations at different levels of precision (64-bit vs
0072 240-bit vs 768-bit) and mixing them does not give a very useful picture of the
0073 performance of these functions.  One could separate inputs for these domains in
0074 the same file by using the `name' directive that looks something like this:
0075 
0076   ##name: 240bit
0077 
0078 See the pow-inputs file for an example of what such a partitioned input file
0079 would look like.
0080 
0081 Benchmark Sets:
0082 ==============
0083 
0084 In addition to standard benchmarking of functions, one may also generate
0085 custom outputs for a set of functions.  This is currently used by string
0086 function benchmarks where the aim is to compare performance between
0087 implementations at various alignments and for various sizes.
0088 
0089 To add a benchset for `foo':
0090 
0091 - Add `foo' to the benchset variable.
0092 - Write your bench-foo.c that prints out the measurements to stdout.
0093 - On execution, a bench-foo.out is created in $(objpfx) with the contents of
0094   stdout.