1.. _timing_functions:
2
3Executing Time Functions
4########################
5
6The timing functions can be used to obtain execution time of
7a section of code to aid in analysis and optimization.
8
9Please note that the timing functions may use a different timer
10than the default kernel timer, where the timer being used is
11specified by architecture, SoC or board configuration.
12
13Configuration
14*************
15
16To allow using the timing functions, :kconfig:option:`CONFIG_TIMING_FUNCTIONS`
17needs to be enabled.
18
19Usage
20*****
21
22To gather timing information:
23
241. Call :c:func:`timing_init` to initialize the timer.
25
262. Call :c:func:`timing_start` to signal the start of gathering of
27   timing information. This usually starts the timer.
28
293. Call :c:func:`timing_counter_get` to mark the start of code
30   execution.
31
324. Call :c:func:`timing_counter_get` to mark the end of code
33   execution.
34
355. Call :c:func:`timing_cycles_get` to get the number of timer cycles
36   between start and end of code execution.
37
386. Call :c:func:`timing_cycles_to_ns` with total number of cycles
39   to convert number of cycles to nanoseconds.
40
417. Repeat from step 3 to gather timing information for other
42   blocks of code.
43
448. Call :c:func:`timing_stop` to signal the end of gathering of
45   timing information. This usually stops the timer.
46
47Example
48-------
49
50This shows an example on how to use the timing functions:
51
52.. code-block:: c
53
54   #include <zephyr/timing/timing.h>
55
56   void gather_timing(void)
57   {
58       timing_t start_time, end_time;
59       uint64_t total_cycles;
60       uint64_t total_ns;
61
62       timing_init();
63       timing_start();
64
65       start_time = timing_counter_get();
66
67       code_execution_to_be_measured();
68
69       end_time = timing_counter_get();
70
71       total_cycles = timing_cycles_get(&start_time, &end_time);
72       total_ns = timing_cycles_to_ns(total_cycles);
73
74       timing_stop();
75   }
76
77API documentation
78*****************
79
80.. doxygengroup:: timing_api
81