[PATCH v1 0/2] Add Delta::to_jiffies_timeout() with tests

[PATCH v1 0/2] Add Delta::to_jiffies_timeout() with tests

[FUJITA Tomonori]

From: FUJITA Tomonori <fujita.tomonori@gmail.com>

The first patch is new. It adds an example and a KUnit test for
Delta::as_millis_ceil(), which Miguel asked for [1].

The second patch was previously posted as patch 4 of [2]; patches 1-3
of that series have been applied. It has been reworked to fix the bug
Miguel reported [1]: on 32 bit with HZ=1000, to_jiffies_timeout()
could return a value larger than MAX_JIFFY_OFFSET.

Both patches follow the format agreed in [3]: the examples show the
behaviour, while the boundary inputs live in `#[test]` KUnit tests, with the
magic numbers as named constants local to the test module rather than part
of the exported API. 

[1] https://lore.kernel.org/rust-for-linux/CANiq72kHP1s7bGr4=xfJGR8KY=aUpjOB4OwLEG5E=TKULXg5Rg@mail.gmail.com/
[2] https://lore.kernel.org/rust-for-linux/20260808062839.1159990-1-tomo@flapping.org/
[3] https://lore.kernel.org/rust-for-linux/874ihxgxy0.fsf@kernel.org/

FUJITA Tomonori (2):
  rust: time: add example and KUnit test for Delta::as_millis_ceil()
  rust: time: add Delta::to_jiffies_timeout() for timeout conversion

 rust/kernel/Kconfig.test |  10 ++++
 rust/kernel/time.rs      | 108 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+)


base-commit: 8fe5e5f62bdb9660999449a4b5eaebcc37d7f842
-- 
2.43.0

[PATCH v1 1/2] rust: time: add example and KUnit test for Delta::as_millis_ceil()

[FUJITA Tomonori]

From: FUJITA Tomonori <fujita.tomonori@gmail.com>

Add an example showing that the value is rounded towards positive
infinity, for both positive and negative spans.

