hrtimer.rs

  1// SPDX-License-Identifier: GPL-2.0
  2
  3//! Intrusive high resolution timers.
  4//!
  5//! Allows running timer callbacks without doing allocations at the time of
  6//! starting the timer. For now, only one timer per type is allowed.
  7//!
  8//! # Vocabulary
  9//!
 10//! States:
 11//!
 12//! - Stopped: initialized but not started, or cancelled, or not restarted.
 13//! - Started: initialized and started or restarted.
 14//! - Running: executing the callback.
 15//!
 16//! Operations:
 17//!
 18//! * Start
 19//! * Cancel
 20//! * Restart
 21//!
 22//! Events:
 23//!
 24//! * Expire
 25//!
 26//! ## State Diagram
 27//!
 28//! ```text
 29//!                                                   Return NoRestart
 30//!                       +---------------------------------------------------------------------+
 31//!                       |                                                                     |
 32//!                       |                                                                     |
 33//!                       |                                                                     |
 34//!                       |                                         Return Restart              |
 35//!                       |                                      +------------------------+     |
 36//!                       |                                      |                        |     |
 37//!                       |                                      |                        |     |
 38//!                       v                                      v                        |     |
 39//!           +-----------------+      Start      +------------------+           +--------+-----+--+
 40//!           |                 +---------------->|                  |           |                 |
 41//! Init      |                 |                 |                  |  Expire   |                 |
 42//! --------->|    Stopped      |                 |      Started     +---------->|     Running     |
 43//!           |                 |     Cancel      |                  |           |                 |
 44//!           |                 |<----------------+                  |           |                 |
 45//!           +-----------------+                 +---------------+--+           +-----------------+
 46//!                                                     ^         |
 47//!                                                     |         |
 48//!                                                     +---------+
 49//!                                                      Restart
 50//! ```
 51//!
 52//!
 53//! A timer is initialized in the **stopped** state. A stopped timer can be
 54//! **started** by the `start` operation, with an **expiry** time. After the
 55//! `start` operation, the timer is in the **started** state. When the timer
 56//! **expires**, the timer enters the **running** state and the handler is
 57//! executed. After the handler has returned, the timer may enter the
 58//! **started* or **stopped** state, depending on the return value of the
 59//! handler. A timer in the **started** or **running** state may be **canceled**
 60//! by the `cancel` operation. A timer that is cancelled enters the **stopped**
 61//! state.
 62//!
 63//! A `cancel` or `restart` operation on a timer in the **running** state takes
 64//! effect after the handler has returned and the timer has transitioned
 65//! out of the **running** state.
 66//!
 67//! A `restart` operation on a timer in the **stopped** state is equivalent to a
 68//! `start` operation.
 69
 70use super::{ClockSource, Delta, Instant};
 71use crate::{prelude::*, types::Opaque};
 72use core::{marker::PhantomData, ptr::NonNull};
 73use pin_init::PinInit;
 74
 75/// A type-alias to refer to the [`Instant<C>`] for a given `T` from [`HrTimer<T>`].
 76///
 77/// Where `C` is the [`ClockSource`] of the [`HrTimer`].
 78pub type HrTimerInstant<T> = Instant<<<T as HasHrTimer<T>>::TimerMode as HrTimerMode>::Clock>;
 79
 80/// A timer backed by a C `struct hrtimer`.
 81///
 82/// # Invariants
 83///
 84/// * `self.timer` is initialized by `bindings::hrtimer_setup`.
 85#[pin_data]
 86#[repr(C)]
 87pub struct HrTimer<T> {
 88    #[pin]
 89    timer: Opaque<bindings::hrtimer>,
 90    _t: PhantomData<T>,
 91}
 92
 93// SAFETY: Ownership of an `HrTimer` can be moved to other threads and
 94// used/dropped from there.
 95unsafe impl<T> Send for HrTimer<T> {}
 96
 97// SAFETY: Timer operations are locked on the C side, so it is safe to operate
 98// on a timer from multiple threads.
 99unsafe impl<T> Sync for HrTimer<T> {}
