timeutil.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019 Peter Bigot Consulting, LLC
 * Copyright (c) 2025 Tenstorrent AI ULC
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SYS_TIMEUTIL_H_
#define ZEPHYR_INCLUDE_SYS_TIMEUTIL_H_
 
#include <limits.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
 
#include <zephyr/sys_clock.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/sys/math_extras.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
 
/* Base Year value use in calculations in "timeutil_timegm64" API */
#define TIME_UTILS_BASE_YEAR 1900
 
int64_t timeutil_timegm64(const struct tm *tm);
 
time_t timeutil_timegm(const struct tm *tm);
 
struct timeutil_sync_config {
        uint32_t ref_Hz;
 
        uint32_t local_Hz;
};
struct timeutil_sync_config {…};
 
struct timeutil_sync_instant {
        uint64_t ref;
 
        uint64_t local;
};
struct timeutil_sync_instant {…};
 
struct timeutil_sync_state {
        const struct timeutil_sync_config *cfg;
 
        struct timeutil_sync_instant base;
 
        struct timeutil_sync_instant latest;
 
        float skew;
};
struct timeutil_sync_state {…};
 
int timeutil_sync_state_update(struct timeutil_sync_state *tsp,
                               const struct timeutil_sync_instant *inst);
 
int timeutil_sync_state_set_skew(struct timeutil_sync_state *tsp, float skew,
                                 const struct timeutil_sync_instant *base);
 
float timeutil_sync_estimate_skew(const struct timeutil_sync_state *tsp);
 
int timeutil_sync_ref_from_local(const struct timeutil_sync_state *tsp,
                                 uint64_t local, uint64_t *refp);
 
int timeutil_sync_local_from_ref(const struct timeutil_sync_state *tsp,
                                 uint64_t ref, int64_t *localp);
 
int32_t timeutil_sync_skew_to_ppb(float skew);
 
static inline bool timespec_is_valid(const struct timespec *ts)
{
        __ASSERT_NO_MSG(ts != NULL);
 
        return (ts->tv_nsec >= 0) && (ts->tv_nsec < NSEC_PER_SEC);
}
static inline bool timespec_is_valid(const struct timespec *ts) {…}
 
static inline bool timespec_normalize(struct timespec *ts)
{
        __ASSERT_NO_MSG(ts != NULL);
 
#if defined(CONFIG_SPEED_OPTIMIZATIONS) && HAS_BUILTIN(__builtin_add_overflow)
 
        int sign = (ts->tv_nsec >= 0) - (ts->tv_nsec < 0);
        int64_t sec = (ts->tv_nsec >= (long)NSEC_PER_SEC) * (ts->tv_nsec / (long)NSEC_PER_SEC) +
                      ((ts->tv_nsec < 0) && (ts->tv_nsec != LONG_MIN)) *
                              DIV_ROUND_UP((unsigned long)-ts->tv_nsec, (long)NSEC_PER_SEC) +
                      (ts->tv_nsec == LONG_MIN) * ((LONG_MAX / NSEC_PER_SEC) + 1);
        bool overflow = __builtin_add_overflow(ts->tv_sec, sign * sec, &ts->tv_sec);
 
        ts->tv_nsec -= sign * (long)NSEC_PER_SEC * sec;
 
        if (!overflow) {
                __ASSERT_NO_MSG(timespec_is_valid(ts));
        }
 
        return !overflow;
 
#else
 
        long sec;
 
        if (ts->tv_nsec >= (long)NSEC_PER_SEC) {
                sec = ts->tv_nsec / (long)NSEC_PER_SEC;
        } else if (ts->tv_nsec < 0) {
                if ((sizeof(ts->tv_nsec) == sizeof(uint32_t)) && (ts->tv_nsec == LONG_MIN)) {
                        sec = DIV_ROUND_UP(LONG_MAX / NSEC_PER_USEC, USEC_PER_SEC);
                } else {
                        sec = DIV_ROUND_UP((unsigned long)-ts->tv_nsec, NSEC_PER_SEC);
                }
        } else {
                sec = 0;
        }
 
        if ((ts->tv_nsec < 0) && (ts->tv_sec < 0) && (ts->tv_sec - INT64_MIN < sec)) {
                /*
                 * When `tv_nsec` is negative and `tv_sec` is already most negative,
                 * further subtraction would cause integer overflow.
                 */
                return false;
        }
 
        if ((ts->tv_nsec >= (long)NSEC_PER_SEC) && (ts->tv_sec > 0) &&
            (INT64_MAX - ts->tv_sec < sec)) {
                /*
                 * When `tv_nsec` is >= `NSEC_PER_SEC` and `tv_sec` is already most
                 * positive, further addition would cause integer overflow.
                 */
                return false;
        }
 
        if (ts->tv_nsec >= (long)NSEC_PER_SEC) {
                ts->tv_sec += sec;
                ts->tv_nsec -= sec * (long)NSEC_PER_SEC;
        } else if (ts->tv_nsec < 0) {
                ts->tv_sec -= sec;
                ts->tv_nsec += sec * (long)NSEC_PER_SEC;
        } else {
                /* no change: SonarQube was complaining */
        }
 
        __ASSERT_NO_MSG(timespec_is_valid(ts));
 
        return true;
 
#endif
}
static inline bool timespec_normalize(struct timespec *ts) {…}
 
