Merge tag 'rust-6.18' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux

Pull rust updates from Miguel Ojeda:
 "Toolchain and infrastructure:

   - Derive 'Zeroable' for all structs and unions generated by 'bindgen'
     where possible and corresponding cleanups. To do so, add the
     'pin-init' crate as a dependency to 'bindings' and 'uapi'.

     It also includes its first use in the 'cpufreq' module, with more
     to come in the next cycle.

   - Add warning to the 'rustdoc' target to detect broken 'srctree/'
     links and fix existing cases.

   - Remove support for unused (since v6.16) host '#[test]'s,
     simplifying the 'rusttest' target. Tests should generally run
     within KUnit.

  'kernel' crate:

   - Add 'ptr' module with a new 'Alignment' type, which is always a
     power of two and is used to validate that a given value is a valid
     alignment and to perform masking and alignment operations:

         // Checked at build time.
         assert_eq!(Alignment::new::<16>().as_usize(), 16);

         // Checked at runtime.
         assert_eq!(Alignment::new_checked(15), None);

         assert_eq!(Alignment::of::<u8>().log2(), 0);

         assert_eq!(0x25u8.align_down(Alignment::new::<0x10>()), 0x20);
         assert_eq!(0x5u8.align_up(Alignment::new::<0x10>()), Some(0x10));
         assert_eq!(u8::MAX.align_up(Alignment::new::<0x10>()), None);

     It also includes its first use in Nova.

   - Add 'core::mem::{align,size}_of{,_val}' to the prelude, matching
     Rust 1.80.0.

   - Keep going with the steps on our migration to the standard library
     'core::ffi::CStr' type (use 'kernel::{fmt, prelude::fmt!}' and use
     upstream method names).

   - 'error' module: improve 'Error::from_errno' and 'to_result'
     documentation, including examples/tests.

   - 'sync' module: extend 'aref' submodule documentation now that it
     exists, and more updates to complete the ongoing move of 'ARef' and
     'AlwaysRefCounted' to 'sync::aref'.

   - 'list' module: add an example/test for 'ListLinksSelfPtr' usage.

   - 'alloc' module:

      - Implement 'Box::pin_slice()', which constructs a pinned slice of
        elements.

      - Provide information about the minimum alignment guarantees of
        'Kmalloc', 'Vmalloc' and 'KVmalloc'.

      - Take minimum alignment guarantees of allocators for
        'ForeignOwnable' into account.

      - Remove the 'allocator_test' (including 'Cmalloc').

      - Add doctest for 'Vec::as_slice()'.

      - Constify various methods.

   - 'time' module:

      - Add methods on 'HrTimer' that can only be called with exclusive
        access to an unarmed timer, or from timer callback context.

      - Add arithmetic operations to 'Instant' and 'Delta'.

      - Add a few convenience and access methods to 'HrTimer' and
        'Instant'.

  'macros' crate:

   - Reduce collections in 'quote!' macro.

  And a few other cleanups and improvements"

* tag 'rust-6.18' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux: (58 commits)
  gpu: nova-core: use Alignment for alignment-related operations
  rust: add `Alignment` type
  rust: macros: reduce collections in `quote!` macro
  rust: acpi: use `core::ffi::CStr` method names
  rust: of: use `core::ffi::CStr` method names
  rust: net: use `core::ffi::CStr` method names
  rust: miscdevice: use `core::ffi::CStr` method names
  rust: kunit: use `core::ffi::CStr` method names
  rust: firmware: use `core::ffi::CStr` method names
  rust: drm: use `core::ffi::CStr` method names
  rust: cpufreq: use `core::ffi::CStr` method names
  rust: configfs: use `core::ffi::CStr` method names
  rust: auxiliary: use `core::ffi::CStr` method names
  drm/panic: use `core::ffi::CStr` method names
  rust: device: use `kernel::{fmt,prelude::fmt!}`
  rust: sync: use `kernel::{fmt,prelude::fmt!}`
  rust: seq_file: use `kernel::{fmt,prelude::fmt!}`
  rust: kunit: use `kernel::{fmt,prelude::fmt!}`
  rust: file: use `kernel::{fmt,prelude::fmt!}`
  rust: device: use `kernel::{fmt,prelude::fmt!}`
  ...

