dummy/linux-stable-mirror
1
0
Fork 1
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/ synced 2025-04-19 20:58:31 +09:00
Code Issues Packages Projects Releases Wiki Activity

Rust hrtimer API for v6.15

Browse Source 
Introduce Rust support for the `hrtimer` subsystem:
 
  - Add a way to use the `hrtimer` subsystem from Rust. Rust code can now set up
    intrusive timers without allocating when starting the timer.
 
  - Add support for `Pin<Box<_>>`, `Arc<_>`, `Pin<&_>` and `Pin<&mut _>` as
    pointer types for use with timer callbacks.
 
  - Add support for setting clock source and timer mode.
 
 `kernel` crate:
 
  - Add `Arc::as_ptr` for converting an `Arc` to a raw pointer. This is a
    dependency for the `hrtimer` API.
 
  - Add `Box::into_pin` for converting a `Box<_>` into a `Pin<Box<_>>` to align
    with Rust `alloc`. This is a dependency for the `hrtimer` API.
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCAAdFiEEEsH5R1a/fCoV1sAS4bgaPnkoY3cFAmfempwACgkQ4bgaPnko
 Y3duBg/+LVcEOEQvmaVi6+5TqOSsytMG2Cf+61n7HHqFhY2ptoY8Br5yMhtY8qxy
 fEPr8F/pGvW8nMN8H9smlscqwp8fAs/DKj2nnX4ZPU3xNj1BwAk52SmUbedBNY37
 JaRxFqheAM3AXVrpHjP2flUyXb3c2G7PR4CaZApa0pzMuHCKSI9iZZNACh/c/ViS
 9pcf1FKLGLqYwFDcLN+d2CtPtJq6ghOjRcaJTGc3G1Wiosw3VYmQK/vyGCwROCQX
 h0OwwT+1wokp9cIhBW4X1WzNdp9df71lW32qpZ4weYeV8y9oPJNvr1SqDblpGLm0
 T+qE2RSRKNsXxiJS4viLUsqVUgzCtu7bB402MxcmoGInxt74AEmY1Vx80QVF4SFq
 KvfDlyk9al2dVc24GsDTAvQo/1KiDCEVWsxLIbyRQMuOZLuA5sGSN6FSGt/aW+Vb
 ngYLnwTangvANWqaRdiTSa9tcGviaqA7V3EcpL27hsL2eMCilm6M3PuC2LnHLp46
 Yf2G6fWUdVi8Sra1cHIArKOz1PVZ+KuMn3SHoKo1UwJPJ3J5VrYxSPIFRd38+2qg
 sjaITJfYg6ZWeBfECfaOv6AHnjBi8AAskrRyUzrUu7bdGqXW6IxnAoGc195Q+wz/
 0h0wK9Z2+UqbNT96jeOk+1FvXk4cL0wUYsZM4hviCi1+w4rP4kg=
 =vNJu
 -----END PGP SIGNATURE-----

Merge tag 'rust-hrtimer-for-v6.15-v3' of https://github.com/Rust-for-Linux/linux into rust-next

Pull rust-hrtimer updates from Andreas Hindborg:
 "Introduce Rust support for the 'hrtimer' subsystem:

   - Add a way to use the 'hrtimer' subsystem from Rust. Rust code can
     now set up intrusive timers without allocating when starting the
     timer.

   - Add support for 'Pin<Box<_>>', 'Arc<_>', 'Pin<&_>' and
     'Pin<&mut _>' as pointer types for use with timer callbacks.

   - Add support for setting clock source and timer mode.

  'kernel' crate:

   - Add 'Arc::as_ptr' for converting an 'Arc' to a raw pointer. This is
     a dependency for the 'hrtimer' API.

   - Add 'Box::into_pin' for converting a 'Box<_>' into a 'Pin<Box<_>>'
     to align with Rust 'alloc'. This is a dependency for the 'hrtimer'
     API."

* tag 'rust-hrtimer-for-v6.15-v3' of https://github.com/Rust-for-Linux/linux:
  rust: hrtimer: add maintainer entry
  rust: hrtimer: add clocksource selection through `ClockId`
  rust: hrtimer: add `HrTimerMode`
  rust: hrtimer: implement `HrTimerPointer` for `Pin<Box<T>>`
  rust: alloc: add `Box::into_pin`
  rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&mut T>`
  rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&T>`
  rust: hrtimer: add `hrtimer::ScopedHrTimerPointer`
  rust: hrtimer: add `UnsafeHrTimerPointer`
  rust: hrtimer: allow timer restart from timer handler
  rust: hrtimer: implement `HrTimerPointer` for `Arc`
  rust: sync: add `Arc::as_ptr`
  rust: hrtimer: introduce hrtimer support
This commit is contained in:
Miguel Ojeda 2025-03-25 22:33:11 +01:00
commit e6ea10d5db
9 changed files with 1052 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
MAINTAINERS
View File

@ -10370,6 +10370,21 @@ F: kernel/time/timer_list.c
F: kernel/time/timer_migration.*
F: tools/testing/selftests/timers/
HIGH-RESOLUTION TIMERS [RUST]
M: Andreas Hindborg <a.hindborg@kernel.org>
R: Boqun Feng <boqun.feng@gmail.com>
R: Frederic Weisbecker <frederic@kernel.org>
R: Lyude Paul <lyude@redhat.com>
R: Thomas Gleixner <tglx@linutronix.de>
R: Anna-Maria Behnsen <anna-maria@linutronix.de>
L: rust-for-linux@vger.kernel.org
S: Supported
W: https://rust-for-linux.com
B: https://github.com/Rust-for-Linux/linux/issues
T: git https://github.com/Rust-for-Linux/linux.git hrtimer-next
F: rust/kernel/time/hrtimer.rs
F: rust/kernel/time/hrtimer/
HIGH-SPEED SCC DRIVER FOR AX.25
L: linux-hams@vger.kernel.org
S: Orphan

