1 /*
2 * Copyright (c) 2014-2015 Wind River Systems, Inc.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Variables needed for system clock
10 *
11 *
12 * Declare variables used by both system timer device driver and kernel
13 * components that use timer functionality.
14 */
15
16 #ifndef ZEPHYR_INCLUDE_SYS_CLOCK_H_
17 #define ZEPHYR_INCLUDE_SYS_CLOCK_H_
18
19 #include <zephyr/sys/util.h>
20 #include <zephyr/sys/dlist.h>
21
22 #include <zephyr/toolchain.h>
23 #include <zephyr/types.h>
24
25 #include <zephyr/sys/time_units.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /**
32 * @addtogroup clock_apis
33 * @{
34 */
35
36 /**
37 * @brief Tick precision used in timeout APIs
38 *
39 * This type defines the word size of the timeout values used in
40 * k_timeout_t objects, and thus defines an upper bound on maximum
41 * timeout length (or equivalently minimum tick duration). Note that
42 * this does not affect the size of the system uptime counter, which
43 * is always a 64 bit count of ticks.
44 */
45 #ifdef CONFIG_TIMEOUT_64BIT
46 typedef int64_t k_ticks_t;
47 #else
48 typedef uint32_t k_ticks_t;
49 #endif
50
51 #define K_TICKS_FOREVER ((k_ticks_t) -1)
52
53 /**
54 * @brief Kernel timeout type
55 *
56 * Timeout arguments presented to kernel APIs are stored in this
57 * opaque type, which is capable of representing times in various
58 * formats and units. It should be constructed from application data
59 * using one of the macros defined for this purpose (e.g. `K_MSEC()`,
60 * `K_TIMEOUT_ABS_TICKS()`, etc...), or be one of the two constants
61 * K_NO_WAIT or K_FOREVER. Applications should not inspect the
62 * internal data once constructed. Timeout values may be compared for
63 * equality with the `K_TIMEOUT_EQ()` macro.
64 */
65 typedef struct {
66 k_ticks_t ticks;
67 } k_timeout_t;
68
69 /**
70 * @brief Compare timeouts for equality
71 *
72 * The k_timeout_t object is an opaque struct that should not be
73 * inspected by application code. This macro exists so that users can
74 * test timeout objects for equality with known constants
75 * (e.g. K_NO_WAIT and K_FOREVER) when implementing their own APIs in
76 * terms of Zephyr timeout constants.
77 *
78 * @return True if the timeout objects are identical
79 */
80 #define K_TIMEOUT_EQ(a, b) ((a).ticks == (b).ticks)
81
82 /** number of nanoseconds per microsecond */
83 #define NSEC_PER_USEC 1000U
84
85 /** number of nanoseconds per millisecond */
86 #define NSEC_PER_MSEC 1000000U
87
88 /** number of microseconds per millisecond */
89 #define USEC_PER_MSEC 1000U
90
91 /** number of milliseconds per second */
92 #define MSEC_PER_SEC 1000U
93
94 /** number of seconds per minute */
95 #define SEC_PER_MIN 60U
96
97 /** number of seconds per hour */
98 #define SEC_PER_HOUR 3600U
99
100 /** number of seconds per day */
101 #define SEC_PER_DAY 86400U
102
103 /** number of minutes per hour */
104 #define MIN_PER_HOUR 60U
105
106 /** number of hours per day */
107 #define HOUR_PER_DAY 24U
108
109 /** number of microseconds per second */
110 #define USEC_PER_SEC ((USEC_PER_MSEC) * (MSEC_PER_SEC))
111
112 /** number of nanoseconds per second */
113 #define NSEC_PER_SEC ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC))
114
115 /** @} */
116
117 /** @cond INTERNAL_HIDDEN */
118 #define Z_TIMEOUT_NO_WAIT_INIT {0}
119 #define Z_TIMEOUT_NO_WAIT ((k_timeout_t) Z_TIMEOUT_NO_WAIT_INIT)
120 #if defined(__cplusplus) && ((__cplusplus - 0) < 202002L)
121 #define Z_TIMEOUT_TICKS_INIT(t) { (t) }
122 #else
123 #define Z_TIMEOUT_TICKS_INIT(t) { .ticks = (t) }
124 #endif
125 #define Z_TIMEOUT_TICKS(t) ((k_timeout_t) Z_TIMEOUT_TICKS_INIT(t))
126 #define Z_FOREVER Z_TIMEOUT_TICKS(K_TICKS_FOREVER)
127
128 #ifdef CONFIG_TIMEOUT_64BIT
129 # define Z_TIMEOUT_MS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ms_to_ticks_ceil64(MAX(t, 0)))
130 # define Z_TIMEOUT_US(t) Z_TIMEOUT_TICKS((k_ticks_t)k_us_to_ticks_ceil64(MAX(t, 0)))
131 # define Z_TIMEOUT_NS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ns_to_ticks_ceil64(MAX(t, 0)))
132 # define Z_TIMEOUT_CYC(t) Z_TIMEOUT_TICKS((k_ticks_t)k_cyc_to_ticks_ceil64(MAX(t, 0)))
133 # define Z_TIMEOUT_MS_TICKS(t) ((k_ticks_t)k_ms_to_ticks_ceil64(MAX(t, 0)))
134 #else
135 # define Z_TIMEOUT_MS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ms_to_ticks_ceil32(MAX(t, 0)))
136 # define Z_TIMEOUT_US(t) Z_TIMEOUT_TICKS((k_ticks_t)k_us_to_ticks_ceil32(MAX(t, 0)))
137 # define Z_TIMEOUT_NS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ns_to_ticks_ceil32(MAX(t, 0)))
138 # define Z_TIMEOUT_CYC(t) Z_TIMEOUT_TICKS((k_ticks_t)k_cyc_to_ticks_ceil32(MAX(t, 0)))
139 # define Z_TIMEOUT_MS_TICKS(t) ((k_ticks_t)k_ms_to_ticks_ceil32(MAX(t, 0)))
140 #endif
141
142 /* Converts between absolute timeout expiration values (packed into
143 * the negative space below K_TICKS_FOREVER) and (non-negative) delta
144 * timeout values. If the result of Z_TICK_ABS(t) is >= 0, then the
145 * value was an absolute timeout with the returned expiration time.
146 * Note that this macro is bidirectional: Z_TICK_ABS(Z_TICK_ABS(t)) ==
147 * t for all inputs, and that the representation of K_TICKS_FOREVER is
148 * the same value in both spaces! Clever, huh?
149 */
150 #define Z_TICK_ABS(t) (K_TICKS_FOREVER - 1 - (t))
151
152 /* Test for relative timeout */
153 #if CONFIG_TIMEOUT_64BIT
154 #define Z_IS_TIMEOUT_RELATIVE(timeout) (Z_TICK_ABS((timeout).ticks) < 0)
155 #else
156 #define Z_IS_TIMEOUT_RELATIVE(timeout) true
157 #endif
158
159 /* added tick needed to account for tick in progress */
160 #define _TICK_ALIGN 1
161
162 /** @endcond */
163
164 #ifndef CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME
165 #if defined(CONFIG_SYS_CLOCK_EXISTS) && \
166 (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC == 0)
167 #error "SYS_CLOCK_HW_CYCLES_PER_SEC must be non-zero!"
168 #endif
169 #endif /* CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME */
170
171 /* kernel clocks */
172
173 /*
174 * We default to using 64-bit intermediates in timescale conversions,
175 * but if the HW timer cycles/sec, ticks/sec and ms/sec are all known
176 * to be nicely related, then we can cheat with 32 bits instead.
177 */
178 /**
179 * @addtogroup clock_apis
180 * @{
181 */
182
183 #ifdef CONFIG_SYS_CLOCK_EXISTS
184
185 #if defined(CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME) || \
186 (MSEC_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) || \
187 (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC)
188 #define _NEED_PRECISE_TICK_MS_CONVERSION
189 #endif
190
191 #endif
192
193 /**
194 * SYS_CLOCK_HW_CYCLES_TO_NS_AVG converts CPU clock cycles to nanoseconds
195 * and calculates the average cycle time
196 */
197 #define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) \
198 (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES)
199
200 /**
201 *
202 * @brief Return the lower part of the current system tick count
203 *
204 * @return the current system tick count
205 *
206 */
207 uint32_t sys_clock_tick_get_32(void);
208
209 /**
210 *
211 * @brief Return the current system tick count
212 *
213 * @return the current system tick count
214 *
215 */
216 int64_t sys_clock_tick_get(void);
217
218 #ifndef CONFIG_SYS_CLOCK_EXISTS
219 #define sys_clock_tick_get() (0)
220 #define sys_clock_tick_get_32() (0)
221 #endif
222
223 #ifdef CONFIG_SYS_CLOCK_EXISTS
224
225 /**
226 * @brief Kernel timepoint type
227 *
228 * Absolute timepoints are stored in this opaque type.
229 * It is best not to inspect its content directly.
230 *
231 * @see sys_timepoint_calc()
232 * @see sys_timepoint_timeout()
233 * @see sys_timepoint_expired()
234 */
235 typedef struct { uint64_t tick; } k_timepoint_t;
236
237 /**
238 * @brief Calculate a timepoint value
239 *
240 * Returns a timepoint corresponding to the expiration (relative to an
241 * unlocked "now"!) of a timeout object. When used correctly, this should
242 * be called once, synchronously with the user passing a new timeout value.
243 * It should not be used iteratively to adjust a timeout (see
244 * `sys_timepoint_timeout()` for that purpose).
245 *
246 * @param timeout Timeout value relative to current time (may also be
247 * `K_FOREVER` or `K_NO_WAIT`).
248 * @retval Timepoint value corresponding to given timeout
249 *
250 * @see sys_timepoint_timeout()
251 * @see sys_timepoint_expired()
252 */
253 k_timepoint_t sys_timepoint_calc(k_timeout_t timeout);
254
255 /**
256 * @brief Remaining time to given timepoint
257 *
258 * Returns the timeout interval between current time and provided timepoint.
259 * If the timepoint is now in the past or if it was created with `K_NO_WAIT`
260 * then `K_NO_WAIT` is returned. If it was created with `K_FOREVER` then
261 * `K_FOREVER` is returned.
262 *
263 * @param timepoint Timepoint for which a timeout value is wanted.
264 * @retval Corresponding timeout value.
265 *
266 * @see sys_timepoint_calc()
267 */
268 k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint);
269
270 /**
271 * @brief Compare two timepoint values.
272 *
273 * This function is used to compare two timepoint values.
274 *
275 * @param a Timepoint to compare
276 * @param b Timepoint to compare against.
277 * @return zero if both timepoints are the same. Negative value if timepoint @a a is before
278 * timepoint @a b, positive otherwise.
279 */
sys_timepoint_cmp(k_timepoint_t a,k_timepoint_t b)280 static inline int sys_timepoint_cmp(k_timepoint_t a, k_timepoint_t b)
281 {
282 if (a.tick == b.tick) {
283 return 0;
284 }
285 return a.tick < b.tick ? -1 : 1;
286 }
287
288 #else
289
290 /*
291 * When timers are configured out, timepoints can't relate to anything.
292 * The best we can do is to preserve whether or not they are derived from
293 * K_NO_WAIT. Anything else will translate back to K_FOREVER.
294 */
295 typedef struct { bool wait; } k_timepoint_t;
296
sys_timepoint_calc(k_timeout_t timeout)297 static inline k_timepoint_t sys_timepoint_calc(k_timeout_t timeout)
298 {
299 k_timepoint_t timepoint;
300
301 timepoint.wait = !K_TIMEOUT_EQ(timeout, Z_TIMEOUT_NO_WAIT);
302 return timepoint;
303 }
304
sys_timepoint_timeout(k_timepoint_t timepoint)305 static inline k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint)
306 {
307 return timepoint.wait ? Z_FOREVER : Z_TIMEOUT_NO_WAIT;
308 }
309
sys_timepoint_cmp(k_timepoint_t a,k_timepoint_t b)310 static inline int sys_timepoint_cmp(k_timepoint_t a, k_timepoint_t b)
311 {
312 if (a.wait == b.wait) {
313 return 0;
314 }
315 return b.wait ? -1 : 1;
316 }
317
318 #endif
319
320 /**
321 * @brief Indicates if timepoint is expired
322 *
323 * @param timepoint Timepoint to evaluate
324 * @retval true if the timepoint is in the past, false otherwise
325 *
326 * @see sys_timepoint_calc()
327 */
sys_timepoint_expired(k_timepoint_t timepoint)328 static inline bool sys_timepoint_expired(k_timepoint_t timepoint)
329 {
330 return K_TIMEOUT_EQ(sys_timepoint_timeout(timepoint), Z_TIMEOUT_NO_WAIT);
331 }
332
333 /** @} */
334
335 #ifdef __cplusplus
336 }
337 #endif
338
339 #endif /* ZEPHYR_INCLUDE_SYS_CLOCK_H_ */
340