static inline bool timespec_add(struct timespec *a, const struct timespec *b)
{
        __ASSERT_NO_MSG((a != NULL) && timespec_is_valid(a));
        __ASSERT_NO_MSG((b != NULL) && timespec_is_valid(b));
 
#if defined(CONFIG_SPEED_OPTIMIZATIONS) && HAS_BUILTIN(__builtin_add_overflow)
 
        return !__builtin_add_overflow(a->tv_sec, b->tv_sec, &a->tv_sec) &&
               !__builtin_add_overflow(a->tv_nsec, b->tv_nsec, &a->tv_nsec) &&
               timespec_normalize(a);
 
#else
 
        if ((a->tv_sec < 0) && (b->tv_sec < 0) && (INT64_MIN - a->tv_sec > b->tv_sec)) {
                /* negative integer overflow would occur */
                return false;
        }
 
        if ((a->tv_sec > 0) && (b->tv_sec > 0) && (INT64_MAX - a->tv_sec < b->tv_sec)) {
                /* positive integer overflow would occur */
                return false;
        }
 
        a->tv_sec += b->tv_sec;
        a->tv_nsec += b->tv_nsec;
 
        return timespec_normalize(a);
 
#endif
}
static inline bool timespec_add(struct timespec *a, const struct timespec *b) {…}
 
static inline bool timespec_negate(struct timespec *ts)
{
        __ASSERT_NO_MSG((ts != NULL) && timespec_is_valid(ts));
 
#if defined(CONFIG_SPEED_OPTIMIZATIONS) && HAS_BUILTIN(__builtin_sub_overflow)
 
        return !__builtin_sub_overflow(0LL, ts->tv_sec, &ts->tv_sec) &&
               !__builtin_sub_overflow(0L, ts->tv_nsec, &ts->tv_nsec) && timespec_normalize(ts);
 
#else
 
        /* note: must check for 32-bit size here until #90029 is resolved */
        if (((sizeof(ts->tv_sec) == sizeof(int32_t)) && (ts->tv_sec == INT32_MIN)) ||
            ((sizeof(ts->tv_sec) == sizeof(int64_t)) && (ts->tv_sec == INT64_MIN))) {
                /* -INT64_MIN > INT64_MAX, so +ve integer overflow would occur */
                return false;
        }
 
        ts->tv_sec = -ts->tv_sec;
        ts->tv_nsec = -ts->tv_nsec;
 
        return timespec_normalize(ts);
 
#endif
}
static inline bool timespec_negate(struct timespec *ts) {…}
 
static inline bool timespec_sub(struct timespec *a, const struct timespec *b)
{
        __ASSERT_NO_MSG(a != NULL);
        __ASSERT_NO_MSG(b != NULL);
 
        struct timespec neg = *b;
 
        return timespec_negate(&neg) && timespec_add(a, &neg);
}
static inline bool timespec_sub(struct timespec *a, const struct timespec *b) {…}
 
static inline int timespec_compare(const struct timespec *a, const struct timespec *b)
{
        __ASSERT_NO_MSG((a != NULL) && timespec_is_valid(a));
        __ASSERT_NO_MSG((b != NULL) && timespec_is_valid(b));
 
        return (((a->tv_sec == b->tv_sec) && (a->tv_nsec < b->tv_nsec)) * -1) +
               (((a->tv_sec == b->tv_sec) && (a->tv_nsec > b->tv_nsec)) * 1) +
               ((a->tv_sec < b->tv_sec) * -1) + ((a->tv_sec > b->tv_sec));
}
static inline int timespec_compare(const struct timespec *a, const struct timespec *b) {…}
 
static inline bool timespec_equal(const struct timespec *a, const struct timespec *b)
{
        __ASSERT_NO_MSG(a != NULL);
        __ASSERT_NO_MSG(b != NULL);
 
        return (a->tv_sec == b->tv_sec) && (a->tv_nsec == b->tv_nsec);
}
static inline bool timespec_equal(const struct timespec *a, const struct timespec *b) {…}
 
