Zephyr Benchmarking Framework

Macros
#define	ZTEST_BENCHMARK_SUITE(suite, setup_fn, teardown_fn)
	Define a benchmark suite.
#define	ZTEST_BENCHMARK(suite_name, benchmark, samples, setup_fn, teardown_fn)
	Define a benchmark with setup and teardown functions.
#define	ZTEST_BENCHMARK_TIMED(testsuite, benchmark, duration, setup_fn, teardown_fn)
	Define a timed benchmark with setup and teardown functions.
#define	ZTEST_BENCHMARK_MANUAL(suite_name, benchmark, samples, setup_fn, teardown_fn)
	Define a manually sampled benchmark.

Functions
void	ztest_benchmark_start (void)
	Begin the measured span of a manual benchmark iteration.
void	ztest_benchmark_end (void)
	End the measured span of a manual benchmark iteration.

Detailed Description

Macro Definition Documentation

ZTEST_BENCHMARK

#define ZTEST_BENCHMARK	(		suite_name,
			benchmark,
			samples,
			setup_fn,
			teardown_fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/benchmark.h>

Value:

static __noinline void Z_ZTEST_BENCHMARK_FN(suite_name, benchmark)(void);               \
static const STRUCT_SECTION_ITERABLE(ztest_benchmark,                                   \
                                     Z_ZTEST_BENCHMARK_NODE(suite_name, benchmark)) =   \
{                                                                                       \
        .name = #benchmark,                                                             \
        .iterations = samples,                                                          \
        .setup = setup_fn,                                                              \
        .run = Z_ZTEST_BENCHMARK_FN(suite_name, benchmark),                             \
        .teardown = teardown_fn,                                                        \
        .suite = &Z_ZTEST_BENCHMARK_SUITE_NODE(suite_name),                             \
};                                                                                      \
static __noinline void Z_ZTEST_BENCHMARK_FN(suite_name, benchmark)(void)

Define a benchmark with setup and teardown functions.

Parameters

suite_name	Name of the suite the benchmark belongs to
benchmark	Name of the benchmark
samples	Number of iterations to run the benchmark
setup_fn	Function to run before the benchmark
teardown_fn	Function to run after the benchmark

ZTEST_BENCHMARK_MANUAL

#define ZTEST_BENCHMARK_MANUAL	(		suite_name,
			benchmark,
			samples,
			setup_fn,
			teardown_fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/benchmark.h>

Value:

static __noinline void Z_ZTEST_BENCHMARK_FN(suite_name, benchmark)(void);               \
static STRUCT_SECTION_ITERABLE(ztest_benchmark_manual,                                  \
                               Z_ZTEST_BENCHMARK_MANUAL_NODE(suite_name, benchmark)) =  \
{                                                                                       \
        .name = #benchmark,                                                             \
        .iterations = samples,                                                          \
        .setup = setup_fn,                                                              \
        .run = Z_ZTEST_BENCHMARK_FN(suite_name, benchmark),                             \
        .teardown = teardown_fn,                                                        \
        .suite = &Z_ZTEST_BENCHMARK_SUITE_NODE(suite_name),                             \
};                                                                                      \
static __noinline void Z_ZTEST_BENCHMARK_FN(suite_name, benchmark)(void)

Define a manually sampled benchmark.

The framework runs the body once per iteration exactly as it does for ZTEST_BENCHMARK(), but the body decides which part of itself is measured by bracketing it with ztest_benchmark_start() and ztest_benchmark_end():

ZTEST_BENCHMARK_MANUAL(my_suite, my_benchmark, 1000, NULL, NULL)
{
        prepare();
        ztest_benchmark_start();
        operation_under_test();
        ztest_benchmark_end();
}

That covers a span the framework cannot time by itself because it does not start and end where the body does. Both hooks are safe to call from an ISR, so a span need not even begin and end in the same execution context: for the latency from an interrupt to the thread it wakes, the ISR calls ztest_benchmark_start() and the woken thread calls ztest_benchmark_end().

A body that records no span contributes no sample for that iteration.

Parameters

suite_name	Name of the suite the benchmark belongs to
benchmark	Name of the benchmark
samples	Number of iterations to run the benchmark
setup_fn	Function to run before each iteration
teardown_fn	Function to run after each iteration

ZTEST_BENCHMARK_SUITE

#define ZTEST_BENCHMARK_SUITE	(		suite,
			setup_fn,
			teardown_fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/benchmark.h>

Value:

static const STRUCT_SECTION_ITERABLE(ztest_benchmark_suite,                     \
                                     Z_ZTEST_BENCHMARK_SUITE_NODE(suite)) =     \
{                                                                               \
        .name = #suite,                                                         \
        .setup = setup_fn,                                                      \
        .teardown = teardown_fn,                                                \
}

Define a benchmark suite.

Parameters

suite	Name of the suite
setup_fn	Function to run before the suite
teardown_fn	Function to run after the suite

ZTEST_BENCHMARK_TIMED

#define ZTEST_BENCHMARK_TIMED	(		testsuite,
			benchmark,
			duration,
			setup_fn,
			teardown_fn )

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/benchmark.h>

Value:

static __noinline void Z_ZTEST_BENCHMARK_FN(testsuite, benchmark)(void);                \
static const STRUCT_SECTION_ITERABLE(ztest_benchmark_timed,                             \
                                Z_ZTEST_BENCHMARK_TIMED_NODE(testsuite, benchmark)) =   \
{                                                                                       \
        .duration_ms = duration,                                                        \
        .name = #benchmark,                                                             \
        .setup = setup_fn,                                                              \
        .run = Z_ZTEST_BENCHMARK_FN(testsuite, benchmark),                              \
        .teardown = teardown_fn,                                                        \
        .suite = &Z_ZTEST_BENCHMARK_SUITE_NODE(testsuite),                              \
};                                                                                      \
static __noinline void Z_ZTEST_BENCHMARK_FN(testsuite, benchmark)(void)

Define a timed benchmark with setup and teardown functions.

Parameters

testsuite	Name of the suite the benchmark belongs to
benchmark	Name of the benchmark
duration	Duration in milliseconds to run the benchmark
setup_fn	Function to run before the benchmark
teardown_fn	Function to run after the benchmark

Function Documentation

ztest_benchmark_end()

void ztest_benchmark_end

(

void

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/benchmark.h>

End the measured span of a manual benchmark iteration.

Timestamps now. Without a preceding ztest_benchmark_start() there is no span, and the call is ignored.

Safe to call from an ISR, for the same reason as ztest_benchmark_start(): the span is only handed to the statistics once the body has returned to thread context.

ztest_benchmark_start()

void ztest_benchmark_start

(

void

)

#include </__w/zephyr/zephyr/subsys/testsuite/ztest/include/zephyr/benchmark.h>

Begin the measured span of a manual benchmark iteration.

Timestamps now. Anything the body did before this call is excluded from the measurement.

Safe to call from an ISR: it only takes a timestamp, so a span whose start belongs to interrupt context is marked from there directly. The sample itself is computed once the body has returned.

Calls made outside a ZTEST_BENCHMARK_MANUAL() body are ignored.