fix: get muldiv to be private and handle overflow properly, do freq checks

- Move rt_muldiv_u64 out of rttypes into private clock_time_internal
  with truncated overflow and an optional overflow out-parameter
- Name the helper rt_clock_time_muldiv_u64 and include its .c from
  clock_time_core.c so IDE projects do not need a new source entry
- Add rt_clock_time_get_res() and reject zero-frequency paths in
  clock_getres, timer_gettime, timer_settime, and soft RTC
- Clamp or error on overflowed/out-of-range delay conversions in
  hrtimer and POSIX timer reload paths
- Keep one-shot timer intervals from being rounded up to a 1-tick
  reload, and clamp timer_gettime remain time after expiry
- Update clock_time core documentation for resolution and overflow

Author: lygstate

components/drivers/clock_time/clock_boottime.c

@@ -11,6 +11,8 @@
 #include <drivers/clock_time.h>
 #include <sys/time.h>
 
+#include "clock_time_internal.h"
+
 rt_err_t rt_clock_boottime_get_us(struct timeval *tv)
 {
     rt_uint64_t cnt;
@@ -26,7 +28,7 @@ rt_err_t rt_clock_boottime_get_us(struct timeval *tv)
     }
 
     tv->tv_sec = (time_t)(cnt / freq);
-    tv->tv_usec = rt_muldiv_u64(cnt % freq, MICROSECOND_PER_SECOND, freq, NULL);
+    tv->tv_usec = rt_clock_time_muldiv_u64(cnt % freq, MICROSECOND_PER_SECOND, freq, RT_NULL, RT_NULL);
 
     return RT_EOK;
 }
@@ -65,7 +67,7 @@ rt_err_t rt_clock_boottime_get_ns(struct timespec *ts)
     }
 
     ts->tv_sec = (time_t)(cnt / freq);
-    ts->tv_nsec = rt_muldiv_u64(cnt % freq, NANOSECOND_PER_SECOND, freq, NULL);
+    ts->tv_nsec = rt_clock_time_muldiv_u64(cnt % freq, NANOSECOND_PER_SECOND, freq, RT_NULL, RT_NULL);
 
     return RT_EOK;
 }

components/drivers/clock_time/clock_hrtimer.c

@@ -14,6 +14,7 @@
 #include <sys/time.h>
 
 #include <drivers/clock_time.h>
+#include "clock_time_internal.h"
 
 #define DBG_SECTION_NAME               "drv.clock_time"
 #define DBG_LEVEL                      DBG_INFO
@@ -52,17 +53,27 @@ static rt_tick_t _hrtimer_cnt_to_tick(rt_uint64_t cnt)
     rt_uint64_t freq = rt_clock_hrtimer_getfrq();
     rt_uint64_t rem = 0;
     rt_uint64_t tick;
+    rt_bool_t overflow = RT_FALSE;
 
     if (freq == 0)
     {
         return 0;
     }
 
-    tick = rt_muldiv_u64(cnt, RT_TICK_PER_SECOND, freq, &rem);
+    tick = rt_clock_time_muldiv_u64(cnt, RT_TICK_PER_SECOND, freq, &rem, &overflow);
+    if (overflow)
+    {
+        /* soft-timer path: clamp overflowed delay into the legal half-range */
+        return (rt_tick_t)(RT_TICK_MAX / 2 - 1);
+    }
     if (rem != 0)
     {
         tick += 1; /* round up so a non-zero cnt never collapses to a 0-tick timeout */
     }
