Re: [PATCH v1] rust: time: fix as_micros_ceil() to round correctly for negative Delta

[FUJITA Tomonori <tomo@flapping.org>]

On Tue, 14 Jul 2026 11:56:58 +0100
"Gary Guo" <gary@garyguo.net> wrote:

> On Tue Jul 14, 2026 at 11:49 AM BST, FUJITA Tomonori wrote:
>> On Tue, 14 Jul 2026 12:38:03 +0200
>> Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
>>
>>> On Tue, Jul 14, 2026 at 12:16 PM FUJITA Tomonori <tomo@flapping.org> wrote:
>>>>
>>>> I can send a patch but as I recall, the last time I posted a patch
>>>> like that, Andreas was opposed to that kind approach?
>>>>
>>>> https://lore.kernel.org/rust-for-linux/20250701001809.496389-1-fujita.tomonori@gmail.com/
>>> 
>>> Ah, that explains why I had the feeling I already mentioned this in
>>> the past... Thanks for linking it! :)
>>> 
>>> My reading at the end of that thread was that he would open to it as
>>> long as the constants had a name or computed relative to something
>>> else, which is a good idea regardless, and I replied with agreement --
>>> so I don't think Andreas was completely opposed to doing so?
>>> 
>>> We should anyway be consistent about this treewide. What we have been
>>> doing (or at least my intention) was to document an example of each
>>> possible return path / edge case. That is, we don't want every single
>>> test in examples, but for instance here at the very least I would
>>> expect to see 1) a normal case, 2) a saturating case, 3) the behavior
>>> of that with negatives; but perhaps we don't want to have every single
>>> test we may have about each of those "groups".
>>
>> As I recall, the last time I posted a patch to make them constants,
>> Gary was opposed?
>>
>> https://lore.kernel.org/rust-for-linux/20260119233621.3465304-1-fujita.tomonori@gmail.com/
> 
> I'm okay having test cases for corner cases but they shouldn't be part of the
> API.

If I understand everyone's positions correctly:

- Andreas wanted the docs to avoid raw magic numbers.
- Gary didn't want to grow the public API with constants purely for
  documentation purposes.
- Miguel suggested doctests could show the boundary behavior, with the
  value declared locally inside the example.   

Here's a concreate attempt at from_micros():

diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
index 363e93cbb139..a60a248a372b 100644
--- a/rust/kernel/time.rs
+++ b/rust/kernel/time.rs
@@ -388,6 +388,24 @@ pub const fn from_nanos(nanos: i64) -> Self {
     /// The `micros` can range from -9_223_372_036_854_775 to 9_223_372_036_854_775.
     /// If `micros` is outside this range, `i64::MIN` is used for negative values,
     /// and `i64::MAX` is used for positive values due to saturation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::time::{Delta, NSEC_PER_USEC};
+    ///
+    /// assert_eq!(Delta::from_micros(1).as_nanos(), 1_000);
+    ///
+    /// // The boundary of the representable range: does not saturate.
+    /// const MAX_MICROS: i64 = 9_223_372_036_854_775;
+    /// assert_eq!(Delta::from_micros(MAX_MICROS).as_nanos(), MAX_MICROS * NSEC_PER_USEC);
+    ///
+    /// // One past the boundary: saturates.
+    /// assert_eq!(Delta::from_micros(MAX_MICROS + 1), Delta::from_nanos(i64::MAX));
+    ///
+    /// // Negative values.
+    /// assert_eq!(Delta::from_micros(-1).as_nanos(), -1_000);
+    /// ```
     #[inline]
     pub const fn from_micros(micros: i64) -> Self {
         Self {


Can we agree on something like this?