sys: util: timeutil: add timespec manipulation utilities

Add a number of utility functions for manipulating struct timespec.

* timespec_add_overflow()
* timespec_compare()
* timespec_equal()
* timespec_is_valid()
* timespec_negate_overflow()
* timespec_normalize_overflow()
* timespec_sub_overflow()

If the `__builtin_add_overflow()` and `__builtin_sub_overflow()`
functions are available, then these functions use are mostly
branchless, which should provide decent performance on systems with an
instruction cache. Otherwise, manually written alternatives exist that
are also perhaps more readable.

Signed-off-by: Chris Friedt <[email protected]>

Author: cfriedt

include/zephyr/sys/timeutil.h

@@ -21,8 +21,15 @@
 #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/toolchain.h>
 #include <zephyr/types.h>
 
 #ifdef __cplusplus
@@ -301,6 +308,278 @@ int timeutil_sync_local_from_ref(const struct timeutil_sync_state *tsp,
  */
 int32_t timeutil_sync_skew_to_ppb(float skew);
 
+/**
+ * @}
+ */
+
+BUILD_ASSERT(sizeof(time_t) == sizeof(int64_t), "time_t must be 64-bit");
+BUILD_ASSERT(sizeof(((struct timespec *)0)->tv_sec) == sizeof(int64_t), "tv_sec must be 64-bit");
+
+/**
+ * @defgroup timeutil_timespec_apis Timespec Utility APIs
+ * @ingroup timeutil_apis
+ * @{
+ */
+
+/**
+ * @brief Check if a timespec is valid.
+ *
+ * Check if a timespec is valid (i.e. normalized) by ensuring that the `tv_nsec` field is in the
+ * range `[0, NSEC_PER_SEC-1]`.
+ *
+ * @note @p ts must not be `NULL`.
+ *
+ * @param ts the timespec to check
+ *
+ * @return `true` if the timespec is valid, otherwise `false`.
+ */
+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);
+}
+
+#if (HAS_BUILTIN(__builtin_add_overflow) && HAS_BUILTIN(__builtin_sub_overflow)) ||                \
+	defined(__DOXYGEN__)
+/**
+ * @brief Normalize a timespec so that the `tv_nsec` field is in valid range.
+ *
+ * Normalize a timespec by adjusting the `tv_sec` and `tv_nsec` fields so that the `tv_nsec` field
+ * is in the range `[0, NSEC_PER_SEC-1]`. This is achieved by converting nanoseconds to seconds and
+ * accumulating seconds in either the positive direction when `tv_nsec` > `NSEC_PER_SEC`, or in the
+ * negative direction when `tv_nsec` < 0.
+ *
+ * In pseudocode, normalization can be done as follows:
+ * ```python
+ * if ts.tv_nsec >= NSEC_PER_SEC:
+ *     sec = ts.tv_nsec / NSEC_PER_SEC
+ *     ts.tv_sec += sec
+ *     ts.tv_nsec -= sec * NSEC_PER_SEC
+ * elif ts.tv_nsec < 0:
+ *      # div_round_up(abs(ts->tv_nsec), NSEC_PER_SEC)
+ *	    sec = (NSEC_PER_SEC - ts.tv_nsec - 1) / NSEC_PER_SEC
+ *	    ts.tv_sec -= sec;
+ *	    ts.tv_nsec += sec * NSEC_PER_SEC;
+ * ```
+ *
+ * @note There are two cases where the normalization can result in integer overflow. These can
+ * be extrapolated to not simply overflowing the `tv_sec` field by one second, but also by any
+ * realizable multiple of `NSEC_PER_SEC`.
+ *
+ * 1. When `tv_nsec` is negative and `tv_sec` is already most negative.
+ * 2. When `tv_nsec` is greater-or-equal to `NSEC_PER_SEC` and `tv_sec` is already most positive.
+ *
+ * @note @p ts must be non-`NULL`.
+ *
+ * @param ts the timespec to be normalized
+ *
+ * @return `true` if the operation would result in integer overflow, otherwise `false`.
+ */
+static inline bool timespec_normalize_overflow(struct timespec *ts)
+{
+	__ASSERT_NO_MSG(ts != NULL);
+
+	int sign = (ts->tv_nsec >= 0) - (ts->tv_nsec < 0);
+	int64_t sec = (ts->tv_nsec >= NSEC_PER_SEC) * (ts->tv_nsec / NSEC_PER_SEC) +
+		      (ts->tv_nsec < 0) * DIV_ROUND_UP(-ts->tv_nsec, NSEC_PER_SEC);
+	bool overflow = __builtin_add_overflow(ts->tv_sec, sign * sec, &ts->tv_sec) ||
+			__builtin_sub_overflow(ts->tv_nsec, (long)(sign * sec * NSEC_PER_SEC),
+					       &ts->tv_nsec);
+
+	if (!overflow) {
+		__ASSERT_NO_MSG(timespec_is_valid(ts));
+	}
+
+	return overflow;
+}
+
+/**
+ * @brief Add one timespec to another
+ *
+ * This function sums the two timespecs pointed to by @p a and @p b and stores the result in the
+ * timespce pointed to by @p a.
+ *
+ * @note @p a and @p b must be non-`NULL` and normalized.
+ *
+ * @param a the timespec which is added to
+ * @param b the timespec to be added
+ *
+ * @return `true` if the operation would result in integer overflow, otherwise `false`.
+ */
+static inline bool timespec_add_overflow(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 __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_overflow(a);
+}
+
+/**
+ * @brief Negate a timespec object
+ *
+ * Negate the timespec object pointed to by @p ts and store the result in the same
+ * memory location.
+ *
+ * @param ts The timespec object to negate.
+ *
+ * @return `true` of the operation would overflow, otherwise `false`.
+ */
+static inline bool timespec_negate_overflow(struct timespec *ts)
+{
+	__ASSERT_NO_MSG((ts != NULL) && timespec_is_valid(ts));
+
+	return __builtin_sub_overflow(0LL, ts->tv_sec, &ts->tv_sec) ||
+	       __builtin_sub_overflow(0L, ts->tv_nsec, &ts->tv_nsec) ||
+	       timespec_normalize_overflow(ts);
+}
+#else
+
+static inline bool timespec_normalize_overflow(struct timespec *ts)
+{
+	__ASSERT_NO_MSG(ts != NULL);
+
+	/* This implementation is unoptimized mainly for readability */
+
+	long sec = 0;
+
+	if (ts->tv_nsec >= NSEC_PER_SEC) {
+		sec = ts->tv_nsec / NSEC_PER_SEC;
+	} else if (ts->tv_nsec < 0) {
+		sec = DIV_ROUND_UP(-ts->tv_nsec, NSEC_PER_SEC);
+	}
+
+	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 true;
+	}
+
+	if ((ts->tv_nsec >= 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 true;
+	}
+
+	if (ts->tv_nsec >= NSEC_PER_SEC) {
+		ts->tv_sec += sec;
+		ts->tv_nsec -= sec * NSEC_PER_SEC;
+	} else if (ts->tv_nsec < 0) {
+		ts->tv_sec -= sec;
+		ts->tv_nsec += sec * NSEC_PER_SEC;
+	}
+
+	return false;
+}
+
+static inline bool timespec_add_overflow(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 ((a->tv_sec < 0) && (b->tv_sec < 0) && (INT64_MIN - a->tv_sec > b->tv_sec)) {
+		/* negative integer overflow would occur */
+		return true;
+	}
+
+	if ((a->tv_sec > 0) && (b->tv_sec > 0) && (INT64_MAX - a->tv_sec < b->tv_sec)) {
+		/* positive integer overflow would occur */
+		return true;
+	}
+
+	a->tv_sec += b->tv_sec;
+	a->tv_nsec += b->tv_nsec;
+
+	return timespec_normalize_overflow(a);
+}
+
+static inline bool timespec_negate_overflow(struct timespec *ts)
+{
+	__ASSERT_NO_MSG((ts != NULL) && timespec_is_valid(ts));
+
+	if (ts->tv_sec == INT64_MIN) {
+		/* -INT64_MIN > INT64_MAX, so +ve integer overflow would occur */
+		return true;
+	}
+
+	ts->tv_sec = -ts->tv_sec;
+	ts->tv_nsec = -ts->tv_nsec;
+
+	return timespec_normalize_overflow(ts);
+}
+#endif
+
+/**
+ * @brief Subtract one timespec from another
+ *
+ * This function subtracts the timespec pointed to by @p b from the timespec pointed to by @p b and
+ * stores the result in the timespce pointed to by @p a.
+ *
+ * @note @p a and @p b must be non-`NULL`.
+ *
+ * @param a the timespec which is subtracted from
+ * @param b the timespec to be subtracted
+ *
+ * @return `true` if the operation would result in integer overflow, otherwise `false`.
+ */
+static inline bool timespec_sub_overflow(struct timespec *a, const struct timespec *b)
+{
+	__ASSERT_NO_MSG(a != NULL);
+	__ASSERT_NO_MSG(b != NULL);
+
+	struct timespec neg = *b;
+
+	return timespec_negate_overflow(&neg) || timespec_add_overflow(a, &neg);
+}
+
+/**
+ * @brief Compare two timespec objects
+ *
+ * This function compares two timespec objects pointed to by @p a and @p b.
+ *
+ * @note @p a and @p b must be non-`NULL` and normalized.
+ *
+ * @param a the first timespec to compare
+ * @param b the second timespec to compare
+ *
+ * @return -1, 0, or +1 if @a a is less than, equal to, or greater than @a b, respectively.
+ */
+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));
+}
+
+/**
+ * @brief Check if two timespec objects are equal
+ *
+ * This function checks if the two timespec objects pointed to by @p a and @p b are equal.
+ *
+ * @note @p a and @p b must be non-`NULL` are not required to be normalized.
+ *
+ * @param a the first timespec to compare
+ * @param b the second timespec to compare
+ *
+ * @return true if the two timespec objects are equal, otherwise false.
+ */
+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);
+}
+
 /**
  * @}
  */