1 files changed, 149 insertions, 3 deletions

diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
index 144e3b57cc78..856d2d929a00 100644
--- a/rust/kernel/time/hrtimer.rs
+++ b/rust/kernel/time/hrtimer.rs
@@ -69,9 +69,14 @@
 
 use super::{ClockSource, Delta, Instant};
 use crate::{prelude::*, types::Opaque};
-use core::marker::PhantomData;
+use core::{marker::PhantomData, ptr::NonNull};
 use pin_init::PinInit;
 
+/// A type-alias to refer to the [`Instant<C>`] for a given `T` from [`HrTimer<T>`].
+///
+/// Where `C` is the [`ClockSource`] of the [`HrTimer`].
+pub type HrTimerInstant<T> = Instant<<<T as HasHrTimer<T>>::TimerMode as HrTimerMode>::Clock>;
+
 /// A timer backed by a C `struct hrtimer`.
 ///
 /// # Invariants
@@ -163,6 +168,84 @@ impl<T> HrTimer<T> {
         // handled on the C side.
         unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 }
     }
+
+    /// Forward the timer expiry for a given timer pointer.
+    ///
+    /// # Safety
+    ///
+    /// - `self_ptr` must point to a valid `Self`.
+    /// - The caller must either have exclusive access to the data pointed at by `self_ptr`, or be
+    ///   within the context of the timer callback.
+    #[inline]
+    unsafe fn raw_forward(self_ptr: *mut Self, now: HrTimerInstant<T>, interval: Delta) -> u64
+    where
+        T: HasHrTimer<T>,
+    {
+        // SAFETY:
+        // * The C API requirements for this function are fulfilled by our safety contract.
+        // * `self_ptr` is guaranteed to point to a valid `Self` via our safety contract
+        unsafe {
+            bindings::hrtimer_forward(Self::raw_get(self_ptr), now.as_nanos(), interval.as_nanos())
+        }
+    }
+
+    /// Conditionally forward the timer.
+    ///
+    /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
+    /// expired at or before `now`, this function forwards the timer by `interval` until the timer
+    /// expires after `now` and then returns the number of times the timer was forwarded by
+    /// `interval`.
+    ///
+    /// This function is mainly useful for timer types which can provide exclusive access to the
+    /// timer when the timer is not running. For forwarding the timer from within the timer callback
+    /// context, see [`HrTimerCallbackContext::forward()`].
+    ///
+    /// Returns the number of overruns that occurred as a result of the timer expiry change.
+    pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
+    where
+        T: HasHrTimer<T>,
+    {
+        // SAFETY: `raw_forward` does not move `Self`
+        let this = unsafe { self.get_unchecked_mut() };
+
+        // SAFETY: By existence of `Pin<&mut Self>`, the pointer passed to `raw_forward` points to a
+        // valid `Self` that we have exclusive access to.
+        unsafe { Self::raw_forward(this, now, interval) }
+    }
+
+    /// Conditionally forward the timer.
+    ///
+    /// This is a variant of [`forward()`](Self::forward) that uses an interval after the current
+    /// time of the base clock for the [`HrTimer`].
+    pub fn forward_now(self: Pin<&mut Self>, interval: Delta) -> u64
+    where
+        T: HasHrTimer<T>,
+    {
+        self.forward(HrTimerInstant::<T>::now(), interval)
+    }
+
+    /// Return the time expiry for this [`HrTimer`].
+    ///
+    /// This value should only be used as a snapshot, as the actual expiry time could change after
+    /// this function is called.
+    pub fn expires(&self) -> HrTimerInstant<T>
+    where
+        T: HasHrTimer<T>,
+    {
+        // SAFETY: `self` is an immutable reference and thus always points to a valid `HrTimer`.
+        let c_timer_ptr = unsafe { HrTimer::raw_get(self) };
+
+        // SAFETY:
+        // - Timers cannot have negative ktime_t values as their expiration time.
+        // - There's no actual locking here, a racy read is fine and expected
+        unsafe {
+            Instant::from_ktime(
+                // This `read_volatile` is intended to correspond to a READ_ONCE call.
+                // FIXME(read_once): Replace with `read_once` when available on the Rust side.
+                core::ptr::read_volatile(&raw const ((*c_timer_ptr).node.expires)),
+            )
+        }
+    }
 }
 
 /// Implemented by pointer types that point to structs that contain a [`HrTimer`].