6
rust/kernel/alloc/kbox.rs
View File

@ -252,6 +252,12 @@ where
Ok(Self::new(x, flags)?.into())
}
/// Convert a [`Box<T,A>`] to a [`Pin<Box<T,A>>`]. If `T` does not implement
/// [`Unpin`], then `x` will be pinned in memory and can't be moved.
pub fn into_pin(this: Self) -> Pin<Self> {
this.into()
}
/// Forgets the contents (does not run the destructor), but keeps the allocation.
fn forget_contents(this: Self) -> Box<MaybeUninit<T>, A> {
let ptr = Self::into_raw(this);

13
rust/kernel/sync/arc.rs
View File

@ -266,6 +266,15 @@ impl<T: ?Sized> Arc<T> {
unsafe { core::ptr::addr_of!((*ptr).data) }
}
/// Return a raw pointer to the data in this arc.
pub fn as_ptr(this: &Self) -> *const T {
let ptr = this.ptr.as_ptr();
// SAFETY: As `ptr` points to a valid allocation of type `ArcInner`,
// field projection to `data`is within bounds of the allocation.
unsafe { core::ptr::addr_of!((*ptr).data) }
}
/// Recreates an [`Arc`] instance previously deconstructed via [`Arc::into_raw`].
///
/// # Safety
@ -559,11 +568,11 @@ impl<T: ?Sized> ArcBorrow<'_, T> {
}
/// Creates an [`ArcBorrow`] to an [`Arc`] that has previously been deconstructed with
/// [`Arc::into_raw`].
/// [`Arc::into_raw`] or [`Arc::as_ptr`].
///
/// # Safety
///
/// * The provided pointer must originate from a call to [`Arc::into_raw`].
/// * The provided pointer must originate from a call to [`Arc::into_raw`] or [`Arc::as_ptr`].
/// * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must
/// not hit zero.
/// * For the duration of the lifetime annotated on this `ArcBorrow`, there must not be a

68
rust/kernel/time.rs
View File

@ -8,6 +8,8 @@
//! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
//! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h).
pub mod hrtimer;
/// The number of nanoseconds per millisecond.
pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;
@ -81,3 +83,69 @@ impl core::ops::Sub for Ktime {
}
}
}
/// An identifier for a clock. Used when specifying clock sources.
///
///
/// Selection of the clock depends on the use case. In some cases the usage of a
/// particular clock is mandatory, e.g. in network protocols, filesystems.In other
/// cases the user of the clock has to decide which clock is best suited for the
/// purpose. In most scenarios clock [`ClockId::Monotonic`] is the best choice as it
/// provides a accurate monotonic notion of time (leap second smearing ignored).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[repr(u32)]
pub enum ClockId {
/// A settable system-wide clock that measures real (i.e., wall-clock) time.
///
/// Setting this clock requires appropriate privileges. This clock is
/// affected by discontinuous jumps in the system time (e.g., if the system
/// administrator manually changes the clock), and by frequency adjustments
/// performed by NTP and similar applications via adjtime(3), adjtimex(2),
/// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the
/// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time
/// (UTC) except that it ignores leap seconds; near a leap second it may be
/// adjusted by leap second smearing to stay roughly in sync with UTC. Leap
/// second smearing applies frequency adjustments to the clock to speed up
/// or slow down the clock to account for the leap second without
/// discontinuities in the clock. If leap second smearing is not applied,
/// the clock will experience discontinuity around leap second adjustment.
RealTime = bindings::CLOCK_REALTIME,
/// A monotonically increasing clock.
///
/// A nonsettable system-wide clock that represents monotonic time since—as
/// described by POSIX—"some unspecified point in the past". On Linux, that
/// point corresponds to the number of seconds that the system has been
/// running since it was booted.
///
/// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the
/// CLOCK_REAL (e.g., if the system administrator manually changes the
/// clock), but is affected by frequency adjustments. This clock does not
/// count time that the system is suspended.
Monotonic = bindings::CLOCK_MONOTONIC,
/// A monotonic that ticks while system is suspended.
///
/// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC,
/// except that it also includes any time that the system is suspended. This
/// allows applications to get a suspend-aware monotonic clock without
/// having to deal with the complications of CLOCK_REALTIME, which may have
/// discontinuities if the time is changed using settimeofday(2) or similar.
BootTime = bindings::CLOCK_BOOTTIME,
/// International Atomic Time.
///
/// A system-wide clock derived from wall-clock time but counting leap seconds.
///
/// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is
/// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This
/// usually happens during boot and **should** not happen during normal operations.
/// However, if NTP or another application adjusts CLOCK_REALTIME by leap second
/// smearing, this clock will not be precise during leap second smearing.
///
/// The acronym TAI refers to International Atomic Time.
TAI = bindings::CLOCK_TAI,
}
impl ClockId {
fn into_c(self) -> bindings::clockid_t {
self as bindings::clockid_t
}
}

520
rust/kernel/time/hrtimer.rs Normal file
View File

