From fef94eab0bd308d5059a2588c753bf9a4926845d Mon Sep 17 00:00:00 2001 From: Siddhesh Poyarekar Date: Tue, 21 May 2013 14:59:50 +0530 Subject: Add a README for benchtests Move instructions from the Makefile here and expand on them. --- benchtests/Makefile | 20 --------------- benchtests/README | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 20 deletions(-) create mode 100644 benchtests/README (limited to 'benchtests') diff --git a/benchtests/Makefile b/benchtests/Makefile index 861839013b..913fe4d8f3 100644 --- a/benchtests/Makefile +++ b/benchtests/Makefile @@ -18,26 +18,6 @@ # Makefile for benchmark tests. The only useful target here is `bench`. -# Adding a new function `foo`: -# --------------------------- - -# - Append the function name to the bench variable - -# - Define foo-ARGLIST as a colon separated list of types of the input -# arguments. Use `void` if function does not take any inputs. Put in quotes -# if the input argument is a pointer, e.g.: - -# malloc-ARGLIST: "void *" - -# - Define foo-RET as the type the function returns. Skip if the function -# returns void. One could even skip foo-ARGLIST if the function does not -# take any inputs AND the function returns void. - - -# - Make a file called `foo-inputs` with one input value per line, an input -# being a comma separated list of arguments to be passed into the function. -# See pow-inputs for an example. - subdir := benchtests bench := exp pow rint sin cos tan atan modf diff --git a/benchtests/README b/benchtests/README new file mode 100644 index 0000000000..8135069fea --- /dev/null +++ b/benchtests/README @@ -0,0 +1,74 @@ +Using the glibc microbenchmark suite +==================================== + +The glibc microbenchmark suite automatically generates code for specified +functions, builds and calls them repeatedly for given inputs to give some +basic performance properties of the function. + +Running the benchmark: +===================== + +The benchmark can be executed by invoking make as follows: + + $ make bench + +This runs each function for 10 seconds and appends its output to +benchtests/bench.out. To ensure that the tests are rebuilt, one could run: + + $ make bench-clean + +The duration of each test can be configured setting the BENCH_DURATION variable +in the call to make. One should run `make bench-clean' before changing +BENCH_DURATION. + + $ make BENCH_DURATION=1 bench + +The benchmark suite does function call measurements using architecture-specific +high precision timing instructions whenever available. When such support is +not available, it uses clock_gettime (CLOCK_PROCESS_CPUTIME_ID). One can force +the benchmark to use clock_gettime by invoking make as follows: + + $ make USE_CLOCK_GETTIME=1 bench + +Again, one must run `make bench-clean' before changing the measurement method. + +Adding a function to benchtests: +=============================== + +If the name of the function is `foo', then the following procedure should allow +one to add `foo' to the bench tests: + +- Append the function name to the bench variable in the Makefile. + +- Define foo-ARGLIST as a colon separated list of types of the input + arguments. Use `void' if function does not take any inputs. Put in quotes + if the input argument is a pointer, e.g.: + + malloc-ARGLIST: "void *" + +- Define foo-RET as the type the function returns. Skip if the function + returns void. One could even skip foo-ARGLIST if the function does not + take any inputs AND the function returns void. + +- Make a file called `foo-inputs` with one input value per line, an input + being a comma separated list of arguments to be passed into the function. + See pow-inputs for an example. + + The script that parses the -inputs file treats lines beginning with a single + `#' as comments. Lines beginning with two hashes `##' are treated specially + as `directives'. + +Multiple execution units per function: +===================================== + +Some functions have distinct performance characteristics for different input +domains and it may be necessary to measure those separately. For example, some +math functions perform computations at different levels of precision (64-bit vs +240-bit vs 768-bit) and mixing them does not give a very useful picture of the +performance of these functions. One could separate inputs for these domains in +the same file by using the `name' directive that looks something like this: + + ##name: 240bit + +See the pow-inputs file for an example of what such a partitioned input file +would look like. -- cgit 1.4.1