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.

The timing measurement APIs 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.

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.

group timing_api_arch

Arch specific Timing Measurement APIs.

Implements the necessary bits to support timing measurement using architecture specific timing measurement mechanism.

Functions

void arch_timing_init(void)

Initialize the timing subsystem.

Perform the necessary steps to initialize the timing subsystem.

See also

timing_init()

void arch_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.

See also

timing_start()

Note

Any call to arch_timing_counter_get() must be done between calls to arch_timing_start() and arch_timing_stop(), and on the same CPU core.

void arch_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.

See also

timing_stop()

Note

Any call to arch_timing_counter_get() must be done between calls to arch_timing_start() and arch_timing_stop(), and on the same CPU core.

timing_t arch_timing_counter_get(void)

Return timing counter.

See also

timing_counter_get()

Note

Any call to arch_timing_counter_get() must be done between calls to arch_timing_start() and arch_timing_stop(), and on the same CPU core.

Note

Not all architectures have a timing counter with 64 bit precision. It is possible to see this value “go backwards” due to internal rollover. Timing code must be prepared to address the rollover (with platform-dependent code, e.g. by casting to a uint32_t before subtraction) or by using arch_timing_cycles_get() which is required to understand the distinction.

Returns:

Timing counter.

uint64_t arch_timing_cycles_get(volatile timing_t *const start, volatile timing_t *const end)

Get number of cycles between start and end.

See also

timing_cycles_get()

Note

For some architectures, the raw numbers from counter need to be scaled to obtain actual number of cycles, or may roll over internally. This function computes a positive-definite interval between two returned cycle values.

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.

uint64_t arch_timing_freq_get(void)

Get frequency of counter used (in Hz).

See also

timing_freq_get()

Returns:

Frequency of counter used for timing in Hz.

uint64_t arch_timing_cycles_to_ns(uint64_t cycles)

Convert number of cycles into nanoseconds.

See also

timing_cycles_to_ns()

Parameters:

  • cycles – Number of cycles

Returns:

Converted time value

uint64_t arch_timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count)

Convert number of cycles into nanoseconds with averaging.

See also

timing_cycles_to_ns_avg()

Parameters:

  • cycles – Number of cycles

  • count – Times of accumulated cycles to average over

Returns:

Converted time value

uint32_t arch_timing_freq_get_mhz(void)

Get frequency of counter used (in MHz).

See also

timing_freq_get_mhz()

Returns:

Frequency of counter used for timing in MHz.

group timing_api_soc

SoC specific Timing Measurement APIs.

Implements the necessary bits to support timing measurement using SoC specific timing measurement mechanism.

Functions

void soc_timing_init(void)

Initialize the timing subsystem on SoC.

Perform the necessary steps to initialize the timing subsystem.

See also

timing_init()

void soc_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.

See also

timing_start()

void soc_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.

See also

timing_stop()

timing_t soc_timing_counter_get(void)

Return timing counter.

See also

timing_counter_get()

Note

Not all SoCs have timing counters with 64 bit precision. It is possible to see this value “go backwards” due to internal rollover. Timing code must be prepared to address the rollover (with SoC dependent code, e.g. by casting to a uint32_t before subtraction) or by using soc_timing_cycles_get() which is required to understand the distinction.

Returns:

Timing counter.

uint64_t soc_timing_cycles_get(volatile timing_t *const start, volatile timing_t *const end)

Get number of cycles between start and end.

See also

timing_cycles_get()

Note

The raw numbers from counter need to be scaled to obtain actual number of cycles, or may roll over internally. This function computes a positive-definite interval between two returned cycle values.

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.

uint64_t soc_timing_freq_get(void)

Get frequency of counter used (in Hz).

See also

timing_freq_get()

Returns:

Frequency of counter used for timing in Hz.

uint64_t soc_timing_cycles_to_ns(uint64_t cycles)

Convert number of cycles into nanoseconds.

See also

timing_cycles_to_ns()

Parameters:

  • cycles – Number of cycles

Returns:

Converted time value

uint64_t soc_timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count)

Convert number of cycles into nanoseconds with averaging.

See also

timing_cycles_to_ns_avg()

Parameters:

  • cycles – Number of cycles

  • count – Times of accumulated cycles to average over

Returns:

Converted time value

uint32_t soc_timing_freq_get_mhz(void)

Get frequency of counter used (in MHz).

See also

timing_freq_get_mhz()

Returns:

Frequency of counter used for timing in MHz.

group timing_api_board

Board specific Timing Measurement APIs.

Implements the necessary bits to support timing measurement using board specific timing measurement mechanism.

Functions

void board_timing_init(void)

Initialize the timing subsystem.

Perform the necessary steps to initialize the timing subsystem.

See also

timing_init()

void board_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.

See also

timing_start()

void board_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.

See also

timing_stop()

timing_t board_timing_counter_get(void)

Return timing counter.

See also

timing_counter_get()

Note

Not all timing counters have 64 bit precision. It is possible to see this value “go backwards” due to internal rollover. Timing code must be prepared to address the rollover (with board dependent code, e.g. by casting to a uint32_t before subtraction) or by using board_timing_cycles_get() which is required to understand the distinction.

Returns:

Timing counter.

uint64_t board_timing_cycles_get(volatile timing_t *const start, volatile timing_t *const end)

Get number of cycles between start and end.

See also

timing_cycles_get()

Note

The raw numbers from counter need to be scaled to obtain actual number of cycles, or may roll over internally. This function computes a positive-definite interval between two returned cycle values.

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.

uint64_t board_timing_freq_get(void)

Get frequency of counter used (in Hz).

See also

timing_freq_get()

Returns:

Frequency of counter used for timing in Hz.

uint64_t board_timing_cycles_to_ns(uint64_t cycles)

Convert number of cycles into nanoseconds.

See also

timing_cycles_to_ns()

Parameters:

  • cycles – Number of cycles

Returns:

Converted time value

uint64_t board_timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count)

Convert number of cycles into nanoseconds with averaging.

See also

timing_cycles_to_ns_avg()

Parameters:

  • cycles – Number of cycles

  • count – Times of accumulated cycles to average over

Returns:

Converted time value

uint32_t board_timing_freq_get_mhz(void)

Get frequency of counter used (in MHz).

See also

timing_freq_get_mhz()

Returns:

Frequency of counter used for timing in MHz.