/* * Copyright (c) 2014-2015 Wind River Systems, Inc. * Copyright (c) 2025 Tenstorrent AI ULC * * SPDX-License-Identifier: Apache-2.0 */ /** * @file * @brief System clock APIs * * Declare variables used by both system timer device driver and kernel * components that use timer functionality. * * APIs for getting, setting, and sleeping with respect to system clocks. */ #ifndef ZEPHYR_INCLUDE_SYS_CLOCK_H_ #define ZEPHYR_INCLUDE_SYS_CLOCK_H_ #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * @addtogroup clock_apis * @{ */ /** * @brief Tick precision used in timeout APIs * * This type defines the word size of the timeout values used in * k_timeout_t objects, and thus defines an upper bound on maximum * timeout length (or equivalently minimum tick duration). Note that * this does not affect the size of the system uptime counter, which * is always a 64 bit count of ticks. */ #ifdef CONFIG_TIMEOUT_64BIT typedef int64_t k_ticks_t; #else typedef uint32_t k_ticks_t; #endif #define K_TICKS_FOREVER ((k_ticks_t)(-1)) /** * @brief Kernel timeout type * * Timeout arguments presented to kernel APIs are stored in this * opaque type, which is capable of representing times in various * formats and units. It should be constructed from application data * using one of the macros defined for this purpose (e.g. `K_MSEC()`, * `K_TIMEOUT_ABS_TICKS()`, etc...), or be one of the two constants * K_NO_WAIT or K_FOREVER. Applications should not inspect the * internal data once constructed. Timeout values may be compared for * equality with the `K_TIMEOUT_EQ()` macro. */ typedef struct { k_ticks_t ticks; } k_timeout_t; /** * @brief Compare timeouts for equality * * The k_timeout_t object is an opaque struct that should not be * inspected by application code. This macro exists so that users can * test timeout objects for equality with known constants * (e.g. K_NO_WAIT and K_FOREVER) when implementing their own APIs in * terms of Zephyr timeout constants. * * @return True if the timeout objects are identical */ #define K_TIMEOUT_EQ(a, b) ((a).ticks == (b).ticks) /** number of nanoseconds per microsecond */ #define NSEC_PER_USEC 1000U /** number of nanoseconds per millisecond */ #define NSEC_PER_MSEC 1000000U /** number of microseconds per millisecond */ #define USEC_PER_MSEC 1000U /** number of milliseconds per second */ #define MSEC_PER_SEC 1000U /** number of seconds per minute */ #define SEC_PER_MIN 60U /** number of seconds per hour */ #define SEC_PER_HOUR 3600U /** number of seconds per day */ #define SEC_PER_DAY 86400U /** number of minutes per hour */ #define MIN_PER_HOUR 60U /** number of hours per day */ #define HOUR_PER_DAY 24U /** number of microseconds per second */ #define USEC_PER_SEC ((USEC_PER_MSEC) * (MSEC_PER_SEC)) /** number of nanoseconds per second */ #define NSEC_PER_SEC ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC)) /** @} */ /** @cond INTERNAL_HIDDEN */ #define Z_TIMEOUT_NO_WAIT_INIT {0} #define Z_TIMEOUT_NO_WAIT ((k_timeout_t)Z_TIMEOUT_NO_WAIT_INIT) #if defined(__cplusplus) && ((__cplusplus - 0) < 202002L) #define Z_TIMEOUT_TICKS_INIT(t) {(t)} #else #define Z_TIMEOUT_TICKS_INIT(t) {.ticks = (t)} #endif #define Z_TIMEOUT_TICKS(t) ((k_timeout_t)Z_TIMEOUT_TICKS_INIT(t)) #define Z_FOREVER Z_TIMEOUT_TICKS(K_TICKS_FOREVER) #ifdef CONFIG_TIMEOUT_64BIT #define Z_TIMEOUT_MS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ms_to_ticks_ceil64(MAX(t, 0))) #define Z_TIMEOUT_US(t) Z_TIMEOUT_TICKS((k_ticks_t)k_us_to_ticks_ceil64(MAX(t, 0))) #define Z_TIMEOUT_NS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ns_to_ticks_ceil64(MAX(t, 0))) #define Z_TIMEOUT_CYC(t) Z_TIMEOUT_TICKS((k_ticks_t)k_cyc_to_ticks_ceil64(MAX(t, 0))) #define Z_TIMEOUT_MS_TICKS(t) ((k_ticks_t)k_ms_to_ticks_ceil64(MAX(t, 0))) #else #define Z_TIMEOUT_MS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ms_to_ticks_ceil32(MAX(t, 0))) #define Z_TIMEOUT_US(t) Z_TIMEOUT_TICKS((k_ticks_t)k_us_to_ticks_ceil32(MAX(t, 0))) #define Z_TIMEOUT_NS(t) Z_TIMEOUT_TICKS((k_ticks_t)k_ns_to_ticks_ceil32(MAX(t, 0))) #define Z_TIMEOUT_CYC(t) Z_TIMEOUT_TICKS((k_ticks_t)k_cyc_to_ticks_ceil32(MAX(t, 0))) #define Z_TIMEOUT_MS_TICKS(t) ((k_ticks_t)k_ms_to_ticks_ceil32(MAX(t, 0))) #endif /* Converts between absolute timeout expiration values (packed into * the negative space below K_TICKS_FOREVER) and (non-negative) delta * timeout values. If the result of Z_TICK_ABS(t) is >= 0, then the * value was an absolute timeout with the returned expiration time. * Note that this macro is bidirectional: Z_TICK_ABS(Z_TICK_ABS(t)) == * t for all inputs, and that the representation of K_TICKS_FOREVER is * the same value in both spaces! Clever, huh? */ #define Z_TICK_ABS(t) (K_TICKS_FOREVER - 1 - (t)) /* Test for relative timeout */ #if CONFIG_TIMEOUT_64BIT /* Positive values are relative/delta timeouts and negative values are absolute * timeouts, except -1 which is reserved for K_TIMEOUT_FOREVER. 0 is K_NO_WAIT, * which is historically considered a relative timeout. * K_TIMEOUT_FOREVER is not considered a relative timeout and neither is it * considerd an absolute timeouts (so !Z_IS_TIMEOUT_RELATIVE() does not * necessarily mean it is an absolute timeout if ticks == -1); */ #define Z_IS_TIMEOUT_RELATIVE(timeout) (((timeout).ticks) >= 0) #else #define Z_IS_TIMEOUT_RELATIVE(timeout) true #endif /* added tick needed to account for tick in progress */ #define _TICK_ALIGN 1 /* The minimum duration in ticks strictly greater than that of K_NO_WAIT */ #define K_TICK_MIN ((k_ticks_t)1) /* The maximum duration in ticks strictly and semantically "less than" K_FOREVER */ #define K_TICK_MAX ((k_ticks_t)(IS_ENABLED(CONFIG_TIMEOUT_64BIT) ? INT64_MAX : UINT32_MAX - 1)) /** @endcond */ #ifndef CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME #if defined(CONFIG_SYS_CLOCK_EXISTS) #if CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC == 0 #error "SYS_CLOCK_HW_CYCLES_PER_SEC must be non-zero!" #endif /* CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC == 0 */ #endif /* CONFIG_SYS_CLOCK_EXISTS */ #endif /* CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME */ /* kernel clocks */ /* * We default to using 64-bit intermediates in timescale conversions, * but if the HW timer cycles/sec, ticks/sec and ms/sec are all known * to be nicely related, then we can cheat with 32 bits instead. */ /** * @addtogroup clock_apis * @{ */ #ifdef CONFIG_SYS_CLOCK_EXISTS #if defined(CONFIG_TIMER_READS_ITS_FREQUENCY_AT_RUNTIME) || \ (MSEC_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) || \ (CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC % CONFIG_SYS_CLOCK_TICKS_PER_SEC) #define _NEED_PRECISE_TICK_MS_CONVERSION #endif #endif /** * SYS_CLOCK_HW_CYCLES_TO_NS_AVG converts CPU clock cycles to nanoseconds * and calculates the average cycle time */ #define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES) /** * * @brief Return the lower part of the current system tick count * * @return the current system tick count * */ uint32_t sys_clock_tick_get_32(void); /** * * @brief Return the current system tick count * * @return the current system tick count * */ int64_t sys_clock_tick_get(void); #ifndef CONFIG_SYS_CLOCK_EXISTS #define sys_clock_tick_get() (0) #define sys_clock_tick_get_32() (0) #endif #ifdef CONFIG_SYS_CLOCK_EXISTS /** * @brief Kernel timepoint type * * Absolute timepoints are stored in this opaque type. * It is best not to inspect its content directly. * * @see sys_timepoint_calc() * @see sys_timepoint_timeout() * @see sys_timepoint_expired() */ typedef struct { uint64_t tick; } k_timepoint_t; /** * @brief Calculate a timepoint value * * Returns a timepoint corresponding to the expiration (relative to an * unlocked "now"!) of a timeout object. When used correctly, this should * be called once, synchronously with the user passing a new timeout value. * It should not be used iteratively to adjust a timeout (see * `sys_timepoint_timeout()` for that purpose). * * @param timeout Timeout value relative to current time (may also be * `K_FOREVER` or `K_NO_WAIT`). * @return Timepoint value corresponding to given timeout * * @see sys_timepoint_timeout() * @see sys_timepoint_expired() */ k_timepoint_t sys_timepoint_calc(k_timeout_t timeout); /** * @brief Remaining time to given timepoint * * Returns the timeout interval between current time and provided timepoint. * If the timepoint is now in the past or if it was created with `K_NO_WAIT` * then `K_NO_WAIT` is returned. If it was created with `K_FOREVER` then * `K_FOREVER` is returned. * * @param timepoint Timepoint for which a timeout value is wanted. * @return Corresponding timeout value. * * @see sys_timepoint_calc() */ k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint); /** * @brief Compare two timepoint values. * * This function is used to compare two timepoint values. * * @param a Timepoint to compare * @param b Timepoint to compare against. * @return zero if both timepoints are the same. Negative value if timepoint @a a is before * timepoint @a b, positive otherwise. */ static inline int sys_timepoint_cmp(k_timepoint_t a, k_timepoint_t b) { if (a.tick == b.tick) { return 0; } return a.tick < b.tick ? -1 : 1; } #else /* * When timers are configured out, timepoints can't relate to anything. * The best we can do is to preserve whether or not they are derived from * K_NO_WAIT. Anything else will translate back to K_FOREVER. */ typedef struct { bool wait; } k_timepoint_t; static inline k_timepoint_t sys_timepoint_calc(k_timeout_t timeout) { k_timepoint_t timepoint; timepoint.wait = !K_TIMEOUT_EQ(timeout, Z_TIMEOUT_NO_WAIT); return timepoint; } static inline k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint) { return timepoint.wait ? Z_FOREVER : Z_TIMEOUT_NO_WAIT; } static inline int sys_timepoint_cmp(k_timepoint_t a, k_timepoint_t b) { if (a.wait == b.wait) { return 0; } return b.wait ? -1 : 1; } #endif /** * @brief Indicates if timepoint is expired * * @param timepoint Timepoint to evaluate * @retval true if the timepoint is in the past, false otherwise * * @see sys_timepoint_calc() */ static inline bool sys_timepoint_expired(k_timepoint_t timepoint) { return K_TIMEOUT_EQ(sys_timepoint_timeout(timepoint), Z_TIMEOUT_NO_WAIT); } /** @} */ /** * @addtogroup clock_apis * @{ */ /** * @brief The real-time clock (i.e. "wall clock") * * This clock is used to measure time since the epoch (1970-01-01 00:00:00 UTC). * * It is not a steady clock; i.e. it may be adjusted for a number of reasons from initialization * of a hardware real-time-clock, to network-time synchronization, to manual adjustment from the * application. */ #define SYS_CLOCK_REALTIME 1 /** * @brief The monotonic clock * * This steady clock is used to measure time since the system booted. Time from this clock is * always monotonically increasing. */ #define SYS_CLOCK_MONOTONIC 4 /** * @brief The flag used for specifying absolute timeouts * * This flag may be passed to @ref sys_clock_nanosleep to indicate the requested timeout is an * absolute time with respect to the specified clock. */ #define SYS_TIMER_ABSTIME 4 /** @cond INTERNAL_HIDDEN */ /* forward declaration as workaround for time.h */ struct timespec; /* Convert a POSIX clock (cast to int) to a sys_clock identifier */ int sys_clock_from_clockid(int clock_id); /** INTERNAL_HIDDEN @endcond */ /** * @brief Get the offset @ref SYS_CLOCK_REALTIME with respect to @ref SYS_CLOCK_MONOTONIC * * The "wall clock" (i.e. @ref SYS_CLOCK_REALTIME) depends on a base time that is set by the * system. The base time may be updated for a number of reasons, such as initialization of a * hardware real-time-clock (RTC), network time protocol (NTP) synchronization, or manual * adjustment by the application. * * This function retrieves the current time offset, as a `timespec` object, for * @ref SYS_CLOCK_REALTIME, with respect to @ref SYS_CLOCK_MONOTONIC, and writes it to the * provided memory location pointed-to by @a tp. * * @note This function may assert if @a tp is NULL. * * @param tp Pointer to memory where time will be written. */ __syscall void sys_clock_getrtoffset(struct timespec *tp); /** * @brief Get the current time from the specified clock * * @param clock_id The clock from which to query time. * @param tp Pointer to memory where time will be written. * @retval 0 on success. * @retval -EINVAL when an invalid @a clock_id is specified. */ int sys_clock_gettime(int clock_id, struct timespec *tp); /** * @brief Set the current time for the specified clock * * @param clock_id The clock for which the time should be set. * @param tp Pointer to memory specifying the desired time. * @retval 0 on success. * @retval -EINVAL when an invalid @a clock_id is specified or when @a tp contains nanoseconds * outside of the range `[0, 999999999]`. */ __syscall int sys_clock_settime(int clock_id, const struct timespec *tp); /** * @brief Sleep for the specified amount of time with respect to the specified clock. * * This function will cause the calling thread to sleep either * - until the absolute time specified by @a rqtp (if @a flags includes @ref SYS_TIMER_ABSTIME), or * - until the relative time specified by @a rqtp (if @a flags does not include * @ref SYS_TIMER_ABSTIME). * * The accepted values for @a clock_id include * - @ref SYS_CLOCK_REALTIME * - @ref SYS_CLOCK_MONOTONIC * * If @a rmtp is not NULL, and the thread is awoken prior to the time specified by @a rqtp, then * any remaining time will be written to @a rmtp. If the thread has slept for at least the time * specified by @a rqtp, then @a rmtp will be set to zero. * * @param clock_id The clock to by which to sleep. * @param flags Flags to modify the behavior of the sleep operation. * @param rqtp Pointer to the requested time to sleep. * @param rmtp Pointer to memory into which to copy the remaining time, if any. * * @retval 0 on success. * @retval -EINVAL when an invalid @a clock_id, when @a rqtp contains nanoseconds outside of the * range `[0, 999999999]`, or when @a rqtp contains a negative value. */ __syscall int sys_clock_nanosleep(int clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp); /** * @} */ #ifndef CONFIG_BOARD_UNIT_TESTING #include #endif #ifdef __cplusplus } #endif #endif /* ZEPHYR_INCLUDE_SYS_CLOCK_H_ */