100
101impl<T> HrTimer<T> {
102    /// Return an initializer for a new timer instance.
103    pub fn new() -> impl PinInit<Self>
104    where
105        T: HrTimerCallback,
106        T: HasHrTimer<T>,
107    {
108        pin_init!(Self {
109            // INVARIANT: We initialize `timer` with `hrtimer_setup` below.
110            timer <- Opaque::ffi_init(move |place: *mut bindings::hrtimer| {
111                // SAFETY: By design of `pin_init!`, `place` is a pointer to a
112                // live allocation. hrtimer_setup will initialize `place` and
113                // does not require `place` to be initialized prior to the call.
114                unsafe {
115                    bindings::hrtimer_setup(
116                        place,
117                        Some(T::Pointer::run),
118                        <<T as HasHrTimer<T>>::TimerMode as HrTimerMode>::Clock::ID,
119                        <T as HasHrTimer<T>>::TimerMode::C_MODE,
120                    );
121                }
122            }),
123            _t: PhantomData,
124        })
125    }
126
127    /// Get a pointer to the contained `bindings::hrtimer`.
128    ///
129    /// This function is useful to get access to the value without creating
130    /// intermediate references.
131    ///
132    /// # Safety
133    ///
134    /// `this` must point to a live allocation of at least the size of `Self`.
135    unsafe fn raw_get(this: *const Self) -> *mut bindings::hrtimer {
136        // SAFETY: The field projection to `timer` does not go out of bounds,
137        // because the caller of this function promises that `this` points to an
138        // allocation of at least the size of `Self`.
139        unsafe { Opaque::cast_into(core::ptr::addr_of!((*this).timer)) }
140    }
141
142    /// Cancel an initialized and potentially running timer.
143    ///
144    /// If the timer handler is running, this function will block until the
145    /// handler returns.
146    ///
147    /// Note that the timer might be started by a concurrent start operation. If
148    /// so, the timer might not be in the **stopped** state when this function
149    /// returns.
150    ///
151    /// Users of the `HrTimer` API would not usually call this method directly.
152    /// Instead they would use the safe [`HrTimerHandle::cancel`] on the handle
153    /// returned when the timer was started.
154    ///
155    /// This function is useful to get access to the value without creating
156    /// intermediate references.
157    ///
158    /// # Safety
159    ///
160    /// `this` must point to a valid `Self`.
161    pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool {
162        // SAFETY: `this` points to an allocation of at least `HrTimer` size.
163        let c_timer_ptr = unsafe { HrTimer::raw_get(this) };
164
165        // If the handler is running, this will wait for the handler to return
166        // before returning.
167        // SAFETY: `c_timer_ptr` is initialized and valid. Synchronization is
168        // handled on the C side.
169        unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 }
170    }
171
172    /// Forward the timer expiry for a given timer pointer.
173    ///
174    /// # Safety
175    ///
176    /// - `self_ptr` must point to a valid `Self`.
177    /// - The caller must either have exclusive access to the data pointed at by `self_ptr`, or be
178    ///   within the context of the timer callback.
179    #[inline]
180    unsafe fn raw_forward(self_ptr: *mut Self, now: HrTimerInstant<T>, interval: Delta) -> u64
181    where
182        T: HasHrTimer<T>,
183    {
184        // SAFETY:
185        // * The C API requirements for this function are fulfilled by our safety contract.
186        // * `self_ptr` is guaranteed to point to a valid `Self` via our safety contract
187        unsafe {
188            bindings::hrtimer_forward(Self::raw_get(self_ptr), now.as_nanos(), interval.as_nanos())
189        }
190    }
191
192    /// Conditionally forward the timer.
193    ///
194    /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
195    /// expired at or before `now`, this function forwards the timer by `interval` until the timer
196    /// expires after `now` and then returns the number of times the timer was forwarded by
197    /// `interval`.
198    ///
199    /// This function is mainly useful for timer types which can provide exclusive access to the
200    /// timer when the timer is not running. For forwarding the timer from within the timer callback
201    /// context, see [`HrTimerCallbackContext::forward()`].
202    ///
203    /// Returns the number of overruns that occurred as a result of the timer expiry change.
204    pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
205    where
206        T: HasHrTimer<T>,
207    {
208        // SAFETY: `raw_forward` does not move `Self`
209        let this = unsafe { self.get_unchecked_mut() };
210
211        // SAFETY: By existence of `Pin<&mut Self>`, the pointer passed to `raw_forward` points to a
212        // valid `Self` that we have exclusive access to.
213        unsafe { Self::raw_forward(this, now, interval) }
214    }
215
216    /// Conditionally forward the timer.
217    ///
218    /// This is a variant of [`forward()`](Self::forward) that uses an interval after the current
219    /// time of the base clock for the [`HrTimer`].
220    pub fn forward_now(self: Pin<&mut Self>, interval: Delta) -> u64
221    where
222        T: HasHrTimer<T>,
223    {
224        self.forward(HrTimerInstant::<T>::now(), interval)
225    }
226
227    /// Return the time expiry for this [`HrTimer`].
228    ///
229    /// This value should only be used as a snapshot, as the actual expiry time could change after
230    /// this function is called.
231    pub fn expires(&self) -> HrTimerInstant<T>
232    where
233        T: HasHrTimer<T>,
234    {
235        // SAFETY: `self` is an immutable reference and thus always points to a valid `HrTimer`.
236        let c_timer_ptr = unsafe { HrTimer::raw_get(self) };
237
238        // SAFETY:
239        // - Timers cannot have negative ktime_t values as their expiration time.
240        // - There's no actual locking here, a racy read is fine and expected
241        unsafe {
242            Instant::from_ktime(
243                // This `read_volatile` is intended to correspond to a READ_ONCE call.
244                // FIXME(read_once): Replace with `read_once` when available on the Rust side.
245                core::ptr::read_volatile(&raw const ((*c_timer_ptr).node.expires)),
246            )
247        }
248    }
249}
250
251/// Implemented by pointer types that point to structs that contain a [`HrTimer`].
252///
253/// `Self` must be [`Sync`] because it is passed to timer callbacks in another
254/// thread of execution (hard or soft interrupt context).
255///
256/// Starting a timer returns a [`HrTimerHandle`] that can be used to manipulate
257/// the timer. Note that it is OK to call the start function repeatedly, and
258/// that more than one [`HrTimerHandle`] associated with a [`HrTimerPointer`] may
259/// exist. A timer can be manipulated through any of the handles, and a handle
260/// may represent a cancelled timer.
261pub trait HrTimerPointer: Sync + Sized {
262    /// The operational mode associated with this timer.
263    ///
264    /// This defines how the expiration value is interpreted.
265    type TimerMode: HrTimerMode;
266
267    /// A handle representing a started or restarted timer.
268    ///
269    /// If the timer is running or if the timer callback is executing when the
270    /// handle is dropped, the drop method of [`HrTimerHandle`] should not return
271    /// until the timer is stopped and the callback has completed.
272    ///
273    /// Note: When implementing this trait, consider that it is not unsafe to
274    /// leak the handle.
275    type TimerHandle: HrTimerHandle;
276
277    /// Start the timer with expiry after `expires` time units. If the timer was
278    /// already running, it is restarted with the new expiry time.
279    fn start(self, expires: <Self::TimerMode as HrTimerMode>::Expires) -> Self::TimerHandle;
280}
281
282/// Unsafe version of [`HrTimerPointer`] for situations where leaking the
283/// [`HrTimerHandle`] returned by `start` would be unsound. This is the case for
284/// stack allocated timers.
285///
286/// Typical implementers are pinned references such as [`Pin<&T>`].
287///
288/// # Safety
289///
290/// Implementers of this trait must ensure that instances of types implementing
291/// [`UnsafeHrTimerPointer`] outlives any associated [`HrTimerPointer::TimerHandle`]
292/// instances.
293pub unsafe trait UnsafeHrTimerPointer: Sync + Sized {
294    /// The operational mode associated with this timer.
295    ///
296    /// This defines how the expiration value is interpreted.
297    type TimerMode: HrTimerMode;
298
299    /// A handle representing a running timer.
300    ///
301    /// # Safety
302    ///
303    /// If the timer is running, or if the timer callback is executing when the
304    /// handle is dropped, the drop method of [`Self::TimerHandle`] must not return
305    /// until the timer is stopped and the callback has completed.
306    type TimerHandle: HrTimerHandle;
307
308    /// Start the timer after `expires` time units. If the timer was already
309    /// running, it is restarted at the new expiry time.
310    ///
311    /// # Safety
312    ///
313    /// Caller promises keep the timer structure alive until the timer is dead.
314    /// Caller can ensure this by not leaking the returned [`Self::TimerHandle`].
315    unsafe fn start(self, expires: <Self::TimerMode as HrTimerMode>::Expires) -> Self::TimerHandle;
316}
317
318/// A trait for stack allocated timers.
319///
320/// # Safety
321///
322/// Implementers must ensure that `start_scoped` does not return until the
323/// timer is dead and the timer handler is not running.
324pub unsafe trait ScopedHrTimerPointer {
325    /// The operational mode associated with this timer.
326    ///
327    /// This defines how the expiration value is interpreted.
328    type TimerMode: HrTimerMode;
329
330    /// Start the timer to run after `expires` time units and immediately
331    /// after call `f`. When `f` returns, the timer is cancelled.
332    fn start_scoped<T, F>(self, expires: <Self::TimerMode as HrTimerMode>::Expires, f: F) -> T
333    where
334        F: FnOnce() -> T;
335}
336
337// SAFETY: By the safety requirement of [`UnsafeHrTimerPointer`], dropping the
338// handle returned by [`UnsafeHrTimerPointer::start`] ensures that the timer is
339// killed.
340unsafe impl<T> ScopedHrTimerPointer for T
341where
342    T: UnsafeHrTimerPointer,
343{
344    type TimerMode = T::TimerMode;
345
346    fn start_scoped<U, F>(
347        self,
348        expires: <<T as UnsafeHrTimerPointer>::TimerMode as HrTimerMode>::Expires,
349        f: F,
350    ) -> U
351    where
352        F: FnOnce() -> U,
353    {
354        // SAFETY: We drop the timer handle below before returning.
355        let handle = unsafe { UnsafeHrTimerPointer::start(self, expires) };
356        let t = f();
357        drop(handle);
358        t
359    }
360}
361
362/// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a
363/// function to call.
364// This is split from `HrTimerPointer` to make it easier to specify trait bounds.
365pub trait RawHrTimerCallback {
366    /// Type of the parameter passed to [`HrTimerCallback::run`]. It may be
367    /// [`Self`], or a pointer type derived from [`Self`].
368    type CallbackTarget<'a>;
369
370    /// Callback to be called from C when timer fires.
371    ///
372    /// # Safety
373    ///
374    /// Only to be called by C code in the `hrtimer` subsystem. `this` must point
375    /// to the `bindings::hrtimer` structure that was used to start the timer.
376    unsafe extern "C" fn run(this: *mut bindings::hrtimer) -> bindings::hrtimer_restart;
377}
378
379/// Implemented by structs that can be the target of a timer callback.
380pub trait HrTimerCallback {
381    /// The type whose [`RawHrTimerCallback::run`] method will be invoked when
382    /// the timer expires.
383    type Pointer<'a>: RawHrTimerCallback;
384
385    /// Called by the timer logic when the timer fires.
386    fn run(
387        this: <Self::Pointer<'_> as RawHrTimerCallback>::CallbackTarget<'_>,
388        ctx: HrTimerCallbackContext<'_, Self>,
389    ) -> HrTimerRestart
390    where
391        Self: Sized,
392        Self: HasHrTimer<Self>;
393}
394
395/// A handle representing a potentially running timer.
396///
397/// More than one handle representing the same timer might exist.
398///
399/// # Safety
400///
401/// When dropped, the timer represented by this handle must be cancelled, if it
402/// is running. If the timer handler is running when the handle is dropped, the
403/// drop method must wait for the handler to return before returning.
404///
405/// Note: One way to satisfy the safety requirement is to call `Self::cancel` in
406/// the drop implementation for `Self.`
407pub unsafe trait HrTimerHandle {
408    /// Cancel the timer. If the timer is in the running state, block till the
409    /// handler has returned.
410    ///
411    /// Note that the timer might be started by a concurrent start operation. If
412    /// so, the timer might not be in the **stopped** state when this function
413    /// returns.
414    ///
415    /// Returns `true` if the timer was running.
416    fn cancel(&mut self) -> bool;
417}
418
419/// Implemented by structs that contain timer nodes.
420///
421/// Clients of the timer API would usually safely implement this trait by using
422/// the [`crate::impl_has_hr_timer`] macro.
423///
424/// # Safety
425///
426/// Implementers of this trait must ensure that the implementer has a
427/// [`HrTimer`] field and that all trait methods are implemented according to
428/// their documentation. All the methods of this trait must operate on the same
429/// field.
430pub unsafe trait HasHrTimer<T> {
431    /// The operational mode associated with this timer.
432    ///
433    /// This defines how the expiration value is interpreted.
434    type TimerMode: HrTimerMode;
435
436    /// Return a pointer to the [`HrTimer`] within `Self`.
437    ///
438    /// This function is useful to get access to the value without creating
439    /// intermediate references.
440    ///
441    /// # Safety
442    ///
443    /// `this` must be a valid pointer.
444    unsafe fn raw_get_timer(this: *const Self) -> *const HrTimer<T>;
445
446    /// Return a pointer to the struct that is containing the [`HrTimer`] pointed
447    /// to by `ptr`.
448    ///
449    /// This function is useful to get access to the value without creating
450    /// intermediate references.
451    ///
452    /// # Safety
453    ///
454    /// `ptr` must point to a [`HrTimer<T>`] field in a struct of type `Self`.
455    unsafe fn timer_container_of(ptr: *mut HrTimer<T>) -> *mut Self
456    where
457        Self: Sized;
458
459    /// Get pointer to the contained `bindings::hrtimer` struct.
460    ///
461    /// This function is useful to get access to the value without creating
462    /// intermediate references.
463    ///
464    /// # Safety
465    ///
466    /// `this` must be a valid pointer.
467    unsafe fn c_timer_ptr(this: *const Self) -> *const bindings::hrtimer {
468        // SAFETY: `this` is a valid pointer to a `Self`.
469        let timer_ptr = unsafe { Self::raw_get_timer(this) };
470
471        // SAFETY: timer_ptr points to an allocation of at least `HrTimer` size.
472        unsafe { HrTimer::raw_get(timer_ptr) }
473    }
474
475    /// Start the timer contained in the `Self` pointed to by `self_ptr`. If
476    /// it is already running it is removed and inserted.
477    ///
478    /// # Safety
479    ///
480    /// - `this` must point to a valid `Self`.
481    /// - Caller must ensure that the pointee of `this` lives until the timer
482    ///   fires or is canceled.
483    unsafe fn start(this: *const Self, expires: <Self::TimerMode as HrTimerMode>::Expires) {
484        // SAFETY: By function safety requirement, `this` is a valid `Self`.
485        unsafe {
486            bindings::hrtimer_start_range_ns(
487                Self::c_timer_ptr(this).cast_mut(),
488                expires.as_nanos(),
489                0,
490                <Self::TimerMode as HrTimerMode>::C_MODE,
491            );
492        }
493    }
494}
495
496/// Restart policy for timers.
497#[derive(Copy, Clone, PartialEq, Eq, Debug)]
498#[repr(u32)]
499pub enum HrTimerRestart {
500    /// Timer should not be restarted.
501    NoRestart = bindings::hrtimer_restart_HRTIMER_NORESTART,
502    /// Timer should be restarted.
503    Restart = bindings::hrtimer_restart_HRTIMER_RESTART,
504}
505
506impl HrTimerRestart {
507    fn into_c(self) -> bindings::hrtimer_restart {
508        self as bindings::hrtimer_restart
509    }
510}
511
512/// Time representations that can be used as expiration values in [`HrTimer`].
513pub trait HrTimerExpires {
514    /// Converts the expiration time into a nanosecond representation.
515    ///
516    /// This value corresponds to a raw ktime_t value, suitable for passing to kernel
517    /// timer functions. The interpretation (absolute vs relative) depends on the
518    /// associated [HrTimerMode] in use.
519    fn as_nanos(&self) -> i64;
520}
521
522impl<C: ClockSource> HrTimerExpires for Instant<C> {
523    #[inline]
524    fn as_nanos(&self) -> i64 {
525        Instant::<C>::as_nanos(self)
526    }
527}
528
529impl HrTimerExpires for Delta {
530    #[inline]
531    fn as_nanos(&self) -> i64 {
532        Delta::as_nanos(*self)
533    }
534}
535
536mod private {
537    use crate::time::ClockSource;
538
539    pub trait Sealed {}
540
541    impl<C: ClockSource> Sealed for super::AbsoluteMode<C> {}
542    impl<C: ClockSource> Sealed for super::RelativeMode<C> {}
543    impl<C: ClockSource> Sealed for super::AbsolutePinnedMode<C> {}
544    impl<C: ClockSource> Sealed for super::RelativePinnedMode<C> {}
545    impl<C: ClockSource> Sealed for super::AbsoluteSoftMode<C> {}
546    impl<C: ClockSource> Sealed for super::RelativeSoftMode<C> {}
547    impl<C: ClockSource> Sealed for super::AbsolutePinnedSoftMode<C> {}
548    impl<C: ClockSource> Sealed for super::RelativePinnedSoftMode<C> {}
549    impl<C: ClockSource> Sealed for super::AbsoluteHardMode<C> {}
550    impl<C: ClockSource> Sealed for super::RelativeHardMode<C> {}
551    impl<C: ClockSource> Sealed for super::AbsolutePinnedHardMode<C> {}
552    impl<C: ClockSource> Sealed for super::RelativePinnedHardMode<C> {}
553}
554
555/// Operational mode of [`HrTimer`].
556pub trait HrTimerMode: private::Sealed {
557    /// The C representation of hrtimer mode.
558    const C_MODE: bindings::hrtimer_mode;
559
560    /// Type representing the clock source.
561    type Clock: ClockSource;
562
563    /// Type representing the expiration specification (absolute or relative time).
564    type Expires: HrTimerExpires;
565}
566
567/// Timer that expires at a fixed point in time.
568pub struct AbsoluteMode<C: ClockSource>(PhantomData<C>);
569
570impl<C: ClockSource> HrTimerMode for AbsoluteMode<C> {
571    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS;
572
573    type Clock = C;
574    type Expires = Instant<C>;
575}
576
577/// Timer that expires after a delay from now.
578pub struct RelativeMode<C: ClockSource>(PhantomData<C>);
579
580impl<C: ClockSource> HrTimerMode for RelativeMode<C> {
581    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL;
582
583    type Clock = C;
584    type Expires = Delta;
585}
586
587/// Timer with absolute expiration time, pinned to its current CPU.
588pub struct AbsolutePinnedMode<C: ClockSource>(PhantomData<C>);
589impl<C: ClockSource> HrTimerMode for AbsolutePinnedMode<C> {
590    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_PINNED;
591
592    type Clock = C;
593    type Expires = Instant<C>;
594}
595
596/// Timer with relative expiration time, pinned to its current CPU.
597pub struct RelativePinnedMode<C: ClockSource>(PhantomData<C>);
598impl<C: ClockSource> HrTimerMode for RelativePinnedMode<C> {
599    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_PINNED;
600
601    type Clock = C;
602    type Expires = Delta;
603}
604
605/// Timer with absolute expiration, handled in soft irq context.
606pub struct AbsoluteSoftMode<C: ClockSource>(PhantomData<C>);
607impl<C: ClockSource> HrTimerMode for AbsoluteSoftMode<C> {
608    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_SOFT;
609
610    type Clock = C;
611    type Expires = Instant<C>;
612}
613
614/// Timer with relative expiration, handled in soft irq context.
615pub struct RelativeSoftMode<C: ClockSource>(PhantomData<C>);
616impl<C: ClockSource> HrTimerMode for RelativeSoftMode<C> {
617    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_SOFT;
618
619    type Clock = C;
620    type Expires = Delta;
621}
622
623/// Timer with absolute expiration, pinned to CPU and handled in soft irq context.
624pub struct AbsolutePinnedSoftMode<C: ClockSource>(PhantomData<C>);
625impl<C: ClockSource> HrTimerMode for AbsolutePinnedSoftMode<C> {
626    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_PINNED_SOFT;
627
628    type Clock = C;
629    type Expires = Instant<C>;
630}
631
632/// Timer with absolute expiration, pinned to CPU and handled in soft irq context.
633pub struct RelativePinnedSoftMode<C: ClockSource>(PhantomData<C>);
634impl<C: ClockSource> HrTimerMode for RelativePinnedSoftMode<C> {
635    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_PINNED_SOFT;
636
637    type Clock = C;
638    type Expires = Delta;
639}
640
641/// Timer with absolute expiration, handled in hard irq context.
642pub struct AbsoluteHardMode<C: ClockSource>(PhantomData<C>);
643impl<C: ClockSource> HrTimerMode for AbsoluteHardMode<C> {
644    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_HARD;
645
646    type Clock = C;
647    type Expires = Instant<C>;
648}
649
650/// Timer with relative expiration, handled in hard irq context.
651pub struct RelativeHardMode<C: ClockSource>(PhantomData<C>);
652impl<C: ClockSource> HrTimerMode for RelativeHardMode<C> {
653    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_HARD;
654
655    type Clock = C;
656    type Expires = Delta;
657}
658
659/// Timer with absolute expiration, pinned to CPU and handled in hard irq context.
660pub struct AbsolutePinnedHardMode<C: ClockSource>(PhantomData<C>);
661impl<C: ClockSource> HrTimerMode for AbsolutePinnedHardMode<C> {
662    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_PINNED_HARD;
663
664    type Clock = C;
665    type Expires = Instant<C>;
666}
667
668/// Timer with relative expiration, pinned to CPU and handled in hard irq context.
669pub struct RelativePinnedHardMode<C: ClockSource>(PhantomData<C>);
670impl<C: ClockSource> HrTimerMode for RelativePinnedHardMode<C> {
671    const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_PINNED_HARD;
672
673    type Clock = C;
674    type Expires = Delta;
675}
676
677/// Privileged smart-pointer for a [`HrTimer`] callback context.
678///
679/// Many [`HrTimer`] methods can only be called in two situations:
680///
681/// * When the caller has exclusive access to the `HrTimer` and the `HrTimer` is guaranteed not to
682///   be running.
683/// * From within the context of an `HrTimer`'s callback method.
684///
685/// This type provides access to said methods from within a timer callback context.
686///
687/// # Invariants
688///
689/// * The existence of this type means the caller is currently within the callback for an
690///   [`HrTimer`].
691/// * `self.0` always points to a live instance of [`HrTimer<T>`].
692pub struct HrTimerCallbackContext<'a, T: HasHrTimer<T>>(NonNull<HrTimer<T>>, PhantomData<&'a ()>);
693
694impl<'a, T: HasHrTimer<T>> HrTimerCallbackContext<'a, T> {
695    /// Create a new [`HrTimerCallbackContext`].
696    ///
697    /// # Safety
698    ///
699    /// This function relies on the caller being within the context of a timer callback, so it must
700    /// not be used anywhere except for within implementations of [`RawHrTimerCallback::run`]. The
701    /// caller promises that `timer` points to a valid initialized instance of
702    /// [`bindings::hrtimer`].
703    ///
704    /// The returned `Self` must not outlive the function context of [`RawHrTimerCallback::run`]
705    /// where this function is called.
706    pub(crate) unsafe fn from_raw(timer: *mut HrTimer<T>) -> Self {
707        // SAFETY: The caller guarantees `timer` is a valid pointer to an initialized
708        // `bindings::hrtimer`
709        // INVARIANT: Our safety contract ensures that we're within the context of a timer callback
710        // and that `timer` points to a live instance of `HrTimer<T>`.
711        Self(unsafe { NonNull::new_unchecked(timer) }, PhantomData)
712    }
713
714    /// Conditionally forward the timer.
715    ///
716    /// This function is identical to [`HrTimer::forward()`] except that it may only be used from
717    /// within the context of a [`HrTimer`] callback.
718    pub fn forward(&mut self, now: HrTimerInstant<T>, interval: Delta) -> u64 {
719        // SAFETY:
720        // - We are guaranteed to be within the context of a timer callback by our type invariants
721        // - By our type invariants, `self.0` always points to a valid `HrTimer<T>`
722        unsafe { HrTimer::<T>::raw_forward(self.0.as_ptr(), now, interval) }
723    }
724
725    /// Conditionally forward the timer.
726    ///
727    /// This is a variant of [`HrTimerCallbackContext::forward()`] that uses an interval after the
728    /// current time of the base clock for the [`HrTimer`].
729    pub fn forward_now(&mut self, duration: Delta) -> u64 {
730        self.forward(HrTimerInstant::<T>::now(), duration)
731    }
732}
733
734/// Use to implement the [`HasHrTimer<T>`] trait.
735///
736/// See [`module`] documentation for an example.
737///
738/// [`module`]: crate::time::hrtimer
739#[macro_export]
740macro_rules! impl_has_hr_timer {
741    (
742        impl$({$($generics:tt)*})?
743            HasHrTimer<$timer_type:ty>
744            for $self:ty
745        {
746            mode : $mode:ty,
747            field : self.$field:ident $(,)?
748        }
749        $($rest:tt)*
750    ) => {
751        // SAFETY: This implementation of `raw_get_timer` only compiles if the
752        // field has the right type.
753        unsafe impl$(<$($generics)*>)? $crate::time::hrtimer::HasHrTimer<$timer_type> for $self {
754            type TimerMode = $mode;
755
756            #[inline]
757            unsafe fn raw_get_timer(
758                this: *const Self,
759            ) -> *const $crate::time::hrtimer::HrTimer<$timer_type> {
760                // SAFETY: The caller promises that the pointer is not dangling.
761                unsafe { ::core::ptr::addr_of!((*this).$field) }
762            }
763
764            #[inline]
765            unsafe fn timer_container_of(
766                ptr: *mut $crate::time::hrtimer::HrTimer<$timer_type>,
767            ) -> *mut Self {
768                // SAFETY: As per the safety requirement of this function, `ptr`
769                // is pointing inside a `$timer_type`.
770                unsafe { ::kernel::container_of!(ptr, $timer_type, $field) }
771            }
772        }
773    }
774}
775
776mod arc;
777pub use arc::ArcHrTimerHandle;
778mod pin;
779pub use pin::PinHrTimerHandle;
780mod pin_mut;
781pub use pin_mut::PinMutHrTimerHandle;
782// `box` is a reserved keyword, so prefix with `t` for timer
783mod tbox;
784pub use tbox::BoxHrTimerHandle;