+    if (tick >= (RT_TICK_MAX / 2))
+    {
+        tick = RT_TICK_MAX / 2 - 1;
+    }
     if (tick == 0)
     {
         tick = 1; /* at least one tick */
@@ -115,13 +126,30 @@ static rt_uint64_t _cnt_convert(rt_tick_t cnt)
 {
     rt_uint64_t rtn = 0;
     rt_tick_t count = cnt - _clock_time_get_cnt();
+    rt_uint64_t src_freq;
+    rt_uint64_t event_freq;
+    rt_bool_t overflow = RT_FALSE;
 
     if (count > (RT_TICK_MAX / 2))
     {
         return 0;
     }
 
-    rtn = rt_muldiv_u64(count, rt_clock_hrtimer_getfrq(), rt_clock_time_get_freq(), NULL);
+    src_freq = rt_clock_time_get_freq();
+    event_freq = rt_clock_hrtimer_getfrq();
+    if ((src_freq == 0) || (event_freq == 0))
+    {
+        /* frequency unavailable: never return 0, or the caller treats the
+         * timer as already expired and may busy-loop reprocessing it */
+        return 1;
+    }
+
+    rtn = rt_clock_time_muldiv_u64(count, event_freq, src_freq, RT_NULL, &overflow);
+    if (overflow)
+    {
+        /* keep a long delay; truncated overflow could schedule too soon */
+        return RT_UINT64_MAX;
+    }
     return rtn == 0 ? 1 : rtn;
 }
 
@@ -408,18 +436,33 @@ rt_err_t rt_clock_hrtimer_sleep(struct rt_clock_hrtimer *timer, rt_tick_t cnt)
 
 rt_err_t rt_clock_hrtimer_ndelay(struct rt_clock_hrtimer *timer, rt_uint64_t ns)
 {
-    rt_tick_t cputimer_tick = (rt_tick_t)rt_muldiv_u64(ns, rt_clock_time_get_freq(), NANOSECOND_PER_SECOND, NULL);
+    rt_uint64_t count = rt_clock_time_ns_to_counter(ns);
 
-    return rt_clock_hrtimer_sleep(timer, cputimer_tick);
+    if ((count == 0) || (count >= (RT_TICK_MAX / 2)))
+    {
+        return -RT_EINVAL;
+    }
+
+    return rt_clock_hrtimer_sleep(timer, (rt_tick_t)count);
 }
 
 rt_err_t rt_clock_hrtimer_udelay(struct rt_clock_hrtimer *timer, rt_uint64_t us)
 {
+    if (us > (RT_UINT64_MAX / 1000))
+    {
+        return -RT_EINVAL;
+    }
+
     return rt_clock_hrtimer_ndelay(timer, us * 1000);
 }
 
 rt_err_t rt_clock_hrtimer_mdelay(struct rt_clock_hrtimer *timer, rt_uint64_t ms)
 {
+    if (ms > (RT_UINT64_MAX / 1000000))
+    {
+        return -RT_EINVAL;
+    }
+
     return rt_clock_hrtimer_ndelay(timer, ms * 1000000);
 }
 

components/drivers/clock_time/clock_time_core.c

@@ -13,6 +13,14 @@
 #include <rtdevice.h>
 
 #include <drivers/clock_time.h>
+#include "clock_time_internal.h"
+/*
+ * The muldiv implementation is textually included so it compiles as part of
+ * this translation unit. Keil/IAR project files list clock_time sources one
+ * by one; including the .c here keeps clock_time_internal.c out of build
+ * scripts and IDE projects while producing a single definition.
+ */
+#include "clock_time_internal.c"
 
 static rt_uint64_t _clock_time_tick_get_freq(struct rt_clock_time_device *dev)
 {
@@ -150,28 +158,55 @@ rt_uint64_t rt_clock_time_get_event_freq(void)
     return event->ops->get_freq(event);
 }
 
+/**
+ * @brief Get the default clock source resolution in nanoseconds.
+ *
+ * @return Non-zero resolution on success, or 0 when frequency is unavailable.
+ */
+rt_uint64_t rt_clock_time_get_res(void)
+{
+    rt_uint64_t freq = rt_clock_time_get_freq();
+    rt_uint64_t res;
+
+    if (freq == 0)
+    {
+        return 0;
+    }
+
+    res = NANOSECOND_PER_SECOND / freq;
+    return res == 0 ? 1 : res;
+}
+
 rt_uint64_t rt_clock_time_counter_to_ns(rt_uint64_t cnt)
 {
     rt_uint64_t freq = rt_clock_time_get_freq();
+    rt_bool_t overflow = RT_FALSE;
+    rt_uint64_t ns;
 
     if (freq == 0)
     {
         return 0;
     }
 
-    return rt_muldiv_u64(cnt, NANOSECOND_PER_SECOND, freq, NULL);
+    ns = rt_clock_time_muldiv_u64(cnt, NANOSECOND_PER_SECOND, freq, RT_NULL, &overflow);
+    /* Call-site policy: report unrepresentable results as the max value. */
+    return overflow ? RT_UINT64_MAX : ns;
 }
 
 rt_uint64_t rt_clock_time_ns_to_counter(rt_uint64_t ns)
 {
     rt_uint64_t freq = rt_clock_time_get_freq();
+    rt_bool_t overflow = RT_FALSE;
+    rt_uint64_t cnt;
 
     if (freq == 0)
     {
         return 0;
     }
 
-    return rt_muldiv_u64(ns, freq, NANOSECOND_PER_SECOND, NULL);
+    cnt = rt_clock_time_muldiv_u64(ns, freq, NANOSECOND_PER_SECOND, RT_NULL, &overflow);
+    /* Call-site policy: report unrepresentable delays as the max value. */
+    return overflow ? RT_UINT64_MAX : cnt;
 }
 
 rt_err_t rt_clock_time_set_timeout(rt_uint64_t delta)

src/rttypes.c …drivers/clock_time/clock_time_internal.csrc/rttypes.c renamed to components/drivers/clock_time/clock_time_internal.c src/rttypes.c renamed to components/drivers/clock_time/clock_time_internal.c

@@ -1,18 +1,24 @@
 /*
- * Copyright (c) 2006-2025, RT-Thread Development Team
+ * Copyright (c) 2006-2026, RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author        Notes
  * 2025-09-25     Yonggang Luo  the first version
+ * 2026-07-14     Yonggang Luo  keep muldiv private to clock_time
  */
 
-#include "rttypes.h"
-#include <rtdef.h>
+#include "clock_time_internal.h"
 
-/* Function to count leading zeros for an rt_uint64_t */
-static rt_int32_t u64_count_leading_zeros(rt_uint64_t n)
+/**
+ * @brief Count leading zero bits in a 64-bit value.
+ *
+ * @param n Input value.
+ *
+ * @return Number of leading zero bits; 64 when @p n is 0.
+ */
+static rt_int32_t _u64_count_leading_zeros(rt_uint64_t n)
 {
     if (n == 0)
     {
@@ -22,8 +28,7 @@ static rt_int32_t u64_count_leading_zeros(rt_uint64_t n)
     return __builtin_clzll(n);
 #else
     rt_int32_t count = 0;
-    rt_uint64_t mask =
-        1ULL << (sizeof(rt_uint64_t) * 8 - 1); // Most significant bit
+    rt_uint64_t mask = 1ULL << (sizeof(rt_uint64_t) * 8 - 1);
 
     while ((n & mask) == 0)
     {
@@ -35,19 +40,29 @@ static rt_int32_t u64_count_leading_zeros(rt_uint64_t n)
 }
 
 /**
+ * @brief Narrowing division of a 128-bit numerator by a 64-bit denominator.
+ *
+ * Algorithm from:
  * https://ridiculousfish.com/blog/posts/labor-of-division-episode-v.html
- * Perform a narrowing division: 128 / 64 -> 64, and 64 / 32 -> 32.
- * The dividend's low and high words are given by \p numhi and \p numlo,
- * respectively. The divisor is given by \p den.
- * \return the quotient, and the remainder by reference in \p r, if not null.
- * If the quotient would require more than 64 bits, or if denom is 0, then
- * return the max value for both quotient and remainder.
  *
- * These functions are released into the public domain, where applicable, or the
- * CC0 license.
+ * The dividend is formed by high word @p numhi and low word @p numlo.
+ * When @p den is 0, both the quotient and the optional remainder are 0 and
+ * @p overflow is set. When the full quotient needs more than 64 bits,
+ * @c numhi %= den truncates to a 64-bit quotient and @p overflow is set.
+ *
+ * These functions are released into the public domain, where applicable, or
+ * the CC0 license.
+ *
+ * @param numhi    High 64 bits of the numerator.
+ * @param numlo    Low 64 bits of the numerator.
+ * @param den      Denominator.
+ * @param r        Optional remainder output; may be @c RT_NULL.
+ * @param overflow Optional overflow flag; may be @c RT_NULL.
+ *
+ * @return The truncated 64-bit quotient.
  */
-static rt_uint64_t u128_div_u64_u64(rt_uint64_t numhi, rt_uint64_t numlo, rt_uint64_t den,
-                                    rt_uint64_t *r)
+static rt_uint64_t _u128_div_u64_u64(rt_uint64_t numhi, rt_uint64_t numlo, rt_uint64_t den,
+                                     rt_uint64_t *r, rt_bool_t *overflow)
 {
     /*
      * We work in base 2**32.
@@ -84,8 +99,34 @@ static rt_uint64_t u128_div_u64_u64(rt_uint64_t numhi, rt_uint64_t numlo, rt_uin
     rt_uint64_t c1;
     rt_uint64_t c2;
 
-    /* Check for overflow and divide by 0. */
-    numhi = numhi % den;
+    if (overflow != RT_NULL)
+    {
+        *overflow = RT_FALSE;
+    }
+
+    /* Divide by 0: treat as a zero result. */
+    if (den == 0)
+    {
+        if (r != RT_NULL)
+        {
+            *r = 0;
+        }
+        if (overflow != RT_NULL)
+        {
+            *overflow = RT_TRUE;
+        }
+        return 0;
+    }
+
+    /* Truncate a wider-than-64-bit quotient to 64 bits. */
+    if (numhi >= den)
+    {
+        if (overflow != RT_NULL)
+        {
+            *overflow = RT_TRUE;
+        }
+        numhi = numhi % den;
+    }
 
     /*
      * Determine the normalization factor. We multiply den by this, so that its leading digit is at
@@ -96,7 +137,7 @@ static rt_uint64_t u128_div_u64_u64(rt_uint64_t numhi, rt_uint64_t numlo, rt_uin
      * by 64. The funny bitwise 'and' ensures that numlo does not get shifted into numhi if shift is 0.
      * clang 11 has an x86 codegen bug here: see LLVM bug 50118. The sequence below avoids it.
      */
-    shift = u64_count_leading_zeros(den);
+    shift = _u64_count_leading_zeros(den);
     den <<= shift;
     numhi <<= shift;
     numhi |= (numlo >> (-shift & 63)) & (-(rt_int64_t)shift >> 63);
@@ -137,16 +178,30 @@ static rt_uint64_t u128_div_u64_u64(rt_uint64_t numhi, rt_uint64_t numlo, rt_uin
     q0 = (rt_uint32_t)qhat;
 
     /* Return remainder if requested. */
-    if (r != NULL)
+    if (r != RT_NULL)
         *r = (rem * b + num0 - q0 * den) >> shift;
     return ((rt_uint64_t)q1 << 32) | q0;
 }
 
-rt_uint64_t rt_muldiv_u64(rt_uint64_t a, rt_uint64_t b, rt_uint64_t c, rt_uint64_t *r)
+rt_uint64_t rt_clock_time_muldiv_u64(rt_uint64_t a, rt_uint64_t b, rt_uint64_t c,
+                                     rt_uint64_t *r, rt_bool_t *overflow)
 {
     rt_uint64_t remainder = 0;
-    rt_uint64_t ret = 0;
-    if (c != 0) /* Handle division by zero. */
+    rt_uint64_t ret;
+
+    if (c == 0)
+    {
+        if (r != RT_NULL)
+        {
+            *r = 0;
+        }
+        if (overflow != RT_NULL)
+        {
+            *overflow = RT_TRUE;
+        }
+        return 0;
+    }
+
     {
         rt_uint64_t a_lo = a & 0xFFFFFFFF;
         rt_uint64_t a_hi = a >> 32;
@@ -163,9 +218,12 @@ rt_uint64_t rt_muldiv_u64(rt_uint64_t a, rt_uint64_t b, rt_uint64_t c, rt_uint64
 
         rt_uint64_t lo = (p0 & 0xFFFFFFFFULL) + ((carry & 0xFFFFFFFFULL) << 32);
         rt_uint64_t hi = p3 + (p1 >> 32) + (p2 >> 32) + (carry >> 32);
-        ret = u128_div_u64_u64(hi, lo, c, &remainder);
+        ret = _u128_div_u64_u64(hi, lo, c, &remainder, overflow);
     }
-    if (r)
+
+    if (r != RT_NULL)
+    {
         *r = remainder;
+    }
     return ret;
 }