@ -0,0 +1,520 @@
// SPDX-License-Identifier: GPL-2.0
//! Intrusive high resolution timers.
//!
//! Allows running timer callbacks without doing allocations at the time of
//! starting the timer. For now, only one timer per type is allowed.
//!
//! # Vocabulary
//!
//! States:
//!
//! - Stopped: initialized but not started, or cancelled, or not restarted.
//! - Started: initialized and started or restarted.
//! - Running: executing the callback.
//!
//! Operations:
//!
//! * Start
//! * Cancel
//! * Restart
//!
//! Events:
//!
//! * Expire
//!
//! ## State Diagram
//!
//! ```text
//! Return NoRestart
//! +---------------------------------------------------------------------+
//! | |
//! | |
//! | |
//! | Return Restart |
//! | +------------------------+ |
//! | | | |
//! | | | |
//! v v | |
//! +-----------------+ Start +------------------+ +--------+-----+--+
//! | +---------------->| | | |
//! Init | | | | Expire | |
//! --------->| Stopped | | Started +---------->| Running |
//! | | Cancel | | | |
//! | |<----------------+ | | |
//! +-----------------+ +---------------+--+ +-----------------+
//! ^ |
//! | |
//! +---------+
//! Restart
//! ```
//!
//!
//! A timer is initialized in the **stopped** state. A stopped timer can be
//! **started** by the `start` operation, with an **expiry** time. After the
//! `start` operation, the timer is in the **started** state. When the timer
//! **expires**, the timer enters the **running** state and the handler is
//! executed. After the handler has returned, the timer may enter the
//! **started* or **stopped** state, depending on the return value of the
//! handler. A timer in the **started** or **running** state may be **canceled**
//! by the `cancel` operation. A timer that is cancelled enters the **stopped**
//! state.
//!
//! A `cancel` or `restart` operation on a timer in the **running** state takes
//! effect after the handler has returned and the timer has transitioned
//! out of the **running** state.
//!
//! A `restart` operation on a timer in the **stopped** state is equivalent to a
//! `start` operation.
use super::ClockId;
use crate::{prelude::*, time::Ktime, types::Opaque};
use core::marker::PhantomData;
use pin_init::PinInit;
/// A timer backed by a C `struct hrtimer`.
///
/// # Invariants
///
/// * `self.timer` is initialized by `bindings::hrtimer_setup`.
#[pin_data]
#[repr(C)]
pub struct HrTimer<T> {
#[pin]
timer: Opaque<bindings::hrtimer>,
mode: HrTimerMode,
_t: PhantomData<T>,
}
// SAFETY: Ownership of an `HrTimer` can be moved to other threads and
// used/dropped from there.
unsafe impl<T> Send for HrTimer<T> {}
// SAFETY: Timer operations are locked on the C side, so it is safe to operate
// on a timer from multiple threads.
unsafe impl<T> Sync for HrTimer<T> {}
impl<T> HrTimer<T> {
/// Return an initializer for a new timer instance.
pub fn new(mode: HrTimerMode, clock: ClockId) -> impl PinInit<Self>
where
T: HrTimerCallback,
{
pin_init!(Self {
// INVARIANT: We initialize `timer` with `hrtimer_setup` below.
timer <- Opaque::ffi_init(move |place: *mut bindings::hrtimer| {
// SAFETY: By design of `pin_init!`, `place` is a pointer to a
// live allocation. hrtimer_setup will initialize `place` and
// does not require `place` to be initialized prior to the call.
unsafe {
bindings::hrtimer_setup(
place,
Some(T::Pointer::run),
clock.into_c(),
mode.into_c(),
);
}
}),
mode: mode,
_t: PhantomData,
})
}
/// Get a pointer to the contained `bindings::hrtimer`.
///
/// This function is useful to get access to the value without creating
/// intermediate references.
///
/// # Safety
///
/// `this` must point to a live allocation of at least the size of `Self`.
unsafe fn raw_get(this: *const Self) -> *mut bindings::hrtimer {
// SAFETY: The field projection to `timer` does not go out of bounds,
// because the caller of this function promises that `this` points to an
// allocation of at least the size of `Self`.
unsafe { Opaque::raw_get(core::ptr::addr_of!((*this).timer)) }
}
/// Cancel an initialized and potentially running timer.
///
/// If the timer handler is running, this function will block until the
/// handler returns.
///
/// 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.
///
/// Users of the `HrTimer` API would not usually call this method directly.
/// Instead they would use the safe [`HrTimerHandle::cancel`] on the handle
/// returned when the timer was started.
///
/// This function is useful to get access to the value without creating
/// intermediate references.
///
/// # Safety
///
/// `this` must point to a valid `Self`.
pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool {
// SAFETY: `this` points to an allocation of at least `HrTimer` size.
let c_timer_ptr = unsafe { HrTimer::raw_get(this) };
// If the handler is running, this will wait for the handler to return
// before returning.
// SAFETY: `c_timer_ptr` is initialized and valid. Synchronization is
// handled on the C side.
unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 }
}
}
/// Implemented by pointer types that point to structs that contain a [`HrTimer`].
///
/// `Self` must be [`Sync`] because it is passed to timer callbacks in another
/// thread of execution (hard or soft interrupt context).
///
/// Starting a timer returns a [`HrTimerHandle`] that can be used to manipulate
/// the timer. Note that it is OK to call the start function repeatedly, and
/// that more than one [`HrTimerHandle`] associated with a [`HrTimerPointer`] may
/// exist. A timer can be manipulated through any of the handles, and a handle
/// may represent a cancelled timer.
pub trait HrTimerPointer: Sync + Sized {
/// A handle representing a started or restarted timer.
///
/// If the timer is running or if the timer callback is executing when the
/// handle is dropped, the drop method of [`HrTimerHandle`] should not return
/// until the timer is stopped and the callback has completed.
///
/// Note: When implementing this trait, consider that it is not unsafe to
/// leak the handle.
type TimerHandle: HrTimerHandle;
/// Start the timer with expiry after `expires` time units. If the timer was
/// already running, it is restarted with the new expiry time.
fn start(self, expires: Ktime) -> Self::TimerHandle;
}
/// Unsafe version of [`HrTimerPointer`] for situations where leaking the
/// [`HrTimerHandle`] returned by `start` would be unsound. This is the case for
/// stack allocated timers.
///
/// Typical implementers are pinned references such as [`Pin<&T>`].
///
/// # Safety
///
/// Implementers of this trait must ensure that instances of types implementing
/// [`UnsafeHrTimerPointer`] outlives any associated [`HrTimerPointer::TimerHandle`]
/// instances.
pub unsafe trait UnsafeHrTimerPointer: Sync + Sized {
/// A handle representing a running timer.
///
/// # Safety
///
/// If the timer is running, or if the timer callback is executing when the
/// handle is dropped, the drop method of [`Self::TimerHandle`] must not return
/// until the timer is stopped and the callback has completed.
type TimerHandle: HrTimerHandle;
/// Start the timer after `expires` time units. If the timer was already
/// running, it is restarted at the new expiry time.
///
/// # Safety
///
/// Caller promises keep the timer structure alive until the timer is dead.
/// Caller can ensure this by not leaking the returned [`Self::TimerHandle`].
unsafe fn start(self, expires: Ktime) -> Self::TimerHandle;
}
/// A trait for stack allocated timers.
///
/// # Safety
///
/// Implementers must ensure that `start_scoped` does not return until the
/// timer is dead and the timer handler is not running.
pub unsafe trait ScopedHrTimerPointer {
/// Start the timer to run after `expires` time units and immediately
/// after call `f`. When `f` returns, the timer is cancelled.
fn start_scoped<T, F>(self, expires: Ktime, f: F) -> T
where
F: FnOnce() -> T;
}
// SAFETY: By the safety requirement of [`UnsafeHrTimerPointer`], dropping the
// handle returned by [`UnsafeHrTimerPointer::start`] ensures that the timer is
// killed.
unsafe impl<T> ScopedHrTimerPointer for T
where
T: UnsafeHrTimerPointer,
{
fn start_scoped<U, F>(self, expires: Ktime, f: F) -> U
where
F: FnOnce() -> U,
{
// SAFETY: We drop the timer handle below before returning.
let handle = unsafe { UnsafeHrTimerPointer::start(self, expires) };
let t = f();
drop(handle);
t
}
}
/// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a
/// function to call.
// This is split from `HrTimerPointer` to make it easier to specify trait bounds.
pub trait RawHrTimerCallback {
/// Type of the parameter passed to [`HrTimerCallback::run`]. It may be
/// [`Self`], or a pointer type derived from [`Self`].
type CallbackTarget<'a>;
/// Callback to be called from C when timer fires.
///
/// # Safety
///
/// Only to be called by C code in the `hrtimer` subsystem. `this` must point
/// to the `bindings::hrtimer` structure that was used to start the timer.
unsafe extern "C" fn run(this: *mut bindings::hrtimer) -> bindings::hrtimer_restart;
}
/// Implemented by structs that can be the target of a timer callback.
pub trait HrTimerCallback {
/// The type whose [`RawHrTimerCallback::run`] method will be invoked when
/// the timer expires.
type Pointer<'a>: RawHrTimerCallback;
/// Called by the timer logic when the timer fires.
fn run(this: <Self::Pointer<'_> as RawHrTimerCallback>::CallbackTarget<'_>) -> HrTimerRestart
where
Self: Sized;
}
/// A handle representing a potentially running timer.
///
/// More than one handle representing the same timer might exist.
///
/// # Safety
///
/// When dropped, the timer represented by this handle must be cancelled, if it
/// is running. If the timer handler is running when the handle is dropped, the
/// drop method must wait for the handler to return before returning.
///
/// Note: One way to satisfy the safety requirement is to call `Self::cancel` in
/// the drop implementation for `Self.`
pub unsafe trait HrTimerHandle {
/// Cancel the timer. If the timer is in the running state, block till the
/// handler has returned.
///
/// 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.
fn cancel(&mut self) -> bool;
}
/// Implemented by structs that contain timer nodes.
///
/// Clients of the timer API would usually safely implement this trait by using
/// the [`crate::impl_has_hr_timer`] macro.
///
/// # Safety
///
/// Implementers of this trait must ensure that the implementer has a
/// [`HrTimer`] field and that all trait methods are implemented according to
/// their documentation. All the methods of this trait must operate on the same
/// field.
pub unsafe trait HasHrTimer<T> {
/// Return a pointer to the [`HrTimer`] within `Self`.
///
/// This function is useful to get access to the value without creating
/// intermediate references.
///
/// # Safety
///
/// `this` must be a valid pointer.
unsafe fn raw_get_timer(this: *const Self) -> *const HrTimer<T>;
/// Return a pointer to the struct that is containing the [`HrTimer`] pointed
/// to by `ptr`.
///
/// This function is useful to get access to the value without creating
/// intermediate references.
///
/// # Safety
///
/// `ptr` must point to a [`HrTimer<T>`] field in a struct of type `Self`.
unsafe fn timer_container_of(ptr: *mut HrTimer<T>) -> *mut Self
where
Self: Sized;
/// Get pointer to the contained `bindings::hrtimer` struct.
///
/// This function is useful to get access to the value without creating
/// intermediate references.
///
/// # Safety
///
/// `this` must be a valid pointer.
unsafe fn c_timer_ptr(this: *const Self) -> *const bindings::hrtimer {
// SAFETY: `this` is a valid pointer to a `Self`.
let timer_ptr = unsafe { Self::raw_get_timer(this) };
// SAFETY: timer_ptr points to an allocation of at least `HrTimer` size.
unsafe { HrTimer::raw_get(timer_ptr) }
}
/// Start the timer contained in the `Self` pointed to by `self_ptr`. If
/// it is already running it is removed and inserted.
///
/// # Safety
///
/// - `this` must point to a valid `Self`.
/// - Caller must ensure that the pointee of `this` lives until the timer
/// fires or is canceled.
unsafe fn start(this: *const Self, expires: Ktime) {
// SAFETY: By function safety requirement, `this` is a valid `Self`.
unsafe {
bindings::hrtimer_start_range_ns(
Self::c_timer_ptr(this).cast_mut(),
expires.to_ns(),
0,
(*Self::raw_get_timer(this)).mode.into_c(),
);
}
}
}
/// Restart policy for timers.
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
#[repr(u32)]
pub enum HrTimerRestart {
/// Timer should not be restarted.
#[allow(clippy::unnecessary_cast)]
NoRestart = bindings::hrtimer_restart_HRTIMER_NORESTART as u32,
/// Timer should be restarted.
#[allow(clippy::unnecessary_cast)]
Restart = bindings::hrtimer_restart_HRTIMER_RESTART as u32,
}
impl HrTimerRestart {
fn into_c(self) -> bindings::hrtimer_restart {
self as bindings::hrtimer_restart
}
}
/// Operational mode of [`HrTimer`].
// NOTE: Some of these have the same encoding on the C side, so we keep
// `repr(Rust)` and convert elsewhere.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum HrTimerMode {
/// Timer expires at the given expiration time.
Absolute,
/// Timer expires after the given expiration time interpreted as a duration from now.
Relative,
/// Timer does not move between CPU cores.
Pinned,
/// Timer handler is executed in soft irq context.
Soft,
/// Timer handler is executed in hard irq context.
Hard,
/// Timer expires at the given expiration time.
/// Timer does not move between CPU cores.
AbsolutePinned,
/// Timer expires after the given expiration time interpreted as a duration from now.
/// Timer does not move between CPU cores.
RelativePinned,
/// Timer expires at the given expiration time.
/// Timer handler is executed in soft irq context.
AbsoluteSoft,
/// Timer expires after the given expiration time interpreted as a duration from now.
/// Timer handler is executed in soft irq context.
RelativeSoft,
/// Timer expires at the given expiration time.
/// Timer does not move between CPU cores.
/// Timer handler is executed in soft irq context.
AbsolutePinnedSoft,
/// Timer expires after the given expiration time interpreted as a duration from now.
/// Timer does not move between CPU cores.
/// Timer handler is executed in soft irq context.
RelativePinnedSoft,
/// Timer expires at the given expiration time.
/// Timer handler is executed in hard irq context.
AbsoluteHard,
/// Timer expires after the given expiration time interpreted as a duration from now.
/// Timer handler is executed in hard irq context.
RelativeHard,
/// Timer expires at the given expiration time.
/// Timer does not move between CPU cores.
/// Timer handler is executed in hard irq context.
AbsolutePinnedHard,
/// Timer expires after the given expiration time interpreted as a duration from now.
/// Timer does not move between CPU cores.
/// Timer handler is executed in hard irq context.
RelativePinnedHard,
}
impl HrTimerMode {
fn into_c(self) -> bindings::hrtimer_mode {
use bindings::*;
match self {
HrTimerMode::Absolute => hrtimer_mode_HRTIMER_MODE_ABS,
HrTimerMode::Relative => hrtimer_mode_HRTIMER_MODE_REL,
HrTimerMode::Pinned => hrtimer_mode_HRTIMER_MODE_PINNED,
HrTimerMode::Soft => hrtimer_mode_HRTIMER_MODE_SOFT,
HrTimerMode::Hard => hrtimer_mode_HRTIMER_MODE_HARD,
HrTimerMode::AbsolutePinned => hrtimer_mode_HRTIMER_MODE_ABS_PINNED,
HrTimerMode::RelativePinned => hrtimer_mode_HRTIMER_MODE_REL_PINNED,
HrTimerMode::AbsoluteSoft => hrtimer_mode_HRTIMER_MODE_ABS_SOFT,
HrTimerMode::RelativeSoft => hrtimer_mode_HRTIMER_MODE_REL_SOFT,
HrTimerMode::AbsolutePinnedSoft => hrtimer_mode_HRTIMER_MODE_ABS_PINNED_SOFT,
HrTimerMode::RelativePinnedSoft => hrtimer_mode_HRTIMER_MODE_REL_PINNED_SOFT,
HrTimerMode::AbsoluteHard => hrtimer_mode_HRTIMER_MODE_ABS_HARD,
HrTimerMode::RelativeHard => hrtimer_mode_HRTIMER_MODE_REL_HARD,
HrTimerMode::AbsolutePinnedHard => hrtimer_mode_HRTIMER_MODE_ABS_PINNED_HARD,
HrTimerMode::RelativePinnedHard => hrtimer_mode_HRTIMER_MODE_REL_PINNED_HARD,
}
}
}
/// Use to implement the [`HasHrTimer<T>`] trait.
///
/// See [`module`] documentation for an example.
///
/// [`module`]: crate::time::hrtimer
#[macro_export]
macro_rules! impl_has_hr_timer {
(
impl$({$($generics:tt)*})?
HasHrTimer<$timer_type:ty>
for $self:ty
{ self.$field:ident }
$($rest:tt)*
) => {
// SAFETY: This implementation of `raw_get_timer` only compiles if the
// field has the right type.
unsafe impl$(<$($generics)*>)? $crate::time::hrtimer::HasHrTimer<$timer_type> for $self {
#[inline]
unsafe fn raw_get_timer(
this: *const Self,
) -> *const $crate::time::hrtimer::HrTimer<$timer_type> {
// SAFETY: The caller promises that the pointer is not dangling.
unsafe { ::core::ptr::addr_of!((*this).$field) }
}
#[inline]
unsafe fn timer_container_of(
ptr: *mut $crate::time::hrtimer::HrTimer<$timer_type>,
) -> *mut Self {
// SAFETY: As per the safety requirement of this function, `ptr`
// is pointing inside a `$timer_type`.
unsafe { ::kernel::container_of!(ptr, $timer_type, $field).cast_mut() }
}
}
}
}
mod arc;
pub use arc::ArcHrTimerHandle;
mod pin;
pub use pin::PinHrTimerHandle;
mod pin_mut;
pub use pin_mut::PinMutHrTimerHandle;
// `box` is a reserved keyword, so prefix with `t` for timer
mod tbox;
pub use tbox::BoxHrTimerHandle;

