[PATCH v2 3/8] rust: hrtimer: Add HrTimerCallbackContext and ::forward()
From: Lyude Paul
Date: Tue Apr 15 2025 - 15:51:53 EST
With Linux's hrtimer API, there's a number of methods that can only be
called in two situations:
* When we have exclusive access to the hrtimer and it is not currently
active
* When we're within the context of an hrtimer callback context
This commit handles the second situation and implements hrtimer_forward()
support in the context of a timer callback. We do this by introducing a
HrTimerCallbackContext type which is provided to users during the
RawHrTimerCallback::run() callback, and then add a forward() function to
the type.
Signed-off-by: Lyude Paul <lyude@xxxxxxxxxx>
---
V2:
* Improve SAFETY comments for HrTimerCallbackContext uses (I forgot to
mention that we're within RawHrTimerCallback::run()
* Split forward into forward() and raw_forward() since we're going to have
two contexts that we can call forward() from now.
* Clarify contexts in which certain hrtimer methods can be called.
* Make sure that we use a mutable reference for forward() here - just in
case :).
* Rename interval to duration
Signed-off-by: Lyude Paul <lyude@xxxxxxxxxx>
---
rust/kernel/time/hrtimer.rs | 51 +++++++++++++++++++++++++++--
rust/kernel/time/hrtimer/arc.rs | 9 ++++-
rust/kernel/time/hrtimer/pin.rs | 9 ++++-
rust/kernel/time/hrtimer/pin_mut.rs | 11 +++++--
rust/kernel/time/hrtimer/tbox.rs | 9 ++++-
5 files changed, 82 insertions(+), 7 deletions(-)
diff --git a/rust/kernel/time/hrtimer.rs b/rust/kernel/time/hrtimer.rs
index aadae8666f7ea..507fff67f8ab2 100644
--- a/rust/kernel/time/hrtimer.rs
+++ b/rust/kernel/time/hrtimer.rs
@@ -73,7 +73,7 @@
time::{Delta, Instant},
types::Opaque,
};
-use core::marker::PhantomData;
+use core::{marker::PhantomData, ptr::NonNull};
use pin_init::PinInit;
/// A timer backed by a C `struct hrtimer`.
@@ -314,7 +314,10 @@ 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<T>(
+ this: <Self::Pointer<'_> as RawHrTimerCallback>::CallbackTarget<'_>,
+ ctx: HrTimerCallbackContext<'_, T>,
+ ) -> HrTimerRestart
where
Self: Sized;
}
@@ -507,6 +510,50 @@ fn into_c(self) -> bindings::hrtimer_mode {
}
}
+/// 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>(NonNull<HrTimer<T>>, PhantomData<&'a ()>);
+
+impl<'a, 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`].
+ 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`
+ Self(unsafe { NonNull::new_unchecked(timer) }, PhantomData)
+ }
+
+ /// Forward the timer expiry so it expires at `duration` after `now`.
+ ///
+ /// Note that this does not requeue the timer, it simply updates its expiry value. It returns
+ /// the number of overruns that have occurred as a result of the expiry change.
+ pub fn forward(&mut self, now: Instant, duration: 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, duration) }
+ }
+}
+
/// Use to implement the [`HasHrTimer<T>`] trait.
///
/// See [`module`] documentation for an example.
diff --git a/rust/kernel/time/hrtimer/arc.rs b/rust/kernel/time/hrtimer/arc.rs
index acc70a0ea1be5..f30efd2d1094d 100644
--- a/rust/kernel/time/hrtimer/arc.rs
+++ b/rust/kernel/time/hrtimer/arc.rs
@@ -3,6 +3,7 @@
use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
+use super::HrTimerCallbackContext;
use super::HrTimerHandle;
use super::HrTimerPointer;
use super::RawHrTimerCallback;
@@ -95,6 +96,12 @@ impl<T> RawHrTimerCallback for Arc<T>
// allocation from other `Arc` clones.
let receiver = unsafe { ArcBorrow::from_raw(data_ptr) };
- T::run(receiver).into_c()
+ // SAFETY:
+ // - By C API contract `timer_ptr` is the pointer that we passed when queuing the timer, so
+ // it is a valid pointer to a `HrTimer<T>` embedded in a `T`.
+ // - We are within `RawHrTimerCallback::run`
+ let context = unsafe { HrTimerCallbackContext::from_raw(timer_ptr) };
+
+ T::run(receiver, context).into_c()
}
}
diff --git a/rust/kernel/time/hrtimer/pin.rs b/rust/kernel/time/hrtimer/pin.rs
index dba22d11a95f5..c694a96fcd9d5 100644
--- a/rust/kernel/time/hrtimer/pin.rs
+++ b/rust/kernel/time/hrtimer/pin.rs
@@ -3,6 +3,7 @@
use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
+use super::HrTimerCallbackContext;
use super::HrTimerHandle;
use super::RawHrTimerCallback;
use super::UnsafeHrTimerPointer;
@@ -99,6 +100,12 @@ impl<'a, T> RawHrTimerCallback for Pin<&'a T>
// here.
let receiver_pin = unsafe { Pin::new_unchecked(receiver_ref) };
- T::run(receiver_pin).into_c()
+ // SAFETY:
+ // - By C API contract `timer_ptr` is the pointer that we passed when queuing the timer, so
+ // it is a valid pointer to a `HrTimer<T>` embedded in a `T`.
+ // - We are within `RawHrTimerCallback::run`
+ let context = unsafe { HrTimerCallbackContext::from_raw(timer_ptr) };
+
+ T::run(receiver_pin, context).into_c()
}
}
diff --git a/rust/kernel/time/hrtimer/pin_mut.rs b/rust/kernel/time/hrtimer/pin_mut.rs
index aeff8e102e1dc..82242c79ee433 100644
--- a/rust/kernel/time/hrtimer/pin_mut.rs
+++ b/rust/kernel/time/hrtimer/pin_mut.rs
@@ -1,7 +1,8 @@
// SPDX-License-Identifier: GPL-2.0
use super::{
- HasHrTimer, HrTimer, HrTimerCallback, HrTimerHandle, RawHrTimerCallback, UnsafeHrTimerPointer,
+ HasHrTimer, HrTimer, HrTimerCallback, HrTimerCallbackContext, HrTimerHandle,
+ RawHrTimerCallback, UnsafeHrTimerPointer,
};
use crate::time::Instant;
use core::{marker::PhantomData, pin::Pin, ptr::NonNull};
@@ -103,6 +104,12 @@ impl<'a, T> RawHrTimerCallback for Pin<&'a mut T>
// here.
let receiver_pin = unsafe { Pin::new_unchecked(receiver_ref) };
- T::run(receiver_pin).into_c()
+ // SAFETY:
+ // - By C API contract `timer_ptr` is the pointer that we passed when queuing the timer, so
+ // it is a valid pointer to a `HrTimer<T>` embedded in a `T`.
+ // - We are within `RawHrTimerCallback::run`
+ let context = unsafe { HrTimerCallbackContext::from_raw(timer_ptr) };
+
+ T::run(receiver_pin, context).into_c()
}
}
diff --git a/rust/kernel/time/hrtimer/tbox.rs b/rust/kernel/time/hrtimer/tbox.rs
index 3df4e359e9bb0..c5c952721cee2 100644
--- a/rust/kernel/time/hrtimer/tbox.rs
+++ b/rust/kernel/time/hrtimer/tbox.rs
@@ -3,6 +3,7 @@
use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
+use super::HrTimerCallbackContext;
use super::HrTimerHandle;
use super::HrTimerPointer;
use super::RawHrTimerCallback;
@@ -115,6 +116,12 @@ impl<T, A> RawHrTimerCallback for Pin<Box<T, A>>
// `data_ptr` exist.
let data_mut_ref = unsafe { Pin::new_unchecked(&mut *data_ptr) };
- T::run(data_mut_ref).into_c()
+ // SAFETY:
+ // - By C API contract `timer_ptr` is the pointer that we passed when queuing the timer, so
+ // it is a valid pointer to a `HrTimer<T>` embedded in a `T`.
+ // - We are within `RawHrTimerCallback::run`
+ let context = unsafe { HrTimerCallbackContext::from_raw(timer_ptr) };
+
+ T::run(data_mut_ref, context).into_c()
}
}
--
2.48.1