Line data Source code
1 0 : /*
2 : * Copyright (c) 2020 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_TIMING_TIMING_H_
8 : #define ZEPHYR_INCLUDE_TIMING_TIMING_H_
9 :
10 : #include <zephyr/arch/arch_interface.h>
11 : #include <zephyr/timing/types.h>
12 :
13 : #ifdef __cplusplus
14 : extern "C" {
15 : #endif
16 :
17 : /**
18 : * @brief Timing Measurement APIs
19 : * @defgroup timing_api Timing Measurement APIs
20 : * @ingroup os_services
21 : *
22 : * The timing measurement APIs can be used to obtain execution
23 : * time of a section of code to aid in analysis and optimization.
24 : *
25 : * Please note that the timing functions may use a different timer
26 : * than the default kernel timer, where the timer being used is
27 : * specified by architecture, SoC or board configuration.
28 : */
29 :
30 : /**
31 : * @brief SoC specific Timing Measurement APIs
32 : * @defgroup timing_api_soc SoC specific Timing Measurement APIs
33 : * @ingroup timing_api
34 : *
35 : * Implements the necessary bits to support timing measurement
36 : * using SoC specific timing measurement mechanism.
37 : *
38 : * @{
39 : */
40 :
41 : /**
42 : * @brief Initialize the timing subsystem on SoC.
43 : *
44 : * Perform the necessary steps to initialize the timing subsystem.
45 : *
46 : * @see timing_init()
47 : */
48 1 : void soc_timing_init(void);
49 :
50 : /**
51 : * @brief Signal the start of the timing information gathering.
52 : *
53 : * Signal to the timing subsystem that timing information
54 : * will be gathered from this point forward.
55 : *
56 : * @see timing_start()
57 : */
58 1 : void soc_timing_start(void);
59 :
60 : /**
61 : * @brief Signal the end of the timing information gathering.
62 : *
63 : * Signal to the timing subsystem that timing information
64 : * is no longer being gathered from this point forward.
65 : *
66 : * @see timing_stop()
67 : */
68 1 : void soc_timing_stop(void);
69 :
70 : /**
71 : * @brief Return timing counter.
72 : *
73 : * @note Not all SoCs have timing counters with 64 bit precision. It
74 : * is possible to see this value "go backwards" due to internal
75 : * rollover. Timing code must be prepared to address the rollover
76 : * (with SoC dependent code, e.g. by casting to a uint32_t before
77 : * subtraction) or by using soc_timing_cycles_get() which is required
78 : * to understand the distinction.
79 : *
80 : * @return Timing counter.
81 : *
82 : * @see timing_counter_get()
83 : */
84 1 : timing_t soc_timing_counter_get(void);
85 :
86 : /**
87 : * @brief Get number of cycles between @p start and @p end.
88 : *
89 : * @note The raw numbers from counter need to be scaled to
90 : * obtain actual number of cycles, or may roll over internally.
91 : * This function computes a positive-definite interval between two
92 : * returned cycle values.
93 : *
94 : * @param start Pointer to counter at start of a measured execution.
95 : * @param end Pointer to counter at stop of a measured execution.
96 : * @return Number of cycles between start and end.
97 : *
98 : * @see timing_cycles_get()
99 : */
100 1 : uint64_t soc_timing_cycles_get(volatile timing_t *const start,
101 : volatile timing_t *const end);
102 :
103 : /**
104 : * @brief Get frequency of counter used (in Hz).
105 : *
106 : * @return Frequency of counter used for timing in Hz.
107 : *
108 : * @see timing_freq_get()
109 : */
110 1 : uint64_t soc_timing_freq_get(void);
111 :
112 : /**
113 : * @brief Convert number of @p cycles into nanoseconds.
114 : *
115 : * @param cycles Number of cycles
116 : * @return Converted time value
117 : *
118 : * @see timing_cycles_to_ns()
119 : */
120 1 : uint64_t soc_timing_cycles_to_ns(uint64_t cycles);
121 :
122 : /**
123 : * @brief Convert number of @p cycles into nanoseconds with averaging.
124 : *
125 : * @param cycles Number of cycles
126 : * @param count Times of accumulated cycles to average over
127 : * @return Converted time value
128 : *
129 : * @see timing_cycles_to_ns_avg()
130 : */
131 1 : uint64_t soc_timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count);
132 :
133 : /**
134 : * @brief Get frequency of counter used (in MHz).
135 : *
136 : * @return Frequency of counter used for timing in MHz.
137 : *
138 : * @see timing_freq_get_mhz()
139 : */
140 1 : uint32_t soc_timing_freq_get_mhz(void);
141 :
142 : /**
143 : * @}
144 : */
145 :
146 : /**
147 : * @brief Board specific Timing Measurement APIs
148 : * @defgroup timing_api_board Board specific Timing Measurement APIs
149 : * @ingroup timing_api
150 : *
151 : * Implements the necessary bits to support timing measurement
152 : * using board specific timing measurement mechanism.
153 : *
154 : * @{
155 : */
156 :
157 : /**
158 : * @brief Initialize the timing subsystem.
159 : *
160 : * Perform the necessary steps to initialize the timing subsystem.
161 : *
162 : * @see timing_init()
163 : */
164 1 : void board_timing_init(void);
165 :
166 : /**
167 : * @brief Signal the start of the timing information gathering.
168 : *
169 : * Signal to the timing subsystem that timing information
170 : * will be gathered from this point forward.
171 : *
172 : * @see timing_start()
173 : */
174 1 : void board_timing_start(void);
175 :
176 : /**
177 : * @brief Signal the end of the timing information gathering.
178 : *
179 : * Signal to the timing subsystem that timing information
180 : * is no longer being gathered from this point forward.
181 : *
182 : * @see timing_stop()
183 : */
184 1 : void board_timing_stop(void);
185 :
186 : /**
187 : * @brief Return timing counter.
188 : *
189 : * @note Not all timing counters have 64 bit precision. It is
190 : * possible to see this value "go backwards" due to internal
191 : * rollover. Timing code must be prepared to address the rollover
192 : * (with board dependent code, e.g. by casting to a uint32_t before
193 : * subtraction) or by using board_timing_cycles_get() which is required
194 : * to understand the distinction.
195 : *
196 : * @return Timing counter.
197 : *
198 : * @see timing_counter_get()
199 : */
200 1 : timing_t board_timing_counter_get(void);
201 :
202 : /**
203 : * @brief Get number of cycles between @p start and @p end.
204 : *
205 : * @note The raw numbers from counter need to be scaled to
206 : * obtain actual number of cycles, or may roll over internally.
207 : * This function computes a positive-definite interval between two
208 : * returned cycle values.
209 : *
210 : * @param start Pointer to counter at start of a measured execution.
211 : * @param end Pointer to counter at stop of a measured execution.
212 : * @return Number of cycles between start and end.
213 : *
214 : * @see timing_cycles_get()
215 : */
216 1 : uint64_t board_timing_cycles_get(volatile timing_t *const start,
217 : volatile timing_t *const end);
218 :
219 : /**
220 : * @brief Get frequency of counter used (in Hz).
221 : *
222 : * @return Frequency of counter used for timing in Hz.
223 : *
224 : * @see timing_freq_get()
225 : */
226 1 : uint64_t board_timing_freq_get(void);
227 :
228 : /**
229 : * @brief Convert number of @p cycles into nanoseconds.
230 : *
231 : * @param cycles Number of cycles
232 : * @return Converted time value
233 : *
234 : * @see timing_cycles_to_ns()
235 : */
236 1 : uint64_t board_timing_cycles_to_ns(uint64_t cycles);
237 :
238 : /**
239 : * @brief Convert number of @p cycles into nanoseconds with averaging.
240 : *
241 : * @param cycles Number of cycles
242 : * @param count Times of accumulated cycles to average over
243 : * @return Converted time value
244 : *
245 : * @see timing_cycles_to_ns_avg()
246 : */
247 1 : uint64_t board_timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count);
248 :
249 : /**
250 : * @brief Get frequency of counter used (in MHz).
251 : *
252 : * @return Frequency of counter used for timing in MHz.
253 : *
254 : * @see timing_freq_get_mhz()
255 : */
256 1 : uint32_t board_timing_freq_get_mhz(void);
257 :
258 : /**
259 : * @}
260 : */
261 :
262 : /**
263 : * @addtogroup timing_api
264 : * @{
265 : */
266 :
267 : #ifdef CONFIG_TIMING_FUNCTIONS
268 :
269 : /**
270 : * @brief Initialize the timing subsystem.
271 : *
272 : * Perform the necessary steps to initialize the timing subsystem.
273 : */
274 1 : void timing_init(void);
275 :
276 : /**
277 : * @brief Signal the start of the timing information gathering.
278 : *
279 : * Signal to the timing subsystem that timing information
280 : * will be gathered from this point forward.
281 : */
282 1 : void timing_start(void);
283 :
284 : /**
285 : * @brief Signal the end of the timing information gathering.
286 : *
287 : * Signal to the timing subsystem that timing information
288 : * is no longer being gathered from this point forward.
289 : */
290 1 : void timing_stop(void);
291 :
292 : /**
293 : * @brief Return timing counter.
294 : *
295 : * @return Timing counter.
296 : */
297 1 : static inline timing_t timing_counter_get(void)
298 : {
299 : #if defined(CONFIG_BOARD_HAS_TIMING_FUNCTIONS)
300 : return board_timing_counter_get();
301 : #elif defined(CONFIG_SOC_HAS_TIMING_FUNCTIONS)
302 : return soc_timing_counter_get();
303 : #else
304 : return arch_timing_counter_get();
305 : #endif
306 : }
307 :
308 : /**
309 : * @brief Get number of cycles between @p start and @p end.
310 : *
311 : * For some architectures or SoCs, the raw numbers from counter
312 : * need to be scaled to obtain actual number of cycles.
313 : *
314 : * @param start Pointer to counter at start of a measured execution.
315 : * @param end Pointer to counter at stop of a measured execution.
316 : * @return Number of cycles between start and end.
317 : */
318 1 : static inline uint64_t timing_cycles_get(volatile timing_t *const start,
319 : volatile timing_t *const end)
320 : {
321 : #if defined(CONFIG_BOARD_HAS_TIMING_FUNCTIONS)
322 : return board_timing_cycles_get(start, end);
323 : #elif defined(CONFIG_SOC_HAS_TIMING_FUNCTIONS)
324 : return soc_timing_cycles_get(start, end);
325 : #else
326 : return arch_timing_cycles_get(start, end);
327 : #endif
328 : }
329 :
330 : /**
331 : * @brief Get frequency of counter used (in Hz).
332 : *
333 : * @return Frequency of counter used for timing in Hz.
334 : */
335 1 : static inline uint64_t timing_freq_get(void)
336 : {
337 : #if defined(CONFIG_BOARD_HAS_TIMING_FUNCTIONS)
338 : return board_timing_freq_get();
339 : #elif defined(CONFIG_SOC_HAS_TIMING_FUNCTIONS)
340 : return soc_timing_freq_get();
341 : #else
342 : return arch_timing_freq_get();
343 : #endif
344 : }
345 :
346 : /**
347 : * @brief Convert number of @p cycles into nanoseconds.
348 : *
349 : * @param cycles Number of cycles
350 : * @return Converted time value
351 : */
352 1 : static inline uint64_t timing_cycles_to_ns(uint64_t cycles)
353 : {
354 : #if defined(CONFIG_BOARD_HAS_TIMING_FUNCTIONS)
355 : return board_timing_cycles_to_ns(cycles);
356 : #elif defined(CONFIG_SOC_HAS_TIMING_FUNCTIONS)
357 : return soc_timing_cycles_to_ns(cycles);
358 : #else
359 : return arch_timing_cycles_to_ns(cycles);
360 : #endif
361 : }
362 :
363 : /**
364 : * @brief Convert number of @p cycles into nanoseconds with averaging.
365 : *
366 : * @param cycles Number of cycles
367 : * @param count Times of accumulated cycles to average over
368 : * @return Converted time value
369 : */
370 1 : static inline uint64_t timing_cycles_to_ns_avg(uint64_t cycles, uint32_t count)
371 : {
372 : #if defined(CONFIG_BOARD_HAS_TIMING_FUNCTIONS)
373 : return board_timing_cycles_to_ns_avg(cycles, count);
374 : #elif defined(CONFIG_SOC_HAS_TIMING_FUNCTIONS)
375 : return soc_timing_cycles_to_ns_avg(cycles, count);
376 : #else
377 : return arch_timing_cycles_to_ns_avg(cycles, count);
378 : #endif
379 : }
380 :
381 : /**
382 : * @brief Get frequency of counter used (in MHz).
383 : *
384 : * @return Frequency of counter used for timing in MHz.
385 : */
386 1 : static inline uint32_t timing_freq_get_mhz(void)
387 : {
388 : #if defined(CONFIG_BOARD_HAS_TIMING_FUNCTIONS)
389 : return board_timing_freq_get_mhz();
390 : #elif defined(CONFIG_SOC_HAS_TIMING_FUNCTIONS)
391 : return soc_timing_freq_get_mhz();
392 : #else
393 : return arch_timing_freq_get_mhz();
394 : #endif
395 : }
396 :
397 : #endif /* CONFIG_TIMING_FUNCTIONS */
398 :
399 : /**
400 : * @}
401 : */
402 :
403 : #ifdef __cplusplus
404 : }
405 : #endif
406 :
407 : #endif /* ZEPHYR_INCLUDE_TIMING_TIMING_H_ */
|