100
rust/kernel/time/hrtimer/arc.rs Normal file
View File

@ -0,0 +1,100 @@
// SPDX-License-Identifier: GPL-2.0
use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
use super::HrTimerHandle;
use super::HrTimerPointer;
use super::RawHrTimerCallback;
use crate::sync::Arc;
use crate::sync::ArcBorrow;
use crate::time::Ktime;
/// A handle for an `Arc<HasHrTimer<T>>` returned by a call to
/// [`HrTimerPointer::start`].
pub struct ArcHrTimerHandle<T>
where
T: HasHrTimer<T>,
{
pub(crate) inner: Arc<T>,
}
// SAFETY: We implement drop below, and we cancel the timer in the drop
// implementation.
unsafe impl<T> HrTimerHandle for ArcHrTimerHandle<T>
where
T: HasHrTimer<T>,
{
fn cancel(&mut self) -> bool {
let self_ptr = Arc::as_ptr(&self.inner);
// SAFETY: As we obtained `self_ptr` from a valid reference above, it
// must point to a valid `T`.
let timer_ptr = unsafe { <T as HasHrTimer<T>>::raw_get_timer(self_ptr) };
// SAFETY: As `timer_ptr` points into `T` and `T` is valid, `timer_ptr`
// must point to a valid `HrTimer` instance.
unsafe { HrTimer::<T>::raw_cancel(timer_ptr) }
}
}
impl<T> Drop for ArcHrTimerHandle<T>
where
T: HasHrTimer<T>,
{
fn drop(&mut self) {
self.cancel();
}
}
impl<T> HrTimerPointer for Arc<T>
where
T: 'static,
T: Send + Sync,
T: HasHrTimer<T>,
T: for<'a> HrTimerCallback<Pointer<'a> = Self>,
{
type TimerHandle = ArcHrTimerHandle<T>;
fn start(self, expires: Ktime) -> ArcHrTimerHandle<T> {
// SAFETY:
// - We keep `self` alive by wrapping it in a handle below.
// - Since we generate the pointer passed to `start` from a valid
// reference, it is a valid pointer.
unsafe { T::start(Arc::as_ptr(&self), expires) };
ArcHrTimerHandle { inner: self }
}
}
impl<T> RawHrTimerCallback for Arc<T>
where
T: 'static,
T: HasHrTimer<T>,
T: for<'a> HrTimerCallback<Pointer<'a> = Self>,
{
type CallbackTarget<'a> = ArcBorrow<'a, T>;
unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart {
// `HrTimer` is `repr(C)`
let timer_ptr = ptr.cast::<super::HrTimer<T>>();
// SAFETY: By C API contract `ptr` is the pointer we passed when
// queuing the timer, so it is a `HrTimer<T>` embedded in a `T`.
let data_ptr = unsafe { T::timer_container_of(timer_ptr) };
// SAFETY:
// - `data_ptr` is derived form the pointer to the `T` that was used to
// queue the timer.
// - As per the safety requirements of the trait `HrTimerHandle`, the
// `ArcHrTimerHandle` associated with this timer is guaranteed to
// be alive until this method returns. That handle borrows the `T`
// behind `data_ptr` thus guaranteeing the validity of
// the `ArcBorrow` created below.
// - We own one refcount in the `ArcTimerHandle` associated with this
// timer, so it is not possible to get a `UniqueArc` to this
// allocation from other `Arc` clones.
let receiver = unsafe { ArcBorrow::from_raw(data_ptr) };
T::run(receiver).into_c()
}
}

