timeutil.h File Reference

Utilities supporting operation on time data structures. More...

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

Go to the source code of this file.

Data Structures
struct	timeutil_sync_config
	Immutable state for synchronizing two clocks. More...
struct	timeutil_sync_instant
	Representation of an instant in two time scales. More...
struct	timeutil_sync_state
	State required to convert instants between time scales. More...

Macros
#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)
#define	SYS_TICKS_TO_SECS(ticks)
#define	SYS_TICKS_TO_NSECS(ticks)
#define	SYS_TIMESPEC(sec, nsec)
#define	SYS_TICKS_TO_TIMESPEC(ticks)
#define	SYS_TIMESPEC_NO_WAIT   SYS_TICKS_TO_TIMESPEC(0)
#define	SYS_TIMESPEC_MIN   SYS_TICKS_TO_TIMESPEC(K_TICK_MIN)
#define	SYS_TIMESPEC_MAX   SYS_TICKS_TO_TIMESPEC(K_TICK_MAX)
#define	SYS_TIMESPEC_FOREVER   SYS_TIMESPEC(SYS_TIME_T_MAX, NSEC_PER_SEC - 1)
#define	TIME_UTILS_BASE_YEAR   1900

Functions
int64_t	timeutil_timegm64 (const struct tm *tm)
	Convert broken-down time to a POSIX epoch offset in seconds.
time_t	timeutil_timegm (const struct tm *tm)
	Convert broken-down time to a POSIX epoch offset in seconds.
int	timeutil_sync_state_update (struct timeutil_sync_state *tsp, const struct timeutil_sync_instant *inst)
	Record a new instant in the time synchronization state.
int	timeutil_sync_state_set_skew (struct timeutil_sync_state *tsp, float skew, const struct timeutil_sync_instant *base)
	Update the state with a new skew and possibly base value.
float	timeutil_sync_estimate_skew (const struct timeutil_sync_state *tsp)
	Estimate the skew based on current state.
int	timeutil_sync_ref_from_local (const struct timeutil_sync_state *tsp, uint64_t local, uint64_t *refp)
	Interpolate a reference timescale instant from a local instant.
int	timeutil_sync_local_from_ref (const struct timeutil_sync_state *tsp, uint64_t ref, int64_t *localp)
	Interpolate a local timescale instant from a reference instant.
int32_t	timeutil_sync_skew_to_ppb (float skew)
	Convert from a skew to an error in parts-per-billion.
static bool	timespec_is_valid (const struct timespec *ts)
	Check if a timespec is valid.
bool	timespec_normalize (struct timespec *ts)
	Normalize a timespec so that the tv_nsec field is in valid range.
static bool	timespec_add (struct timespec *a, const struct timespec *b)
	Add one timespec to another.
static bool	timespec_negate (struct timespec *ts)
	Negate a timespec object.
static bool	timespec_sub (struct timespec *a, const struct timespec *b)
	Subtract one timespec from another.
static int	timespec_compare (const struct timespec *a, const struct timespec *b)
	Compare two timespec objects.
static bool	timespec_equal (const struct timespec *a, const struct timespec *b)
	Check if two timespec objects are equal.
static void	timespec_from_timeout (k_timeout_t timeout, struct timespec *ts)
	Convert a kernel timeout to a timespec.
static k_timeout_t	timespec_to_timeout (const struct timespec *req, struct timespec *rem)
	Convert a timespec to a kernel timeout.

Detailed Description

Utilities supporting operation on time data structures.

POSIX defines gmtime() to convert from time_t to struct tm, but all inverse transformations are non-standard or require access to time zone information. timeutil_timegm() implements the functionality of the GNU extension timegm() function, but changes the error value as EOVERFLOW is not a standard C error identifier.

timeutil_timegm64() is provided to support full precision conversion on platforms where time_t is limited to 32 bits.

Macro Definition Documentation

SYS_TICKS_TO_NSECS

#define SYS_TICKS_TO_NSECS

(

ticks

)

Value:

        (((uint64_t)(ticks) >= (uint64_t)K_TICKS_FOREVER)                                          \
                 ? (NSEC_PER_SEC - 1)                                                              \
                 : k_ticks_to_ns_floor64((uint64_t)(ticks) % CONFIG_SYS_CLOCK_TICKS_PER_SEC))

SYS_TICKS_TO_SECS

#define SYS_TICKS_TO_SECS

(

ticks

)

Value:

        (((uint64_t)(ticks) >= (uint64_t)K_TICKS_FOREVER) ? SYS_TIME_T_MAX                         \
                                                          : k_ticks_to_sec_floor64(ticks))

SYS_TICKS_TO_TIMESPEC

#define SYS_TICKS_TO_TIMESPEC

(

ticks

)

Value:

                                                  SYS_TIMESPEC(SYS_TICKS_TO_SECS(ticks), \
                                                  SYS_TICKS_TO_NSECS(ticks))

SYS_TIME_T_MAX

#define SYS_TIME_T_MAX   ((((time_t)1 << (8 * sizeof(time_t) - 2)) - 1) * 2 + 1)

SYS_TIME_T_MIN

#define SYS_TIME_T_MIN   (-SYS_TIME_T_MAX - 1)

SYS_TIMESPEC

#define SYS_TIMESPEC	(		sec,
			nsec )

Value:

        ((struct timespec){                                                                        \
                .tv_sec = (time_t)CLAMP((int64_t)(sec), SYS_TIME_T_MIN, SYS_TIME_T_MAX),           \
                .tv_nsec = (long)(nsec),                                                           \
        })

SYS_TIMESPEC_FOREVER

#define SYS_TIMESPEC_FOREVER   SYS_TIMESPEC(SYS_TIME_T_MAX, NSEC_PER_SEC - 1)

SYS_TIMESPEC_MAX

#define SYS_TIMESPEC_MAX   SYS_TICKS_TO_TIMESPEC(K_TICK_MAX)

SYS_TIMESPEC_MIN

#define SYS_TIMESPEC_MIN   SYS_TICKS_TO_TIMESPEC(K_TICK_MIN)

SYS_TIMESPEC_NO_WAIT

#define SYS_TIMESPEC_NO_WAIT   SYS_TICKS_TO_TIMESPEC(0)