Timing Functions¶

The timing functions can be used to obtain execution time of a section of code to aid in analysis and optimization.

Please note that the timing functions may use a different timer than the default kernel timer, where the timer being used is specified by architecture, SoC or board configuration.

Configuration¶

To allow using the timing functions, CONFIG_TIMING_FUNCTIONS needs to be enabled.

Usage¶

To gather timing information:

Call timing_init() to initialize the timer.
Call timing_start() to signal the start of gathering of timing information. This usually starts the timer.
Call timing_counter_get() to mark the start of code execution.
Call timing_counter_get() to mark the end of code execution.
Call timing_cycles_get() to get the number of timer cycles between start and end of code execution.
Call timing_cycles_to_ns() with total number of cycles to convert number of cycles to nanoseconds.
Repeat from step 3 to gather timing information for other blocks of code.
Call timing_stop() to signal the end of gathering of timing information. This usually stops the timer.

Example¶

This shows an example on how to use the timing functions:

#include <timing/timing.h>

void gather_timing(void)
{
    timing_t start_time, end_time;
    uint64_t total_cycles;
    uint64_t total_ns;

    timing_init();
    timing_start();

    start_time = timing_counter_get();

    code_execution_to_be_measured();

    end_time = timing_counter_get();

    total_cycles = timing_cycles_get(&start_time, &end_time);
    total_ns = timing_cycles_to_ns(total_cycles);

    timing_stop();
}

API documentation¶

group timing_api

Timing Measurement APIs.

Functions

void timing_init(void)¶

Initialize the timing subsystem.

Perform the necessary steps to initialize the timing subsystem.

void timing_start(void)¶

Signal the start of the timing information gathering.

Signal to the timing subsystem that timing information will be gathered from this point forward.

void timing_stop(void)¶

Signal the end of the timing information gathering.

Signal to the timing subsystem that timing information is no longer being gathered from this point forward.

static inline timing_t timing_counter_get(void)¶

Return timing counter.

Return: Timing counter.

static inline uint64_t timing_cycles_get(volatile timing_t *const start, volatile timing_t *const end)¶

Get number of cycles between start and end.

For some architectures or SoCs, the raw numbers from counter need to be scaled to obtain actual number of cycles.

Return

Number of cycles between start and end.

Parameters

start: Pointer to counter at start of a measured execution.
end: Pointer to counter at stop of a measured execution.

static inline uint64_t timing_freq_get(void)¶

Get frequency of counter used (in Hz).

Return: Frequency of counter used for timing in Hz.

static inline uint64_t timing_cycles_to_ns(uint64_t cycles)¶

Convert number of cycles into nanoseconds.

Return

Converted time value

Parameters

cycles: Number of cycles

static inline uint64_t timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count)¶

Convert number of cycles into nanoseconds with averaging.

Return

Converted time value

Parameters

cycles: Number of cycles
count: Times of accumulated cycles to average over

static inline uint32_t timing_freq_get_mhz(void)¶

Get frequency of counter used (in MHz).

Return: Frequency of counter used for timing in MHz.