104
rust/kernel/time/hrtimer/pin.rs Normal file
View File

@ -0,0 +1,104 @@
// SPDX-License-Identifier: GPL-2.0
use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
use super::HrTimerHandle;
use super::RawHrTimerCallback;
use super::UnsafeHrTimerPointer;
use crate::time::Ktime;
use core::pin::Pin;
/// A handle for a `Pin<&HasHrTimer>`. When the handle exists, the timer might be
/// running.
pub struct PinHrTimerHandle<'a, T>
where
T: HasHrTimer<T>,
{
pub(crate) inner: Pin<&'a T>,
}
// SAFETY: We cancel the timer when the handle is dropped. The implementation of
// the `cancel` method will block if the timer handler is running.
unsafe impl<'a, T> HrTimerHandle for PinHrTimerHandle<'a, T>
where
T: HasHrTimer<T>,
{
fn cancel(&mut self) -> bool {
let self_ptr: *const T = self.inner.get_ref();
// SAFETY: As we got `self_ptr` from a reference above, it must point to
// a valid `T`.
let timer_ptr = unsafe { <T as HasHrTimer<T>>::raw_get_timer(self_ptr) };
// SAFETY: As `timer_ptr` is derived from a reference, it must point to
// a valid and initialized `HrTimer`.
unsafe { HrTimer::<T>::raw_cancel(timer_ptr) }
}
}
impl<'a, T> Drop for PinHrTimerHandle<'a, T>
where
T: HasHrTimer<T>,
{
fn drop(&mut self) {
self.cancel();
}
}
// SAFETY: We capture the lifetime of `Self` when we create a `PinHrTimerHandle`,
// so `Self` will outlive the handle.
unsafe impl<'a, T> UnsafeHrTimerPointer for Pin<&'a T>
where
T: Send + Sync,
T: HasHrTimer<T>,
T: HrTimerCallback<Pointer<'a> = Self>,
{
type TimerHandle = PinHrTimerHandle<'a, T>;
unsafe fn start(self, expires: Ktime) -> Self::TimerHandle {
// Cast to pointer
let self_ptr: *const T = self.get_ref();
// SAFETY:
// - As we derive `self_ptr` from a reference above, it must point to a
// valid `T`.
// - We keep `self` alive by wrapping it in a handle below.
unsafe { T::start(self_ptr, expires) };
PinHrTimerHandle { inner: self }
}
}
impl<'a, T> RawHrTimerCallback for Pin<&'a T>
where
T: HasHrTimer<T>,
T: HrTimerCallback<Pointer<'a> = Self>,
{
type CallbackTarget<'b> = Self;
unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart {
// `HrTimer` is `repr(C)`
let timer_ptr = ptr as *mut HrTimer<T>;
// SAFETY: By the safety requirement of this function, `timer_ptr`
// points to a `HrTimer<T>` contained in an `T`.
let receiver_ptr = unsafe { T::timer_container_of(timer_ptr) };
// SAFETY:
// - By the safety requirement of this function, `timer_ptr`
// points to a `HrTimer<T>` contained in an `T`.
// - As per the safety requirements of the trait `HrTimerHandle`, the
// `PinHrTimerHandle` associated with this timer is guaranteed to
// be alive until this method returns. That handle borrows the `T`
// behind `receiver_ptr`, thus guaranteeing the validity of
// the reference created below.
let receiver_ref = unsafe { &*receiver_ptr };
// SAFETY: `receiver_ref` only exists as pinned, so it is safe to pin it
// here.
let receiver_pin = unsafe { Pin::new_unchecked(receiver_ref) };
T::run(receiver_pin).into_c()
}
}

