benchtests/README

   1 Using the glibc microbenchmark suite
   2 ====================================
   3
   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.
   7
   8 Running the benchmark:
   9 =====================
  10
  11 The benchmark can be executed by invoking make as follows:
  12
  13   $ make bench
  14
  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:
  17
  18   $ make bench-clean
  19
  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
  22 BENCH_DURATION.
  23
  24   $ make BENCH_DURATION=1 bench
  25
  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:
  30
  31   $ make USE_CLOCK_GETTIME=1 bench
  32
  33 Again, one must run `make bench-clean' before changing the measurement method.
  34
  35 Adding a function to benchtests:
  36 ===============================
  37
  38 If the name of the function is `foo', then the following procedure should allow
  39 one to add `foo' to the bench tests:
  40
  41 - Append the function name to the bench variable in the Makefile.
  42
  43 - Define foo-ARGLIST as a colon separated list of types of the input
  44   arguments.  Use `void' if function does not take any inputs.  Put in quotes
  45   if the input argument is a pointer, e.g.:
  46
  47      malloc-ARGLIST: "void *"
  48
  49 - Define foo-RET as the type the function returns.  Skip if the function
  50   returns void.  One could even skip foo-ARGLIST if the function does not
  51   take any inputs AND the function returns void.
  52
  53 - Make a file called `foo-inputs` with one input value per line, an input
  54   being a comma separated list of arguments to be passed into the function.
  55   See pow-inputs for an example.
  56
  57   The script that parses the -inputs file treats lines beginning with a single
  58   `#' as comments.  Lines beginning with two hashes `##' are treated specially
  59   as `directives'.
  60
  61 Multiple execution units per function:
  62 =====================================
  63
  64 Some functions have distinct performance characteristics for different input
  65 domains and it may be necessary to measure those separately.  For example, some
  66 math functions perform computations at different levels of precision (64-bit vs
  67 240-bit vs 768-bit) and mixing them does not give a very useful picture of the
  68 performance of these functions.  One could separate inputs for these domains in
  69 the same file by using the `name' directive that looks something like this:
  70
  71   ##name: 240bit
  72
  73 See the pow-inputs file for an example of what such a partitioned input file
  74 would look like.
  75
  76 Benchmark Sets:
  77 ==============
  78
  79 In addition to standard benchmarking of functions, one may also generate
  80 custom outputs for a set of functions.  This is currently used by string
  81 function benchmarks where the aim is to compare performance between
  82 implementations at various alignments and for various sizes.
  83
  84 To add a benchset for `foo':
  85
  86 - Add `foo' to the benchset variable.
  87 - Write your bench-foo.c that prints out the measurements to stdout.
  88 - On execution, a bench-foo.out is created in $(objpfx) with the contents of
  89   stdout.