as_millis_ceil() uses the same idiom as as_micros_ceil(), which dropped
the rounding bias near i64::MAX before commit ec90dfcf05f0 ("rust: time:
fix as_micros_ceil() rounding near i64::MAX"), so add a KUnit test for
the i64::MAX and i64::MIN extremes.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
 rust/kernel/Kconfig.test | 10 ++++++++++
 rust/kernel/time.rs      | 42 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/rust/kernel/Kconfig.test b/rust/kernel/Kconfig.test
index e6a5c7a795f0..0087749995d2 100644
--- a/rust/kernel/Kconfig.test
+++ b/rust/kernel/Kconfig.test
@@ -83,4 +83,14 @@ config RUST_BITFIELD_KUNIT_TEST
 
 	  If unsure, say N.
 
+config RUST_TIME_KUNIT_TEST
+	bool "KUnit tests for the Rust time API" if !KUNIT_ALL_TESTS
+	default KUNIT_ALL_TESTS
+	help
+	  This option enables KUnit tests for the Rust time API.
+	  These are only for development and testing, not for regular
+	  kernel use cases.
+
+	  If unsure, say N.
+
 endif
diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
index 6c0a5e8090d0..b0b43ad3aa47 100644
--- a/rust/kernel/time.rs
+++ b/rust/kernel/time.rs
@@ -530,6 +530,21 @@ pub fn as_millis(self) -> i64 {
 
     /// Return the smallest number of milliseconds greater than or equal
     /// to the value in the [`Delta`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::time::Delta;
+    ///
+    /// // Whole milliseconds are returned as-is.
+    /// assert_eq!(Delta::from_millis(2).as_millis_ceil(), 2);
+    /// assert_eq!(Delta::from_nanos(1_000_000).as_millis_ceil(), 1);
+    /// assert_eq!(Delta::from_nanos(-1_000_000).as_millis_ceil(), -1);
+    ///
+    /// // Anything else is rounded towards positive infinity.
+    /// assert_eq!(Delta::from_nanos(1_000_001).as_millis_ceil(), 2);
+    /// assert_eq!(Delta::from_nanos(-1_000_001).as_millis_ceil(), -1);
+    /// ```
     #[inline]
     pub fn as_millis_ceil(self) -> i64 {
         // Only positive values need to be rounded up: truncating division already
@@ -580,3 +595,30 @@ pub fn rem_nanos(self, dividend: i32) -> Self {
         }
     }
 }
+
+#[cfg(CONFIG_RUST_TIME_KUNIT_TEST)]
+#[macros::kunit_tests(rust_kernel_time)]
+mod tests {
+    use super::*;
+
+    /// `i64::MAX` nanoseconds in milliseconds, rounded towards positive infinity.
+    const MAX_MILLIS_CEIL: i64 = 9_223_372_036_855;
+
+    /// `i64::MIN` nanoseconds in milliseconds, rounded towards positive infinity.
+    const MIN_MILLIS_CEIL: i64 = -9_223_372_036_854;
+
+    #[test]
+    fn as_millis_ceil_extremes() {
+        // The rounding bias must survive near `i64::MAX`.
+        assert_eq!(
+            Delta::from_nanos(i64::MAX).as_millis_ceil(),
+            MAX_MILLIS_CEIL
+        );
+
+        // No bias is applied to negative values, so `i64::MIN` cannot overflow.
+        assert_eq!(
+            Delta::from_nanos(i64::MIN).as_millis_ceil(),
+            MIN_MILLIS_CEIL
+        );
+    }
+}
-- 
2.43.0

[PATCH v1 2/2] rust: time: add Delta::to_jiffies_timeout() for timeout conversion

[FUJITA Tomonori]

From: FUJITA Tomonori <fujita.tomonori@gmail.com>

Add Delta<Nsec>::to_jiffies_timeout() conversion. Unless the result
saturates, the value is rounded up, so the resulting timeout is never
shorter than the requested span.

The result saturates at zero jiffies for a negative span, i.e. an
immediate timeout, and at the kernel's MAX_JIFFY_OFFSET "wait forever"
value for a span that is too large.

Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
 rust/kernel/time.rs | 66 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
index b0b43ad3aa47..4ec1748c2602 100644
--- a/rust/kernel/time.rs
+++ b/rust/kernel/time.rs
@@ -39,6 +39,10 @@
 /// The number of nanoseconds per second.
 pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64;
 
+/// The C side `MAX_JIFFY_OFFSET`, i.e. `((LONG_MAX >> 1) - 1)`, which the kernel
+/// treats as an infinite timeout.
+const MAX_JIFFY_OFFSET: isize = (isize::MAX >> 1) - 1;
+
 /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
 pub type Jiffies = crate::ffi::c_ulong;
 
@@ -569,6 +573,51 @@ pub fn as_millis_ceil(self) -> i64 {
         }
     }
 
+    /// Convert this span to a [`Delta<Jiffy>`] suitable for use as a timeout.
+    ///
+    /// Unless the result saturates, the value is rounded up to the next whole
+    /// jiffy, so the resulting timeout is never shorter than `self` (as
+    /// [`msecs_to_jiffies()`] does).
+    ///
+    /// The result saturates at zero jiffies for a negative span, i.e. an
+    /// immediate timeout, and at the kernel's [`MAX_JIFFY_OFFSET`] for a span
+    /// that is too large, which the C side treats as an infinite timeout.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::time::Delta;
+    ///
+    /// // A negative span is an immediate timeout.
+    /// assert_eq!(Delta::from_millis(-1).to_jiffies_timeout().as_jiffies(), 0);
+    ///
+    /// // A span shorter than a jiffy still waits, i.e. the timeout is never
+    /// // shorter than the span.
+    /// assert!(Delta::from_nanos(1).to_jiffies_timeout().as_jiffies() >= 1);
+    /// ```
+    ///
+    /// [`msecs_to_jiffies()`]: srctree/include/linux/jiffies.h
+    /// [`MAX_JIFFY_OFFSET`]: srctree/include/linux/jiffies.h
+    #[inline]
+    pub fn to_jiffies_timeout(self) -> Delta<Jiffy> {
+        let msecs = self.as_millis_ceil();
+
+        // CAST: `msecs` is clamped to `0..=c_uint::MAX`, so it is non-negative and
+        // fits in `c_uint`.
+        let msecs = msecs.clamp(0, i64::from(crate::ffi::c_uint::MAX)) as crate::ffi::c_uint;
+
+        // SAFETY: `__msecs_to_jiffies()` is always safe to call.
+        let jiffies = unsafe { bindings::__msecs_to_jiffies(msecs) };
+
+        // `__msecs_to_jiffies()` only saturates when its argument is negative as an
+        // `int`: with `HZ=1000` it returns `msecs` as-is, which exceeds
+        // `MAX_JIFFY_OFFSET` on 32 bit.
+        let jiffies = jiffies.min(MAX_JIFFY_OFFSET as crate::ffi::c_ulong);
+
+        // CAST: `jiffies` is clamped to `MAX_JIFFY_OFFSET`, which is `<= isize::MAX`.
+        Delta::<Jiffy>::from_jiffies(jiffies as isize)
+    }
+
     /// Return `self % dividend` where `dividend` is in nanoseconds.
     ///
     /// The kernel doesn't have any emulation for `s64 % s64` on 32 bit platforms, so this is