@@ -300,9 +383,13 @@ pub trait HrTimerCallback {
     type Pointer<'a>: RawHrTimerCallback;
 
     /// Called by the timer logic when the timer fires.
-    fn run(this: <Self::Pointer<'_> as RawHrTimerCallback>::CallbackTarget<'_>) -> HrTimerRestart
+    fn run(
+        this: <Self::Pointer<'_> as RawHrTimerCallback>::CallbackTarget<'_>,
+        ctx: HrTimerCallbackContext<'_, Self>,
+    ) -> HrTimerRestart
     where
-        Self: Sized;
+        Self: Sized,
+        Self: HasHrTimer<Self>;
 }
 
 /// A handle representing a potentially running timer.
@@ -324,6 +411,8 @@ pub unsafe trait HrTimerHandle {
     /// Note that the timer might be started by a concurrent start operation. If
     /// so, the timer might not be in the **stopped** state when this function
     /// returns.
+    ///
+    /// Returns `true` if the timer was running.
     fn cancel(&mut self) -> bool;
 }
 
@@ -585,6 +674,63 @@ impl<C: ClockSource> HrTimerMode for RelativePinnedHardMode<C> {
     type Expires = Delta;
 }
 
+/// Privileged smart-pointer for a [`HrTimer`] callback context.
+///
+/// Many [`HrTimer`] methods can only be called in two situations:
+///
+/// * When the caller has exclusive access to the `HrTimer` and the `HrTimer` is guaranteed not to
+///   be running.
+/// * From within the context of an `HrTimer`'s callback method.
+///
+/// This type provides access to said methods from within a timer callback context.
+///
+/// # Invariants
+///
+/// * The existence of this type means the caller is currently within the callback for an
+///   [`HrTimer`].
+/// * `self.0` always points to a live instance of [`HrTimer<T>`].
+pub struct HrTimerCallbackContext<'a, T: HasHrTimer<T>>(NonNull<HrTimer<T>>, PhantomData<&'a ()>);
+
+impl<'a, T: HasHrTimer<T>> HrTimerCallbackContext<'a, T> {
+    /// Create a new [`HrTimerCallbackContext`].
+    ///
+    /// # Safety
+    ///
+    /// This function relies on the caller being within the context of a timer callback, so it must
+    /// not be used anywhere except for within implementations of [`RawHrTimerCallback::run`]. The
+    /// caller promises that `timer` points to a valid initialized instance of
+    /// [`bindings::hrtimer`].
+    ///
+    /// The returned `Self` must not outlive the function context of [`RawHrTimerCallback::run`]
+    /// where this function is called.
+    pub(crate) unsafe fn from_raw(timer: *mut HrTimer<T>) -> Self {
+        // SAFETY: The caller guarantees `timer` is a valid pointer to an initialized
+        // `bindings::hrtimer`
+        // INVARIANT: Our safety contract ensures that we're within the context of a timer callback
+        // and that `timer` points to a live instance of `HrTimer<T>`.
+        Self(unsafe { NonNull::new_unchecked(timer) }, PhantomData)
+    }
+
+    /// Conditionally forward the timer.
+    ///
+    /// This function is identical to [`HrTimer::forward()`] except that it may only be used from
+    /// within the context of a [`HrTimer`] callback.
+    pub fn forward(&mut self, now: HrTimerInstant<T>, interval: Delta) -> u64 {
+        // SAFETY:
+        // - We are guaranteed to be within the context of a timer callback by our type invariants
+        // - By our type invariants, `self.0` always points to a valid `HrTimer<T>`
+        unsafe { HrTimer::<T>::raw_forward(self.0.as_ptr(), now, interval) }
+    }
+
+    /// Conditionally forward the timer.
+    ///
+    /// This is a variant of [`HrTimerCallbackContext::forward()`] that uses an interval after the
+    /// current time of the base clock for the [`HrTimer`].
+    pub fn forward_now(&mut self, duration: Delta) -> u64 {
+        self.forward(HrTimerInstant::<T>::now(), duration)
+    }
+}
+
 /// Use to implement the [`HasHrTimer<T>`] trait.
 ///
 /// See [`module`] documentation for an example.