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
 
/* Maximum and minimum value TIME_T can hold */
#define SYS_TIME_T_MAX ((((time_t)1 << (8 * sizeof(time_t) - 2)) - 1) * 2 + 1)
#define SYS_TIME_T_MIN (-SYS_TIME_T_MAX - 1)
 
/* Converts ticks to seconds, discarding any fractional seconds */
#define SYS_TICKS_TO_SECS(ticks)                                                                   \
        (((uint64_t)(ticks) >= (uint64_t)K_TICKS_FOREVER) ? SYS_TIME_T_MAX                         \
                                                          : k_ticks_to_sec_floor64(ticks))
 
/* Converts ticks to nanoseconds, modulo NSEC_PER_SEC */
#define SYS_TICKS_TO_NSECS(ticks)                                                                  \
        (((uint64_t)(ticks) >= (uint64_t)K_TICKS_FOREVER)                                          \
                 ? (NSEC_PER_SEC - 1)                                                              \
                 : k_ticks_to_ns_floor32((uint64_t)(ticks) % CONFIG_SYS_CLOCK_TICKS_PER_SEC))
 
/* Define a timespec */
#define SYS_TIMESPEC(sec, nsec)                                                                    \
        ((struct timespec){                                                                        \
                .tv_sec = (time_t)CLAMP((int64_t)(sec), SYS_TIME_T_MIN, SYS_TIME_T_MAX),           \
                .tv_nsec = (long)(nsec),                                                           \
        })
 
/* Initialize a struct timespec object from a tick count */
#define SYS_TICKS_TO_TIMESPEC(ticks) SYS_TIMESPEC(SYS_TICKS_TO_SECS(ticks), \
                                                  SYS_TICKS_TO_NSECS(ticks))
 
/* The semantic equivalent of K_NO_WAIT but expressed as a timespec object*/
#define SYS_TIMESPEC_NO_WAIT SYS_TICKS_TO_TIMESPEC(0)
 
/* The semantic equivalent of K_TICK_MIN but expressed as a timespec object */
#define SYS_TIMESPEC_MIN SYS_TICKS_TO_TIMESPEC(K_TICK_MIN)
 
/* The semantic equivalent of K_TICK_MAX but expressed as a timespec object */
#define SYS_TIMESPEC_MAX SYS_TICKS_TO_TIMESPEC(K_TICK_MAX)
 
/* The semantic equivalent of K_FOREVER but expressed as a timespec object*/
#define SYS_TIMESPEC_FOREVER SYS_TIMESPEC(SYS_TIME_T_MAX, NSEC_PER_SEC - 1)
 