static inline void timespec_from_timeout(k_timeout_t timeout, struct timespec *ts)
{
        __ASSERT_NO_MSG(ts != NULL);
 
#if defined(CONFIG_SPEED_OPTIMIZATIONS)
 
        uint64_t ns = k_ticks_to_ns_ceil64(timeout.ticks);
 
        *ts = (struct timespec){
                .tv_sec = (timeout.ticks == K_TICKS_FOREVER) * INT64_MAX +
                          (timeout.ticks != K_TICKS_FOREVER) * (ns / NSEC_PER_SEC),
                .tv_nsec = (timeout.ticks == K_TICKS_FOREVER) * (NSEC_PER_SEC - 1) +
                           (timeout.ticks != K_TICKS_FOREVER) * (ns % NSEC_PER_SEC),
        };
 
#else
 
        if (timeout.ticks == 0) {
                /* This is equivalent to K_NO_WAIT, but without including <zephyr/kernel.h> */
                ts->tv_sec = 0;
                ts->tv_nsec = 0;
        } else if (timeout.ticks == K_TICKS_FOREVER) {
                /* This is roughly equivalent to K_FOREVER, but not including <zephyr/kernel.h> */
                ts->tv_sec = (time_t)INT64_MAX;
                ts->tv_nsec = NSEC_PER_SEC - 1;
        } else {
                uint64_t ns = k_ticks_to_ns_ceil64(timeout.ticks);
 
                ts->tv_sec = ns / NSEC_PER_SEC;
                ts->tv_nsec = ns - ts->tv_sec * NSEC_PER_SEC;
        }
 
#endif
 
        __ASSERT_NO_MSG(timespec_is_valid(ts));
}
static inline void timespec_from_timeout(k_timeout_t timeout, struct timespec *ts) {…}
 
static inline k_timeout_t timespec_to_timeout(const struct timespec *ts)
{
        __ASSERT_NO_MSG((ts != NULL) && timespec_is_valid(ts));
 
#if defined(CONFIG_SPEED_OPTIMIZATIONS)
 
        return (k_timeout_t){
                /* note: must check for 32-bit size here until #90029 is resolved */
                .ticks = ((sizeof(ts->tv_sec) == sizeof(int32_t) && (ts->tv_sec == INT32_MAX) &&
                           (ts->tv_nsec == NSEC_PER_SEC - 1)) ||
                          ((sizeof(ts->tv_sec) == sizeof(int64_t)) && (ts->tv_sec == INT64_MAX) &&
                           (ts->tv_nsec == NSEC_PER_SEC - 1))) *
                                 K_TICKS_FOREVER +
                         ((sizeof(ts->tv_sec) == sizeof(int32_t) && (ts->tv_sec == INT32_MAX) &&
                           (ts->tv_nsec == NSEC_PER_SEC - 1)) ||
                          ((sizeof(ts->tv_sec) == sizeof(int64_t)) && (ts->tv_sec != INT64_MAX) &&
                           (ts->tv_sec >= 0))) *
                                 (IS_ENABLED(CONFIG_TIMEOUT_64BIT)
                                          ? (int64_t)(CLAMP(
                                                    k_sec_to_ticks_floor64(ts->tv_sec) +
                                                            k_ns_to_ticks_floor64(ts->tv_nsec),
                                                    0, (uint64_t)INT64_MAX))
                                          : (uint32_t)(CLAMP(
                                                    k_sec_to_ticks_floor64(ts->tv_sec) +
                                                            k_ns_to_ticks_floor64(ts->tv_nsec),
                                                    0, (uint64_t)UINT32_MAX)))};
 
#else
 
        if ((ts->tv_sec < 0) || (ts->tv_sec == 0 && ts->tv_nsec == 0)) {
                /* This is equivalent to K_NO_WAIT, but without including <zephyr/kernel.h> */
                return (k_timeout_t){
                        .ticks = 0,
                };
                /* note: must check for 32-bit size here until #90029 is resolved */
        } else if (((sizeof(ts->tv_sec) == sizeof(int32_t)) && (ts->tv_sec == INT32_MAX) &&
                    (ts->tv_nsec == NSEC_PER_SEC - 1)) ||
                   ((sizeof(ts->tv_sec) == sizeof(int64_t)) && (ts->tv_sec == INT64_MAX) &&
                    (ts->tv_nsec == NSEC_PER_SEC - 1))) {
                /* This is equivalent to K_FOREVER, but not including <zephyr/kernel.h> */
                return (k_timeout_t){
                        .ticks = K_TICKS_FOREVER,
                };
        } else {
                if (IS_ENABLED(CONFIG_TIMEOUT_64BIT)) {
                        return (k_timeout_t){
                                .ticks = (int64_t)CLAMP(k_sec_to_ticks_floor64(ts->tv_sec) +
                                                                k_ns_to_ticks_floor64(ts->tv_nsec),
                                                        0, (uint64_t)INT64_MAX),
                        };
                } else {
                        return (k_timeout_t){
                                .ticks = (uint32_t)CLAMP(k_sec_to_ticks_floor64(ts->tv_sec) +
                                                                 k_ns_to_ticks_floor64(ts->tv_nsec),
                                                         0, (uint64_t)UINT32_MAX),
                        };
                }
        }
 
#endif
}
static inline k_timeout_t timespec_to_timeout(const struct timespec *ts) {…}
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_TIMEUTIL_H_ */