Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
clock.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2014-2015 Wind River Systems, Inc.
3 * Copyright (c) 2025 Tenstorrent AI ULC
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
17
18#ifndef ZEPHYR_INCLUDE_SYS_CLOCK_H_
19#define ZEPHYR_INCLUDE_SYS_CLOCK_H_
20
21#include <zephyr/sys/dlist.h>
23#include <zephyr/sys/util.h>
24#include <zephyr/toolchain.h>
25#include <zephyr/types.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
35
45#ifdef CONFIG_TIMEOUT_64BIT
46typedef int64_t k_ticks_t;
47#else
49#endif
50
51#define K_TICKS_FOREVER ((k_ticks_t)(-1))
52
65typedef struct {
68
80#define K_TIMEOUT_EQ(a, b) ((a).ticks == (b).ticks)
81
83#define NSEC_PER_USEC 1000U
84
86#define NSEC_PER_MSEC 1000000U
87
89#define USEC_PER_MSEC 1000U
90
92#define MSEC_PER_SEC 1000U
93
95#define SEC_PER_MIN 60U
96
98#define SEC_PER_HOUR 3600U
99
101#define SEC_PER_DAY 86400U
102
104#define MIN_PER_HOUR 60U
105
107#define HOUR_PER_DAY 24U
108
110#define USEC_PER_SEC ((USEC_PER_MSEC) * (MSEC_PER_SEC))
111
113#define NSEC_PER_SEC ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC))
114
116
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/* Positive values are relative/delta timeouts and negative values are absolute
155 * timeouts, except -1 which is reserved for K_TIMEOUT_FOREVER. 0 is K_NO_WAIT,
156 * which is historically considered a relative timeout.
157 * K_TIMEOUT_FOREVER is not considered a relative timeout and neither is it
158 * considerd an absolute timeouts (so !Z_IS_TIMEOUT_RELATIVE() does not
159 * necessarily mean it is an absolute timeout if ticks == -1);
160 */
161#define Z_IS_TIMEOUT_RELATIVE(timeout) (((timeout).ticks) >= 0)
162#else
163#define Z_IS_TIMEOUT_RELATIVE(timeout) true
164#endif
165
166/* added tick needed to account for tick in progress */
167#define _TICK_ALIGN 1
168
169/* The minimum duration in ticks strictly greater than that of K_NO_WAIT */
170#define K_TICK_MIN ((k_ticks_t)1)
171
172/* The maximum duration in ticks strictly and semantically "less than" K_FOREVER */
173#define K_TICK_MAX ((k_ticks_t)(IS_ENABLED(CONFIG_TIMEOUT_64BIT) ? INT64_MAX : UINT32_MAX - 1))
174
176
177#ifndef CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME
178#if defined(CONFIG_SYS_CLOCK_EXISTS)
179#if CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC == 0
180#error "SYS_CLOCK_HW_CYCLES_PER_SEC must be non-zero!"
181#endif /* CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC == 0 */
182#endif /* CONFIG_SYS_CLOCK_EXISTS */
183#endif /* CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME */
184
185/* kernel clocks */
186
187/*
188 * We default to using 64-bit intermediates in timescale conversions,
189 * but if the HW timer cycles/sec, ticks/sec and ms/sec are all known
190 * to be nicely related, then we can cheat with 32 bits instead.
191 */
196
197#ifdef CONFIG_SYS_CLOCK_EXISTS
198
199#if defined(CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME) || \
200 (MSEC_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) || \
201 (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC)
202#define _NEED_PRECISE_TICK_MS_CONVERSION
203#endif
204
205#endif
206
211#define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES)
212
221
230
231#ifndef CONFIG_SYS_CLOCK_EXISTS
232#define sys_clock_tick_get() (0)
233#define sys_clock_tick_get_32() (0)
234#endif
235
236#ifdef CONFIG_SYS_CLOCK_EXISTS
237
248typedef struct {
251
269
284
296{
297 if (a.tick == b.tick) {
298 return 0;
299 }
300 return a.tick < b.tick ? -1 : 1;
301}
302
303#else
304
305/*
306 * When timers are configured out, timepoints can't relate to anything.
307 * The best we can do is to preserve whether or not they are derived from
308 * K_NO_WAIT. Anything else will translate back to K_FOREVER.
309 */
310typedef struct {
311 bool wait;
313
314static inline k_timepoint_t sys_timepoint_calc(k_timeout_t timeout)
315{
316 k_timepoint_t timepoint;
317
318 timepoint.wait = !K_TIMEOUT_EQ(timeout, Z_TIMEOUT_NO_WAIT);
319 return timepoint;
320}
321
322static inline k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint)
323{
324 return timepoint.wait ? Z_FOREVER : Z_TIMEOUT_NO_WAIT;
325}
326
327static inline int sys_timepoint_cmp(k_timepoint_t a, k_timepoint_t b)
328{
329 if (a.wait == b.wait) {
330 return 0;
331 }
332 return b.wait ? -1 : 1;
333}
334
335#endif
336
345static inline bool sys_timepoint_expired(k_timepoint_t timepoint)
346{
347 return K_TIMEOUT_EQ(sys_timepoint_timeout(timepoint), Z_TIMEOUT_NO_WAIT);
348}
349
351
356
366#define SYS_CLOCK_REALTIME 1
367
374#define SYS_CLOCK_MONOTONIC 4
375
382#define SYS_TIMER_ABSTIME 4
383
385/* forward declaration as workaround for time.h */
386struct timespec;
387
388/* Convert a POSIX clock (cast to int) to a sys_clock identifier */
389int sys_clock_from_clockid(int clock_id);
391
408__syscall void sys_clock_getrtoffset(struct timespec *tp);
409
418int sys_clock_gettime(int clock_id, struct timespec *tp);
419
429__syscall int sys_clock_settime(int clock_id, const struct timespec *tp);
430
456__syscall int sys_clock_nanosleep(int clock_id, int flags, const struct timespec *rqtp,
457 struct timespec *rmtp);
458
462
463#ifndef CONFIG_BOARD_UNIT_TESTING
464#include <zephyr/syscalls/clock.h>
465#endif
466
467#ifdef __cplusplus
468}
469#endif
470
471#endif /* ZEPHYR_INCLUDE_SYS_CLOCK_H_ */
int sys_clock_nanosleep(int clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)
Sleep for the specified amount of time with respect to the specified clock.
int sys_clock_settime(int clock_id, const struct timespec *tp)
Set the current time for the specified clock.
uint32_t sys_clock_tick_get_32(void)
Return the lower part of the current system tick count.
k_timepoint_t sys_timepoint_calc(k_timeout_t timeout)
Calculate a timepoint value.
int64_t sys_clock_tick_get(void)
Return the current system tick count.
k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint)
Remaining time to given timepoint.
static bool sys_timepoint_expired(k_timepoint_t timepoint)
Indicates if timepoint is expired.
Definition clock.h:345
int sys_clock_gettime(int clock_id, struct timespec *tp)
Get the current time from the specified clock.
uint32_t k_ticks_t
Tick precision used in timeout APIs.
Definition clock.h:48
#define K_TIMEOUT_EQ(a, b)
Compare timeouts for equality.
Definition clock.h:80
void sys_clock_getrtoffset(struct timespec *tp)
INTERNAL_HIDDEN.
static int sys_timepoint_cmp(k_timepoint_t a, k_timepoint_t b)
Compare two timepoint values.
Definition clock.h:295
flags
Definition parser.h:97
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT64_TYPE__ uint64_t
Definition stdint.h:91
__INT64_TYPE__ int64_t
Definition stdint.h:75
Kernel timeout type.
Definition clock.h:65
k_ticks_t ticks
Definition clock.h:66
Kernel timepoint type.
Definition clock.h:248
uint64_t tick
Definition clock.h:249
Definition _timespec.h:22
Misc utilities.
Macros to abstract toolchain specific capabilities.