Executing Time 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:

  1. Call timing_init() to initialize the timer.

  2. Call timing_start() to signal the start of gathering of timing information. This usually starts the timer.

  3. Call timing_counter_get() to mark the start of code execution.

  4. Call timing_counter_get() to mark the end of code execution.

  5. Call timing_cycles_get() to get the number of timer cycles between start and end of code execution.

  6. Call timing_cycles_to_ns() with total number of cycles to convert number of cycles to nanoseconds.

  7. Repeat from step 3 to gather timing information for other blocks of code.

  8. 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 <zephyr/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.

Returns:

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.

Parameters:

  • start – Pointer to counter at start of a measured execution.

  • end – Pointer to counter at stop of a measured execution.

Returns:

Number of cycles between start and end.

static inline uint64_t timing_freq_get(void)

Get frequency of counter used (in Hz).

Returns:

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.

Parameters:

  • cycles – Number of cycles

Returns:

Converted time value

static inline uint64_t timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count)

Convert number of cycles into nanoseconds with averaging.

Parameters:

  • cycles – Number of cycles

  • count – Times of accumulated cycles to average over

Returns:

Converted time value

static inline uint32_t timing_freq_get_mhz(void)

Get frequency of counter used (in MHz).

Returns:

Frequency of counter used for timing in MHz.