108
rust/kernel/time/hrtimer/pin_mut.rs Normal file
View File

@ -0,0 +1,108 @@
// SPDX-License-Identifier: GPL-2.0
use super::{
HasHrTimer, HrTimer, HrTimerCallback, HrTimerHandle, RawHrTimerCallback, UnsafeHrTimerPointer,
};
use crate::time::Ktime;
use core::{marker::PhantomData, pin::Pin, ptr::NonNull};
/// A handle for a `Pin<&mut HasHrTimer>`. When the handle exists, the timer might
/// be running.
pub struct PinMutHrTimerHandle<'a, T>
where
T: HasHrTimer<T>,
{
pub(crate) inner: NonNull<T>,
_p: PhantomData<&'a mut T>,
}
// SAFETY: We cancel the timer when the handle is dropped. The implementation of
// the `cancel` method will block if the timer handler is running.
unsafe impl<'a, T> HrTimerHandle for PinMutHrTimerHandle<'a, T>
where
T: HasHrTimer<T>,
{
fn cancel(&mut self) -> bool {
let self_ptr = self.inner.as_ptr();
// SAFETY: As we got `self_ptr` from a reference above, it must point to
// a valid `T`.
let timer_ptr = unsafe { <T as HasHrTimer<T>>::raw_get_timer(self_ptr) };
// SAFETY: As `timer_ptr` is derived from a reference, it must point to
// a valid and initialized `HrTimer`.
unsafe { HrTimer::<T>::raw_cancel(timer_ptr) }
}
}
impl<'a, T> Drop for PinMutHrTimerHandle<'a, T>
where
T: HasHrTimer<T>,
{
fn drop(&mut self) {
self.cancel();
}
}
// SAFETY: We capture the lifetime of `Self` when we create a
// `PinMutHrTimerHandle`, so `Self` will outlive the handle.
unsafe impl<'a, T> UnsafeHrTimerPointer for Pin<&'a mut T>
where
T: Send + Sync,
T: HasHrTimer<T>,
T: HrTimerCallback<Pointer<'a> = Self>,
{
type TimerHandle = PinMutHrTimerHandle<'a, T>;
unsafe fn start(mut self, expires: Ktime) -> Self::TimerHandle {
// SAFETY:
// - We promise not to move out of `self`. We only pass `self`
// back to the caller as a `Pin<&mut self>`.
// - The return value of `get_unchecked_mut` is guaranteed not to be null.
let self_ptr = unsafe { NonNull::new_unchecked(self.as_mut().get_unchecked_mut()) };
// SAFETY:
// - As we derive `self_ptr` from a reference above, it must point to a
// valid `T`.
// - We keep `self` alive by wrapping it in a handle below.
unsafe { T::start(self_ptr.as_ptr(), expires) };
PinMutHrTimerHandle {
inner: self_ptr,
_p: PhantomData,
}
}
}
impl<'a, T> RawHrTimerCallback for Pin<&'a mut T>
where
T: HasHrTimer<T>,
T: HrTimerCallback<Pointer<'a> = Self>,
{
type CallbackTarget<'b> = Self;
unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart {
// `HrTimer` is `repr(C)`
let timer_ptr = ptr as *mut HrTimer<T>;
// SAFETY: By the safety requirement of this function, `timer_ptr`
// points to a `HrTimer<T>` contained in an `T`.
let receiver_ptr = unsafe { T::timer_container_of(timer_ptr) };
// SAFETY:
// - By the safety requirement of this function, `timer_ptr`
// points to a `HrTimer<T>` contained in an `T`.
// - As per the safety requirements of the trait `HrTimerHandle`, the
// `PinMutHrTimerHandle` associated with this timer is guaranteed to
// be alive until this method returns. That handle borrows the `T`
// behind `receiver_ptr` mutably thus guaranteeing the validity of
// the reference created below.
let receiver_ref = unsafe { &mut *receiver_ptr };
// SAFETY: `receiver_ref` only exists as pinned, so it is safe to pin it
// here.
let receiver_pin = unsafe { Pin::new_unchecked(receiver_ref) };
T::run(receiver_pin).into_c()
}
}