@@ -621,4 +670,21 @@ fn as_millis_ceil_extremes() {
             MIN_MILLIS_CEIL
         );
     }
+
+    #[test]
+    fn to_jiffies_timeout_saturates() {
+        // `__msecs_to_jiffies()` does not clamp its result for every `HZ` configuration,
+        // e.g. with `HZ=1000` it returns the millisecond value as-is, which exceeds
+        // `MAX_JIFFY_OFFSET` on 32 bit.
+        let max = Delta::from_millis(i64::from(i32::MAX)).to_jiffies_timeout();
+        assert!(max.as_jiffies() <= MAX_JIFFY_OFFSET);
+
+        // An overlong span is an infinite timeout.
+        let overlong = Delta::from_nanos(i64::MAX).to_jiffies_timeout();
+        assert_eq!(overlong.as_jiffies(), MAX_JIFFY_OFFSET);
+
+        // A negative span is an immediate timeout, however long it is.
+        let negative = Delta::from_nanos(i64::MIN).to_jiffies_timeout();
+        assert_eq!(negative.as_jiffies(), 0);
+    }
 }
-- 
2.43.0

Re: [PATCH v1 2/2] rust: time: add Delta::to_jiffies_timeout() for timeout conversion

[Gary Guo]

On Tue Aug 11, 2026 at 4:01 PM BST, FUJITA Tomonori wrote:
> From: FUJITA Tomonori <fujita.tomonori@gmail.com>
>
> Add Delta<Nsec>::to_jiffies_timeout() conversion. Unless the result
> saturates, the value is rounded up, so the resulting timeout is never
> shorter than the requested span.
>
> The result saturates at zero jiffies for a negative span, i.e. an
> immediate timeout, and at the kernel's MAX_JIFFY_OFFSET "wait forever"
> value for a span that is too large.
>
> Reviewed-by: Gary Guo <gary@garyguo.net>

You should drop old review tags given this has been changed non trivially.

> Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> ---
>  rust/kernel/time.rs | 66 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 66 insertions(+)
>
> diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
> index b0b43ad3aa47..4ec1748c2602 100644
> --- a/rust/kernel/time.rs
> +++ b/rust/kernel/time.rs
> @@ -39,6 +39,10 @@
>  /// The number of nanoseconds per second.
>  pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64;
>  
> +/// The C side `MAX_JIFFY_OFFSET`, i.e. `((LONG_MAX >> 1) - 1)`, which the kernel
> +/// treats as an infinite timeout.
> +const MAX_JIFFY_OFFSET: isize = (isize::MAX >> 1) - 1;
> +
>  /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
>  pub type Jiffies = crate::ffi::c_ulong;
>  
> @@ -569,6 +573,51 @@ pub fn as_millis_ceil(self) -> i64 {
>          }
>      }
>  
> +    /// Convert this span to a [`Delta<Jiffy>`] suitable for use as a timeout.
> +    ///
> +    /// Unless the result saturates, the value is rounded up to the next whole
> +    /// jiffy, so the resulting timeout is never shorter than `self` (as
> +    /// [`msecs_to_jiffies()`] does).
> +    ///
> +    /// The result saturates at zero jiffies for a negative span, i.e. an
> +    /// immediate timeout, and at the kernel's [`MAX_JIFFY_OFFSET`] for a span
> +    /// that is too large, which the C side treats as an infinite timeout.
> +    ///
> +    /// # Examples
> +    ///
> +    /// ```
> +    /// use kernel::time::Delta;
> +    ///
> +    /// // A negative span is an immediate timeout.
> +    /// assert_eq!(Delta::from_millis(-1).to_jiffies_timeout().as_jiffies(), 0);
> +    ///
> +    /// // A span shorter than a jiffy still waits, i.e. the timeout is never
> +    /// // shorter than the span.
> +    /// assert!(Delta::from_nanos(1).to_jiffies_timeout().as_jiffies() >= 1);
> +    /// ```
> +    ///
> +    /// [`msecs_to_jiffies()`]: srctree/include/linux/jiffies.h
> +    /// [`MAX_JIFFY_OFFSET`]: srctree/include/linux/jiffies.h
> +    #[inline]
> +    pub fn to_jiffies_timeout(self) -> Delta<Jiffy> {
> +        let msecs = self.as_millis_ceil();
> +
> +        // CAST: `msecs` is clamped to `0..=c_uint::MAX`, so it is non-negative and
> +        // fits in `c_uint`.
> +        let msecs = msecs.clamp(0, i64::from(crate::ffi::c_uint::MAX)) as crate::ffi::c_uint;
> +
> +        // SAFETY: `__msecs_to_jiffies()` is always safe to call.
> +        let jiffies = unsafe { bindings::__msecs_to_jiffies(msecs) };

As I mentioned in previous 2 versions, I don't think __msecs_to_jiffies should
be used for this. You're doing two rounding and saturation operations here.

If you do nsecs_to_jiffies64 and then clamp, you wouldn't run into any of these
boundary conditions.

Best,
Gary

> +
> +        // `__msecs_to_jiffies()` only saturates when its argument is negative as an
> +        // `int`: with `HZ=1000` it returns `msecs` as-is, which exceeds
> +        // `MAX_JIFFY_OFFSET` on 32 bit.
> +        let jiffies = jiffies.min(MAX_JIFFY_OFFSET as crate::ffi::c_ulong);
> +
> +        // CAST: `jiffies` is clamped to `MAX_JIFFY_OFFSET`, which is `<= isize::MAX`.
> +        Delta::<Jiffy>::from_jiffies(jiffies as isize)
> +    }
> +
>      /// Return `self % dividend` where `dividend` is in nanoseconds.
>      ///
>      /// The kernel doesn't have any emulation for `s64 % s64` on 32 bit platforms, so this is
> @@ -621,4 +670,21 @@ fn as_millis_ceil_extremes() {
>              MIN_MILLIS_CEIL
>          );
>      }
> +
> +    #[test]
> +    fn to_jiffies_timeout_saturates() {
> +        // `__msecs_to_jiffies()` does not clamp its result for every `HZ` configuration,
> +        // e.g. with `HZ=1000` it returns the millisecond value as-is, which exceeds
> +        // `MAX_JIFFY_OFFSET` on 32 bit.
> +        let max = Delta::from_millis(i64::from(i32::MAX)).to_jiffies_timeout();
> +        assert!(max.as_jiffies() <= MAX_JIFFY_OFFSET);
> +
> +        // An overlong span is an infinite timeout.
> +        let overlong = Delta::from_nanos(i64::MAX).to_jiffies_timeout();
> +        assert_eq!(overlong.as_jiffies(), MAX_JIFFY_OFFSET);
> +
> +        // A negative span is an immediate timeout, however long it is.
> +        let negative = Delta::from_nanos(i64::MIN).to_jiffies_timeout();
> +        assert_eq!(negative.as_jiffies(), 0);
> +    }
>  }

Re: [PATCH v1 2/2] rust: time: add Delta::to_jiffies_timeout() for timeout conversion

[FUJITA Tomonori]

On Tue, 11 Aug 2026 17:44:24 +0100
"Gary Guo" <gary@garyguo.net> wrote:

