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:
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 <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
startandend.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
cyclesinto 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
cyclesinto 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.
-
void timing_init(void)
- 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
-
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
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
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
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
startandend.See also
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
- Returns:
Frequency of counter used for timing in Hz.
-
uint64_t arch_timing_cycles_to_ns(uint64_t cycles)
Convert number of
cyclesinto nanoseconds.See also
- 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
cyclesinto nanoseconds with averaging.See also
- 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
- Returns:
Frequency of counter used for timing in MHz.
-
void arch_timing_init(void)
- 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
-
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
-
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_t soc_timing_counter_get(void)
Return timing counter.
See also
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
startandend.See also
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
- Returns:
Frequency of counter used for timing in Hz.
-
uint64_t soc_timing_cycles_to_ns(uint64_t cycles)
Convert number of
cyclesinto nanoseconds.See also
- 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
cyclesinto nanoseconds with averaging.See also
- 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
- Returns:
Frequency of counter used for timing in MHz.
-
void soc_timing_init(void)
- 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
-
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
-
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_t board_timing_counter_get(void)
Return timing counter.
See also
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
startandend.See also
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
- Returns:
Frequency of counter used for timing in Hz.
-
uint64_t board_timing_cycles_to_ns(uint64_t cycles)
Convert number of
cyclesinto nanoseconds.See also
- 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
cyclesinto nanoseconds with averaging.See also
- 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
- Returns:
Frequency of counter used for timing in MHz.
-
void board_timing_init(void)