Executing Time Functions

.. _timing_functions:

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, :kconfig:option:CONFIG_TIMING_FUNCTIONS needs to be enabled.

Usage

To gather timing information:

1. Call :c:func:timing_init to initialize the timer.

2. Call :c:func:timing_start to signal the start of gathering of timing information. This usually starts the timer.

3. Call :c:func:timing_counter_get to mark the start of code execution.

4. Call :c:func:timing_counter_get to mark the end of code execution.

5. Call :c:func:timing_cycles_get to get the number of timer cycles between start and end of code execution.

6. Call :c:func: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 :c:func: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:

.. code-block:: c

#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

.. doxygengroup:: timing_api .. doxygengroup:: timing_api_arch .. doxygengroup:: timing_api_soc .. doxygengroup:: timing_api_board