sys: timeutil: compute the remainder in timespec to timeout conversion

Since it's possible that rounding up might not always be the right thing
to do in every situation, in order to allow the application to make more
informed decisions, we created a modified timespec_to_timeout() that also
returns the remainder (or difference) between the requested time to
convert and resulting k_timeout_t. The difference is expressed as a
timespec object.

Signed-off-by: Chris Friedt <cfriedt@tenstorrent.com>

Author: cfriedt

include/zephyr/sys/timeutil.h

@@ -663,22 +663,37 @@ static inline void timespec_from_timeout(k_timeout_t timeout, struct timespec *t
  *
  * Otherwise, this function will return the `k_timeout_t` that is rounded-up to a tick boundary.
  *
+ * If @p rem is not `NULL`, it will be set to the remainder of the conversion, i.e. the difference
+ * between the requested duration and the converted duration as a `timespec` object, approximately
+ * as shown below.
+ *
+ * ```python
+ * rem = requested_duration - converted_duration
+ * ```
+ *
  * @param req the requested `timespec` to convert
+ * @param[out] rem optional pointer to a `timespec` to store the remainder
  * @return the corresponding kernel timeout
  */
-static inline k_timeout_t timespec_to_timeout(const struct timespec *req)
+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, &K_TS_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, &K_TS_FOREVER) == 0) {
+		if (rem != NULL) {
+			*rem = K_TS_NO_WAIT;
+		}
 		/* equivalent of K_FOREVER without including kernel.h */
 		timeout.ticks = K_TICKS_FOREVER;
 		return timeout;
@@ -694,6 +709,12 @@ static inline k_timeout_t timespec_to_timeout(const struct timespec *req)
 				      K_TICK_MIN, K_TICK_MAX);
 	}
 
+	if (rem != NULL) {
+		timespec_from_timeout(timeout, rem);
+		timespec_sub(rem, req);
+		timespec_negate(rem);
+	}
+
 	return timeout;
 }
 

lib/os/clock.c

@@ -175,7 +175,7 @@ int z_impl_sys_clock_nanosleep(int clock_id, int flags, const struct timespec *r
 		(void)timespec_add(&duration, &rem);
 	}
 
-	timeout = timespec_to_timeout(&duration);
+	timeout = timespec_to_timeout(&duration, NULL);
 	end = sys_timepoint_calc(timeout);
 	do {
 		(void)k_sleep(timeout);

tests/lib/timespec_util/src/main.c

@@ -454,12 +454,14 @@ ZTEST(timeutil_api, test_timespec_to_timeout)
 	ARRAY_FOR_EACH(tospecs, i) {
 		const struct tospec *const tspec = &tospecs[i];
 		k_timeout_t actual;
+		struct timespec tick_ts;
+		struct timespec rem = {};
 
 		TC_PRINT("%zu: ticks: {%lld}, timespec: {%lld, %lld}\n", i,
 			 (long long)tspec->timeout.ticks, (long long)tspec->tspec.tv_sec,
 			 (long long)tspec->tspec.tv_nsec);
 
-		actual = timespec_to_timeout(&tspec->tspec);
+		actual = timespec_to_timeout(&tspec->tspec, &rem);
 		if (tspec->saturation == 0) {
 			/* exact match or rounding up */
 			if (!tspec->negative &&
@@ -501,20 +503,32 @@ ZTEST(timeutil_api, test_timespec_to_timeout)
 				      "} are unexpectedly different",
 				      i, (int64_t)actual.ticks, (int64_t)K_TICK_MAX);
 		}
+
+		timespec_from_timeout(tspec->timeout, &tick_ts);
+		timespec_add(&tick_ts, &rem);
+		zexpect_true(timespec_equal(&tick_ts, &tspec->tspec),
+			     "%d: {%ld, %ld} and {%ld, %ld} are unexpectedly different", i,
+			     tick_ts.tv_sec, tick_ts.tv_nsec, tspec->tspec.tv_sec,
+			     tspec->tspec.tv_nsec);
 	}
 
 #if defined(CONFIG_TIMEOUT_64BIT) && (CONFIG_SYS_CLOCK_TICKS_PER_SEC == 100)
 	{
+		struct timespec rem = {};
 		k_timeout_t to = K_TICKS(K_TICK_MAX);
 		/* K_TS_MAX corresponding K_TICK_MAX with a tick rate of 100 Hz */
 		struct timespec ts = K_TIMESPEC(92233720368547758LL, 70000000L);
 
-		zexpect_true(K_TIMEOUT_EQ(timespec_to_timeout(&ts), to),
+		zexpect_true(K_TIMEOUT_EQ(timespec_to_timeout(&ts, &rem), to),
 			     "timespec_to_timeout(%lld, %lld) != %lld", (long long)ts.tv_sec,
 			     (long long)ts.tv_nsec, (long long)to.ticks);
+		zexpect_true(timespec_equal(&rem, &K_TS_NO_WAIT), "non-zero remainder {%lld, %lld}",
+			     (long long)rem.tv_sec, (long long)rem.tv_nsec);
 
-		TC_PRINT("timespec_to_timeout():\nts: {%lld, %lld} => to: {%lld}\n",
-			 (long long)ts.tv_sec, (long long)ts.tv_nsec, (long long)to.ticks);
+		TC_PRINT("timespec_to_timeout():\nts: {%lld, %lld} => to: {%lld}, rem: {%lld, "
+			 "%lld}\n",
+			 (long long)ts.tv_sec, (long long)ts.tv_nsec, (long long)to.ticks,
+			 (long long)rem.tv_sec, (long long)rem.tv_nsec);
 	}
 #endif
 }