clock.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014-2015 Wind River Systems, Inc.
 * Copyright (c) 2025 Tenstorrent AI ULC
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_SYS_CLOCK_H_
#define ZEPHYR_INCLUDE_SYS_CLOCK_H_
 
#include <zephyr/sys/dlist.h>
#include <zephyr/sys/time_units.h>
#include <zephyr/sys/util.h>
#include <zephyr/toolchain.h>
#include <zephyr/types.h>
 
#ifdef __cplusplus
extern "C" {
#endif


#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))

typedef struct {
        k_ticks_t ticks;
} k_timeout_t;

#define K_TIMEOUT_EQ(a, b) ((a).ticks == (b).ticks)

#define NSEC_PER_USEC 1000U

#define NSEC_PER_MSEC 1000000U

#define USEC_PER_MSEC 1000U

#define MSEC_PER_SEC 1000U

#define SEC_PER_MIN 60U

#define SEC_PER_HOUR 3600U

#define SEC_PER_DAY 86400U

#define MIN_PER_HOUR 60U

#define HOUR_PER_DAY 24U

#define USEC_PER_SEC ((USEC_PER_MSEC) * (MSEC_PER_SEC))

#define NSEC_PER_SEC ((NSEC_PER_USEC) * (USEC_PER_MSEC) * (MSEC_PER_SEC))


#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))

static inline k_ticks_t z_timeout_sum(k_timeout_t t1, k_timeout_t t2)
{
        k_ticks_t ticks1 = t1.ticks;
        k_ticks_t ticks2 = t2.ticks;
 
#ifdef CONFIG_TIMEOUT_64BIT
        if ((ticks1 == K_TICKS_FOREVER) || (ticks2 == K_TICKS_FOREVER)) {
                return K_TICKS_FOREVER;
        }
 
        if (ticks1 < 0) {
                if (ticks2 < 0) {
                        return K_TICKS_FOREVER;  /* Both absolute timeouts */
                }
 
                return ((ticks1 - INT64_MIN) < ticks2) ?
                        K_TICKS_FOREVER : (ticks1 - ticks2);
        } else if (ticks2 < 0) {
                return ((ticks2 - INT64_MIN) < ticks1) ?
                        K_TICKS_FOREVER : (ticks2 - ticks1);
        } else {
                return ((INT64_MAX - ticks1) < ticks2) ?
                        K_TICKS_FOREVER : ticks1 + ticks2;
        }
#else
        return ((UINT32_MAX - ticks1) < ticks2) ? K_TICKS_FOREVER : ticks1 + ticks2;
#endif
}

 
#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.
 */
 
#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

#define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) (uint32_t)(k_cyc_to_ns_floor64(X) / NCYCLES)

uint32_t sys_clock_tick_get_32(void);

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

typedef struct {
        uint64_t tick;
} k_timepoint_t;

k_timepoint_t sys_timepoint_calc(k_timeout_t timeout);

k_timeout_t sys_timepoint_timeout(k_timepoint_t timepoint);

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

static inline bool sys_timepoint_expired(k_timepoint_t timepoint)
{
        return K_TIMEOUT_EQ(sys_timepoint_timeout(timepoint), Z_TIMEOUT_NO_WAIT);
}



#define SYS_CLOCK_REALTIME 1

#define SYS_CLOCK_MONOTONIC 4

#define SYS_TIMER_ABSTIME 4

/* 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);

__syscall void sys_clock_getrtoffset(struct timespec *tp);

int sys_clock_gettime(int clock_id, struct timespec *tp);

__syscall int sys_clock_settime(int clock_id, const struct timespec *tp);

__syscall int sys_clock_nanosleep(int clock_id, int flags, const struct timespec *rqtp,
                                  struct timespec *rmtp);

 
#ifndef CONFIG_BOARD_UNIT_TESTING
#include <zephyr/syscalls/clock.h>
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_CLOCK_H_ */