/* 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_instant {
        uint64_t ref;
 
        uint64_t local;
};
 
struct timeutil_sync_state {
        const struct timeutil_sync_config *cfg;
 
        struct timeutil_sync_instant base;
 
        struct timeutil_sync_instant latest;
 
        float skew;
};
 
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 < (long)NSEC_PER_SEC);
}
 
static inline bool timespec_normalize(struct timespec *ts)
{
        __ASSERT_NO_MSG(ts != NULL);
 
#if defined(CONFIG_SPEED_OPTIMIZATIONS) && HAS_BUILTIN(__builtin_add_overflow)
 
        int64_t sec = 0;
        int sign = (ts->tv_nsec >= 0) - (ts->tv_nsec < 0);
 
        /* only one of the following should be non-zero */
        sec += (ts->tv_nsec >= (long)NSEC_PER_SEC) * (ts->tv_nsec / (long)NSEC_PER_SEC);
        sec += ((sizeof(ts->tv_nsec) != sizeof(int64_t)) && (ts->tv_nsec != LONG_MIN) &&
                (ts->tv_nsec < 0)) *
               DIV_ROUND_UP((unsigned long)-ts->tv_nsec, (long)NSEC_PER_SEC);
        sec += ((sizeof(ts->tv_nsec) == sizeof(int64_t)) && (ts->tv_nsec != INT64_MIN) &&
                (ts->tv_nsec < 0)) *
               DIV_ROUND_UP((uint64_t)-ts->tv_nsec, NSEC_PER_SEC);
        sec += ((sizeof(ts->tv_nsec) != sizeof(int64_t)) && (ts->tv_nsec == LONG_MIN)) *
               ((LONG_MAX / NSEC_PER_SEC) + 1);
        sec += ((sizeof(ts->tv_nsec) == sizeof(int64_t)) && (ts->tv_nsec == INT64_MIN)) *
               ((INT64_MAX / NSEC_PER_SEC) + 1);
 
        ts->tv_nsec -= sec * sign * NSEC_PER_SEC;
 
        bool overflow = __builtin_add_overflow(ts->tv_sec, sign * sec, &ts->tv_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) {
                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 - SYS_TIME_T_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) &&
            (SYS_TIME_T_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_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) && (SYS_TIME_T_MIN - a->tv_sec > b->tv_sec)) {
                /* negative integer overflow would occur */
                return false;
        }
 
        if ((a->tv_sec > 0) && (b->tv_sec > 0) && (SYS_TIME_T_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_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
 
        if (ts->tv_sec == SYS_TIME_T_MIN) {
                /* -SYS_TIME_T_MIN > SYS_TIME_T_MAX, so positive 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_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 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 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 void timespec_from_timeout(k_timeout_t timeout, struct timespec *ts)
{
        __ASSERT_NO_MSG(ts != NULL);
        __ASSERT_NO_MSG(Z_IS_TIMEOUT_RELATIVE(timeout) ||
                        (IS_ENABLED(CONFIG_TIMEOUT_64BIT) &&
                         K_TIMEOUT_EQ(timeout, (k_timeout_t){K_TICKS_FOREVER})));
 
        /* equivalent of K_FOREVER without including kernel.h */
        if (K_TIMEOUT_EQ(timeout, (k_timeout_t){K_TICKS_FOREVER})) {
                /* duration == K_TICKS_FOREVER ticks */
                *ts = SYS_TIMESPEC_FOREVER;
                /* equivalent of K_NO_WAIT without including kernel.h */
        } else if (K_TIMEOUT_EQ(timeout, (k_timeout_t){0})) {
                /* duration <= 0 ticks */
                *ts = SYS_TIMESPEC_NO_WAIT;
        } else {
                *ts = SYS_TICKS_TO_TIMESPEC(timeout.ticks);
        }
 
        __ASSERT_NO_MSG(timespec_is_valid(ts));
}
 
static inline k_timeout_t timespec_to_timeout(const struct timespec *req, struct timespec *rem)
{
        k_timeout_t timeout;
 
        __ASSERT_NO_MSG((req != NULL) && timespec_is_valid(req));
 
        if (timespec_compare(req, &SYS_TIMESPEC_NO_WAIT) <= 0) {
                if (rem != NULL) {
                        *rem = *req;
                }
                /* equivalent of K_NO_WAIT without including kernel.h */
                timeout.ticks = 0;
                return timeout;
        }
 
        if (timespec_compare(req, &SYS_TIMESPEC_FOREVER) == 0) {
                if (rem != NULL) {
                        *rem = SYS_TIMESPEC_NO_WAIT;
                }
                /* equivalent of K_FOREVER without including kernel.h */
                timeout.ticks = K_TICKS_FOREVER;
                return timeout;
        }
 
        if (timespec_compare(req, &SYS_TIMESPEC_MAX) >= 0) {
                /* round down to align to max ticks */
                timeout.ticks = K_TICK_MAX;
        } else {
                /* round up to align to next tick boundary */
                timeout.ticks = CLAMP(k_ns_to_ticks_ceil64(req->tv_nsec) +
                                              k_sec_to_ticks_ceil64(req->tv_sec),
                                      K_TICK_MIN, K_TICK_MAX);
        }
 
        if (rem != NULL) {
                timespec_from_timeout(timeout, rem);
                timespec_sub(rem, req);
                timespec_negate(rem);
        }
 
        return timeout;
}
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_TIMEUTIL_H_ */