120
rust/kernel/time/hrtimer/tbox.rs Normal file
View File

@ -0,0 +1,120 @@
// SPDX-License-Identifier: GPL-2.0
use super::HasHrTimer;
use super::HrTimer;
use super::HrTimerCallback;
use super::HrTimerHandle;
use super::HrTimerPointer;
use super::RawHrTimerCallback;
use crate::prelude::*;
use crate::time::Ktime;
use core::ptr::NonNull;
/// A handle for a [`Box<HasHrTimer<T>>`] returned by a call to
/// [`HrTimerPointer::start`].
///
/// # Invariants
///
/// - `self.inner` comes from a `Box::into_raw` call.
pub struct BoxHrTimerHandle<T, A>
where
T: HasHrTimer<T>,
A: crate::alloc::Allocator,
{
pub(crate) inner: NonNull<T>,
_p: core::marker::PhantomData<A>,
}
// SAFETY: We implement drop below, and we cancel the timer in the drop
// implementation.
unsafe impl<T, A> HrTimerHandle for BoxHrTimerHandle<T, A>
where
T: HasHrTimer<T>,
A: crate::alloc::Allocator,
{
fn cancel(&mut self) -> bool {
// SAFETY: As we obtained `self.inner` from a valid reference when we
// created `self`, it must point to a valid `T`.
let timer_ptr = unsafe { <T as HasHrTimer<T>>::raw_get_timer(self.inner.as_ptr()) };
// SAFETY: As `timer_ptr` points into `T` and `T` is valid, `timer_ptr`
// must point to a valid `HrTimer` instance.
unsafe { HrTimer::<T>::raw_cancel(timer_ptr) }
}
}
impl<T, A> Drop for BoxHrTimerHandle<T, A>
where
T: HasHrTimer<T>,
A: crate::alloc::Allocator,
{
fn drop(&mut self) {
self.cancel();
// SAFETY: By type invariant, `self.inner` came from a `Box::into_raw`
// call.
drop(unsafe { Box::<T, A>::from_raw(self.inner.as_ptr()) })
}
}
impl<T, A> HrTimerPointer for Pin<Box<T, A>>
where
T: 'static,
T: Send + Sync,
T: HasHrTimer<T>,
T: for<'a> HrTimerCallback<Pointer<'a> = Pin<Box<T, A>>>,
A: crate::alloc::Allocator,
{
type TimerHandle = BoxHrTimerHandle<T, A>;
fn start(self, expires: Ktime) -> Self::TimerHandle {
// SAFETY:
// - We will not move out of this box during timer callback (we pass an
// immutable reference to the callback).
// - `Box::into_raw` is guaranteed to return a valid pointer.
let inner =
unsafe { NonNull::new_unchecked(Box::into_raw(Pin::into_inner_unchecked(self))) };
// SAFETY:
// - We keep `self` alive by wrapping it in a handle below.
// - Since we generate the pointer passed to `start` from a valid
// reference, it is a valid pointer.
unsafe { T::start(inner.as_ptr(), expires) };
// INVARIANT: `inner` came from `Box::into_raw` above.
BoxHrTimerHandle {
inner,
_p: core::marker::PhantomData,
}
}
}
impl<T, A> RawHrTimerCallback for Pin<Box<T, A>>
where
T: 'static,
T: HasHrTimer<T>,
T: for<'a> HrTimerCallback<Pointer<'a> = Pin<Box<T, A>>>,
A: crate::alloc::Allocator,
{
type CallbackTarget<'a> = Pin<&'a mut T>;
unsafe extern "C" fn run(ptr: *mut bindings::hrtimer) -> bindings::hrtimer_restart {
// `HrTimer` is `repr(C)`
let timer_ptr = ptr.cast::<super::HrTimer<T>>();
// SAFETY: By C API contract `ptr` is the pointer we passed when
// queuing the timer, so it is a `HrTimer<T>` embedded in a `T`.
let data_ptr = unsafe { T::timer_container_of(timer_ptr) };
// SAFETY:
// - As per the safety requirements of the trait `HrTimerHandle`, the
// `BoxHrTimerHandle` associated with this timer is guaranteed to
// be alive until this method returns. That handle owns the `T`
// behind `data_ptr` thus guaranteeing the validity of
// the reference created below.
// - As `data_ptr` comes from a `Pin<Box<T>>`, only pinned references to
// `data_ptr` exist.
let data_mut_ref = unsafe { Pin::new_unchecked(&mut *data_ptr) };
T::run(data_mut_ref).into_c()
}
}