uspace/app/hbench/doc/doxygroups.h

   1 /** @addtogroup hbench hbench
   2  * @brief User space benchmarks
   3  * @ingroup apps
   4  *
   5  * @details
   6  *
   7  * To add a new benchmark, you need to implement the actual benchmarking
   8  * code and register it.
   9  *
  10  * Registration is done by adding
  11  * <code>extern benchmark_t bench_YOUR_NAME</code> reference to benchlist.h
  12  * and by adding it to the array in benchlist.c.
  13  *
  14  * The actual benchmark should reside in a separate file (see malloc/malloc1.c
  15  * for example) and has to (at least) declare one function (the actual
  16  * benchmark) and fill-in the benchmark_t structure.
  17  *
  18  * Fill-in the name of the benchmark, its description and a reference to the
  19  * benchmark function to the benchmark_t.
  20  *
  21  * The benchmarking function has to accept trhee arguments:
  22  *  @li bench_env_t: benchmark environment configuration
  23  *  @li bench_run_t: call bench_run_start and bench_run_stop around the
  24  *      actual benchmarking code
  25  *  @li uint64_t: size of the workload - typically number of inner loops in
  26  *      your benchmark (used to self-calibrate benchmark size)
  27  *
  28  * Typically, the structure of the function is following:
  29  * @code{c}
  30  * static bool runnerconst bench_env_t const *envbench_run_t *run, uint64_t size)
  31  * {
  32  *      bench_run_start(run);
  33  *      for (uint64_t i = 0; i < size; i++) {
  34  *              // measured action
  35  *              if (something_fails) {
  36  *                  return bench_run_fail(run, "oops: %s (%d)", str_error(rc), rc);
  37  *              }
  38  *      }
  39  *      bench_run_stop(run);
  40  *
  41  *      return true;
  42  * }
  43  * @endcode
  44  */