1/**
2 * \file
3 * \brief Bench library.
4 */
5
6/*
7 * Copyright (c) 2007, 2008, 2009, 2010, ETH Zurich.
8 * All rights reserved.
9 *
10 * This file is distributed under the terms in the attached LICENSE file.
11 * If you do not find this file, copies can be found by writing to:
12 * ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
13 */
14
15#ifndef BENCH_H
16#define BENCH_H
17
18#include <barrelfish/types.h> // for cycles_t
19#include <bench/bench_arch.h>
20#include <sys/cdefs.h>
21
22#define BENCH_IGNORE_WATERMARK 0XDEADBEEF
23
24#define BENCH_DUMP_OCTAVE 0
25
26__BEGIN_DECLS
27void bench_init(void);
28cycles_t bench_avg(cycles_t *array, size_t len);
29cycles_t bench_variance(cycles_t *array, size_t len);
30void bench_stddev(cycles_t *array, size_t len, uint8_t correction,
31                  cycles_t *ret_avg, cycles_t *ret_stddev);
32cycles_t bench_min(cycles_t *array, size_t len);
33cycles_t bench_max(cycles_t *array, size_t len);
34cycles_t bench_tscoverhead(void);
35cycles_t bench_time_diff(cycles_t tsc_start, cycles_t tsc_end);
36__END_DECLS
37
38
39/*
40 * Control functions for benchmarks
41 */
42
43enum bench_ctl_mode {
44    // Fixed number of runs (exactly min_runs)
45    BENCH_MODE_FIXEDRUNS,
46};
47
48struct bench_ctl {
49    enum bench_ctl_mode mode;
50    size_t              result_dimensions;
51
52    size_t              min_runs;
53    size_t              dry_runs;
54
55    size_t              result_count;
56    cycles_t           *data;
57};
58
59typedef struct bench_ctl bench_ctl_t;
60
61
62/**
63 * Initialize a benchmark control instance.
64 *
65 * @param mode       Mode of the benchmark (enum bench_ctl_mode)
66 * @param dimensions Number of values each run produces
67 * @param min_runs   Minimal number of runs to be executed
68 *
69 * @return Control handle, to be passed on subsequent calls to bench_ctl_
70 *         functions.
71 */
72bench_ctl_t *bench_ctl_init(enum bench_ctl_mode mode,
73                            size_t              dimensions,
74                            size_t              min_runs);
75
76/**
77 * Frees all resources associated with this benchmark control instance. Should
78 * be called after the benchmark is done and the results are dumped.
79 *
80 * @param ctl Control handle
81 */
82void bench_ctl_destroy(bench_ctl_t *ctl);
83
84/**
85 * Add a fixed number of dry runs whose results should not be recorded. Should
86 * be called before any calls to bench_ctl_add_run().
87 *
88 * @param ctl      Control handle
89 * @param dry_runs Number of dry runs
90 */
91void bench_ctl_dry_runs(bench_ctl_t *ctl,
92                        size_t       dry_runs);
93
94/**
95 * Add results from one run of the benchmark.
96 *
97 * @param ctl    Control handle
98 * @param result Pointer to the 'dimensions' values of this run
99 *
100 * @return true if this was the last run necessary, false if more runs are
101 *         needed.
102 */
103bool bench_ctl_add_run(bench_ctl_t *ctl,
104                       cycles_t* result);
105
106/**
107 * Dump results of the benchmark to the standard output. One line per run, the
108 * lines will be prefixed with prefix, the values separeted using commas.
109 *
110 * @param ctl    Control handle
111 * @param prefix String to be printed before each line
112 */
113void bench_ctl_dump_csv(bench_ctl_t *ctl,
114                        const char  *prefix, uint64_t tscperus);
115/**
116 * Use bincounting to reduce the amount of data that is printed.
117 * One line per bin (bin_count + 2 for those below and above the specified
118 * range) with two columns each is emited at most. Lines for empty bins are
119 * omitted except for above and below. The first column contains the start
120 * of the range for this bin (or below/above for the border cases), while the
121 * second column contains the number of values in that bin.
122 *
123 * @param ctl       Control handle
124 * @param dimenison Index of the value in the run
125 * @param bin_count Number of bins to create
126 * @param min       Minimum of range to be represented by bins
127 * @param max       Maximum of range to be represented by bins
128 * @param prefix    String to be printed before each line
129 * @param tscperus  cpu ticks per micro-second
130 */
131void bench_ctl_dump_csv_bincounting(bench_ctl_t *ctl,
132                                    size_t dimension,
133                                    size_t bin_count,
134                                    cycles_t min,
135                                    cycles_t max,
136                                    const char *prefix,
137                                    cycles_t tscperus);
138
139
140void bench_ctl_dump_analysis(bench_ctl_t *ctl,
141                                    size_t dimension,
142                                    const char *prefix,
143                                    cycles_t tscperus);
144
145
146#endif // BENCH_H
147