> On Tue Aug 11, 2026 at 4:01 PM BST, FUJITA Tomonori wrote:
>> From: FUJITA Tomonori <fujita.tomonori@gmail.com>
>>
>> Add Delta<Nsec>::to_jiffies_timeout() conversion. Unless the result
>> saturates, the value is rounded up, so the resulting timeout is never
>> shorter than the requested span.
>>
>> The result saturates at zero jiffies for a negative span, i.e. an
>> immediate timeout, and at the kernel's MAX_JIFFY_OFFSET "wait forever"
>> value for a span that is too large.
>>
>> Reviewed-by: Gary Guo <gary@garyguo.net>
> 
> You should drop old review tags given this has been changed non trivially.

Sorry about that.


>> +    #[inline]
>> +    pub fn to_jiffies_timeout(self) -> Delta<Jiffy> {
>> +        let msecs = self.as_millis_ceil();
>> +
>> +        // CAST: `msecs` is clamped to `0..=c_uint::MAX`, so it is non-negative and
>> +        // fits in `c_uint`.
>> +        let msecs = msecs.clamp(0, i64::from(crate::ffi::c_uint::MAX)) as crate::ffi::c_uint;
>> +
>> +        // SAFETY: `__msecs_to_jiffies()` is always safe to call.
>> +        let jiffies = unsafe { bindings::__msecs_to_jiffies(msecs) };
> 
> As I mentioned in previous 2 versions, I don't think __msecs_to_jiffies should
> be used for this. You're doing two rounding and saturation operations here.

Fair enough.

> If you do nsecs_to_jiffies64 and then clamp, you wouldn't run into any of these
> boundary conditions.

I think nsecs_to_jiffies64() has boundary conditions of its own that
the Rust side has to take care of:

u64 nsecs_to_jiffies64(u64 n)
{
#if (NSEC_PER_SEC % HZ) == 0
	/* Common case, HZ = 100, 128, 200, 250, 256, 500, 512, 1000 etc. */
	return div_u64(n, NSEC_PER_SEC / HZ);
#elif (HZ % 512) == 0
	/* overflow after 292 years if HZ = 1024 */
	return div_u64(n * HZ / 512, NSEC_PER_SEC / 512);
#else
	/*
	 * Generic case - optimized for cases where HZ is a multiple of 3.
	 * overflow after 64.99 years, exact for HZ = 60, 72, 90, 120 etc.
	 */
	return div_u64(n * 9, (9ull * NSEC_PER_SEC + HZ / 2) / HZ);
#endif
}

In the generic case (e.g. CONFIG_HZ_300), n * 9 can overflow and
return a small value so the Rust side has to clamp the Delta before
the call.

The boundaries move rather than go away.

I agree the double rounding should go, but doing the ceiling on the
Rust side will need a few rounds of review.

Miguel, you suggested landing the minimum set, e.g. the first 2 or
first 4 patches. Patches 1-3 are already in, so that leaves patch
4. Would you like to take this version, which clamps the result and
has a KUnit test that fails on arm with HZ=1000 without the clamp,
or should I hold it for early next cycle? Either is fine with me.

Re: [PATCH v1 2/2] rust: time: add Delta::to_jiffies_timeout() for timeout conversion

[Miguel Ojeda]

On Wed, Aug 12, 2026 at 2:05 AM FUJITA Tomonori <tomo@flapping.org> wrote:
>
> Miguel, you suggested landing the minimum set, e.g. the first 2 or
> first 4 patches. Patches 1-3 are already in, so that leaves patch
> 4. Would you like to take this version, which clamps the result and
> has a KUnit test that fails on arm with HZ=1000 without the clamp,
> or should I hold it for early next cycle? Either is fine with me.

Up to timekeeping, but it is very late and I think Andreas was already
on the fence of deferring everything even before this version.

But I appreciate that you reworked this very quickly as soon as I
found that issue -- thanks Tomo.

I am happy to give a tag or similar if needed next cycle for Gary's
use case etc., so it is not a problem.

If we were to actually take it, then I think that, generally speaking,
any version that works in all cases is to be strongly favored even if
it can be optimized/improved later, i.e. what I think matters the most
is agreeing on the documented contract, i.e. to agree on what we want
the function to actually do. Function bodies can always be improved
later.

Cheers,
Miguel