projects/linux·blob uaccess-cleanups · refs

1120 lines · 38.5 KiB

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//!
70//! When a type implements both `HrTimerPointer` and `Clone`, it is possible to
71//! issue the `start` operation while the timer is in the **started** state. In
72//! this case the `start` operation is equivalent to the `restart` operation.
73//!
74//! # Examples
75//!
76//! ## Using an intrusive timer living in a [`Box`]
77//!
78//! ```
79//! # use kernel::{
80//! # alloc::flags,
81//! # impl_has_hr_timer,
82//! # prelude::*,
83//! # sync::{
84//! # atomic::{ordering, Atomic},
85//! # completion::Completion,
86//! # Arc,
87//! # },
88//! # time::{
89//! # hrtimer::{
90//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer,
91//! # HrTimerRestart, HrTimerCallbackContext
92//! # },
93//! # Delta, Monotonic,
94//! # },
95//! # };
96//!
97//! #[pin_data]
98//! struct Shared {
99//! #[pin]
100//! flag: Atomic<u64>,
101//! #[pin]
102//! cond: Completion,
103//! }
104//!
105//! impl Shared {
106//! fn new() -> impl PinInit<Self> {
107//! pin_init!(Self {
108//! flag <- Atomic::new(0),
109//! cond <- Completion::new(),
110//! })
111//! }
112//! }
113//!
114//! #[pin_data]
115//! struct BoxIntrusiveHrTimer {
116//! #[pin]
117//! timer: HrTimer<Self>,
118//! shared: Arc<Shared>,
119//! }
120//!
121//! impl BoxIntrusiveHrTimer {
122//! fn new() -> impl PinInit<Self, kernel::error::Error> {
123//! try_pin_init!(Self {
124//! timer <- HrTimer::new(),
125//! shared: Arc::pin_init(Shared::new(), flags::GFP_KERNEL)?,
126//! })
127//! }
128//! }
129//!
130//! impl HrTimerCallback for BoxIntrusiveHrTimer {
131//! type Pointer<'a> = Pin<KBox<Self>>;
132//!
133//! fn run(this: Pin<&mut Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
134//! pr_info!("Timer called\n");
135//!
136//! let flag = this.shared.flag.fetch_add(1, ordering::Full);
137//! this.shared.cond.complete_all();
138//!
139//! if flag == 4 {
140//! HrTimerRestart::NoRestart
141//! } else {
142//! HrTimerRestart::Restart
143//! }
144//! }
145//! }
146//!
147//! impl_has_hr_timer! {
148//! impl HasHrTimer<Self> for BoxIntrusiveHrTimer {
149//! mode: RelativeMode<Monotonic>, field: self.timer
150//! }
151//! }
152//!
153//! let has_timer = Box::pin_init(BoxIntrusiveHrTimer::new(), GFP_KERNEL)?;
154//! let shared = has_timer.shared.clone();
155//! let _handle = has_timer.start(Delta::from_micros(200));
156//!
157//! while shared.flag.load(ordering::Relaxed) != 5 {
158//! shared.cond.wait_for_completion();
159//! }
160//!
161//! pr_info!("Counted to 5\n");
162//! # Ok::<(), kernel::error::Error>(())
163//! ```
164//!
165//! ## Using an intrusive timer in an [`Arc`]
166//!
167//! ```
168//! # use kernel::{
169//! # alloc::flags,
170//! # impl_has_hr_timer,
171//! # prelude::*,
172//! # sync::{
173//! # atomic::{ordering, Atomic},
174//! # completion::Completion,
175//! # Arc, ArcBorrow,
176//! # },
177//! # time::{
178//! # hrtimer::{
179//! # RelativeMode, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
180//! # HasHrTimer, HrTimerCallbackContext
181//! # },
182//! # Delta, Monotonic,
183//! # },
184//! # };
185//!
186//! #[pin_data]
187//! struct ArcIntrusiveHrTimer {
188//! #[pin]
189//! timer: HrTimer<Self>,
190//! #[pin]
191//! flag: Atomic<u64>,
192//! #[pin]
193//! cond: Completion,
194//! }
195//!
196//! impl ArcIntrusiveHrTimer {
197//! fn new() -> impl PinInit<Self> {
198//! pin_init!(Self {
199//! timer <- HrTimer::new(),
200//! flag <- Atomic::new(0),
201//! cond <- Completion::new(),
202//! })
203//! }
204//! }
205//!
206//! impl HrTimerCallback for ArcIntrusiveHrTimer {
207//! type Pointer<'a> = Arc<Self>;
208//!
209//! fn run(
210//! this: ArcBorrow<'_, Self>,
211//! _ctx: HrTimerCallbackContext<'_, Self>,
212//! ) -> HrTimerRestart {
213//! pr_info!("Timer called\n");
214//!
215//! let flag = this.flag.fetch_add(1, ordering::Full);
216//! this.cond.complete_all();
217//!
218//! if flag == 4 {
219//! HrTimerRestart::NoRestart
220//! } else {
221//! HrTimerRestart::Restart
222//! }
223//! }
224//! }
225//!
226//! impl_has_hr_timer! {
227//! impl HasHrTimer<Self> for ArcIntrusiveHrTimer {
228//! mode: RelativeMode<Monotonic>, field: self.timer
229//! }
230//! }
231//!
232//! let has_timer = Arc::pin_init(ArcIntrusiveHrTimer::new(), GFP_KERNEL)?;
233//! let _handle = has_timer.clone().start(Delta::from_micros(200));
234//!
235//! while has_timer.flag.load(ordering::Relaxed) != 5 {
236//! has_timer.cond.wait_for_completion();
237//! }
238//!
239//! pr_info!("Counted to 5\n");
240//! # Ok::<(), kernel::error::Error>(())
241//! ```
242//!
243//! ## Using a stack-based timer
244//!
245//! ```
246//! # use kernel::{
247//! # impl_has_hr_timer,
248//! # prelude::*,
249//! # sync::{
250//! # atomic::{ordering, Atomic},
251//! # completion::Completion,
252//! # },
253//! # time::{
254//! # hrtimer::{
255//! # ScopedHrTimerPointer, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
256//! # HasHrTimer, RelativeMode, HrTimerCallbackContext
257//! # },
258//! # Delta, Monotonic,
259//! # },
260//! # };
261//! # use pin_init::stack_pin_init;
262//!
263//! #[pin_data]
264//! struct IntrusiveHrTimer {
265//! #[pin]
266//! timer: HrTimer<Self>,
267//! #[pin]
268//! flag: Atomic<u64>,
269//! #[pin]
270//! cond: Completion,
271//! }
272//!
273//! impl IntrusiveHrTimer {
274//! fn new() -> impl PinInit<Self> {
275//! pin_init!(Self {
276//! timer <- HrTimer::new(),
277//! flag <- Atomic::new(0),
278//! cond <- Completion::new(),
279//! })
280//! }
281//! }
282//!
283//! impl HrTimerCallback for IntrusiveHrTimer {
284//! type Pointer<'a> = Pin<&'a Self>;
285//!
286//! fn run(this: Pin<&Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
287//! pr_info!("Timer called\n");
288//!
289//! this.flag.store(1, ordering::Release);
290//! this.cond.complete_all();
291//!
292//! HrTimerRestart::NoRestart
293//! }
294//! }
295//!
296//! impl_has_hr_timer! {
297//! impl HasHrTimer<Self> for IntrusiveHrTimer {
298//! mode: RelativeMode<Monotonic>, field: self.timer
299//! }
300//! }
301//!
302//! stack_pin_init!( let has_timer = IntrusiveHrTimer::new() );
303//! has_timer.as_ref().start_scoped(Delta::from_micros(200), || {
304//! while has_timer.flag.load(ordering::Relaxed) != 1 {
305//! has_timer.cond.wait_for_completion();
306//! }
307//! });
308//!
309//! pr_info!("Flag raised\n");
310//! # Ok::<(), kernel::error::Error>(())
311//! ```
312//!
313//! ## Using a mutable stack-based timer
314//!
315//! ```
316//! # use kernel::{
317//! # alloc::flags,
318//! # impl_has_hr_timer,
319//! # prelude::*,
320//! # sync::{
321//! # atomic::{ordering, Atomic},
322//! # completion::Completion,
323//! # Arc,
324//! # },
325//! # time::{
326//! # hrtimer::{
327//! # ScopedHrTimerPointer, HrTimer, HrTimerCallback, HrTimerPointer, HrTimerRestart,
328//! # HasHrTimer, RelativeMode, HrTimerCallbackContext
329//! # },
330//! # Delta, Monotonic,
331//! # },
332//! # };
333//! # use pin_init::stack_try_pin_init;
334//!
335//! #[pin_data]
336//! struct Shared {
337//! #[pin]
338//! flag: Atomic<u64>,
339//! #[pin]
340//! cond: Completion,
341//! }
342//!
343//! impl Shared {
344//! fn new() -> impl PinInit<Self> {
345//! pin_init!(Self {
346//! flag <- Atomic::new(0),
347//! cond <- Completion::new(),
348//! })
349//! }
350//! }
351//!
352//! #[pin_data]
353//! struct IntrusiveHrTimer {
354//! #[pin]
355//! timer: HrTimer<Self>,
356//! shared: Arc<Shared>,
357//! }
358//!
359//! impl IntrusiveHrTimer {
360//! fn new() -> impl PinInit<Self, kernel::error::Error> {
361//! try_pin_init!(Self {
362//! timer <- HrTimer::new(),
363//! shared: Arc::pin_init(Shared::new(), flags::GFP_KERNEL)?,
364//! })
365//! }
366//! }
367//!
368//! impl HrTimerCallback for IntrusiveHrTimer {
369//! type Pointer<'a> = Pin<&'a mut Self>;
370//!
371//! fn run(this: Pin<&mut Self>, _ctx: HrTimerCallbackContext<'_, Self>) -> HrTimerRestart {
372//! pr_info!("Timer called\n");
373//!
374//! let flag = this.shared.flag.fetch_add(1, ordering::Full);
375//! this.shared.cond.complete_all();
376//!
377//! if flag == 4 {
378//! HrTimerRestart::NoRestart
379//! } else {
380//! HrTimerRestart::Restart
381//! }
382//! }
383//! }
384//!
385//! impl_has_hr_timer! {
386//! impl HasHrTimer<Self> for IntrusiveHrTimer {
387//! mode: RelativeMode<Monotonic>, field: self.timer
388//! }
389//! }
390//!
391//! stack_try_pin_init!( let has_timer =? IntrusiveHrTimer::new() );
392//! let shared = has_timer.shared.clone();
393//!
394//! has_timer.as_mut().start_scoped(Delta::from_micros(200), || {
395//! while shared.flag.load(ordering::Relaxed) != 5 {
396//! shared.cond.wait_for_completion();
397//! }
398//! });
399//!
400//! pr_info!("Counted to 5\n");
401//! # Ok::<(), kernel::error::Error>(())
402//! ```
403//!
404//! [`Arc`]: kernel::sync::Arc
405
406use super::{ClockSource, Delta, Instant};
407use crate::{prelude::*, types::Opaque};
408use core::{marker::PhantomData, ptr::NonNull};
409use pin_init::PinInit;
410
411/// A type-alias to refer to the [`Instant<C>`] for a given `T` from [`HrTimer<T>`].
412///
413/// Where `C` is the [`ClockSource`] of the [`HrTimer`].
414pub type HrTimerInstant<T> = Instant<<<T as HasHrTimer<T>>::TimerMode as HrTimerMode>::Clock>;
415
416/// A timer backed by a C `struct hrtimer`.
417///
418/// # Invariants
419///
420/// * `self.timer` is initialized by `bindings::hrtimer_setup`.
421#[pin_data]
422#[repr(C)]
423pub struct HrTimer<T> {
424 #[pin]
425 timer: Opaque<bindings::hrtimer>,
426 _t: PhantomData<T>,
427}
428
429// SAFETY: Ownership of an `HrTimer` can be moved to other threads and
430// used/dropped from there.
431unsafe impl<T> Send for HrTimer<T> {}
432
433// SAFETY: Timer operations are locked on the C side, so it is safe to operate
434// on a timer from multiple threads.
435unsafe impl<T> Sync for HrTimer<T> {}
436
437impl<T> HrTimer<T> {
438 /// Return an initializer for a new timer instance.
439 pub fn new() -> impl PinInit<Self>
440 where
441 T: HrTimerCallback,
442 T: HasHrTimer<T>,
443 {
444 pin_init!(Self {
445 // INVARIANT: We initialize `timer` with `hrtimer_setup` below.
446 timer <- Opaque::ffi_init(move |place: *mut bindings::hrtimer| {
447 // SAFETY: By design of `pin_init!`, `place` is a pointer to a
448 // live allocation. hrtimer_setup will initialize `place` and
449 // does not require `place` to be initialized prior to the call.
450 unsafe {
451 bindings::hrtimer_setup(
452 place,
453 Some(T::Pointer::run),
454 <<T as HasHrTimer<T>>::TimerMode as HrTimerMode>::Clock::ID,
455 <T as HasHrTimer<T>>::TimerMode::C_MODE,
456 );
457 }
458 }),
459 _t: PhantomData,
460 })
461 }
462
463 /// Get a pointer to the contained `bindings::hrtimer`.
464 ///
465 /// This function is useful to get access to the value without creating
466 /// intermediate references.
467 ///
468 /// # Safety
469 ///
470 /// `this` must point to a live allocation of at least the size of `Self`.
471 unsafe fn raw_get(this: *const Self) -> *mut bindings::hrtimer {
472 // SAFETY: The field projection to `timer` does not go out of bounds,
473 // because the caller of this function promises that `this` points to an
474 // allocation of at least the size of `Self`.
475 unsafe { Opaque::cast_into(core::ptr::addr_of!((*this).timer)) }
476 }
477
478 /// Cancel an initialized and potentially running timer.
479 ///
480 /// If the timer handler is running, this function will block until the
481 /// handler returns.
482 ///
483 /// Note that the timer might be started by a concurrent start operation. If
484 /// so, the timer might not be in the **stopped** state when this function
485 /// returns.
486 ///
487 /// Users of the `HrTimer` API would not usually call this method directly.
488 /// Instead they would use the safe [`HrTimerHandle::cancel`] on the handle
489 /// returned when the timer was started.
490 ///
491 /// This function is useful to get access to the value without creating
492 /// intermediate references.
493 ///
494 /// # Safety
495 ///
496 /// `this` must point to a valid `Self`.
497 pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool {
498 // SAFETY: `this` points to an allocation of at least `HrTimer` size.
499 let c_timer_ptr = unsafe { HrTimer::raw_get(this) };
500
501 // If the handler is running, this will wait for the handler to return
502 // before returning.
503 // SAFETY: `c_timer_ptr` is initialized and valid. Synchronization is
504 // handled on the C side.
505 unsafe { bindings::hrtimer_cancel(c_timer_ptr) != 0 }
506 }
507
508 /// Forward the timer expiry for a given timer pointer.
509 ///
510 /// # Safety
511 ///
512 /// - `self_ptr` must point to a valid `Self`.
513 /// - The caller must either have exclusive access to the data pointed at by `self_ptr`, or be
514 /// within the context of the timer callback.
515 #[inline]
516 unsafe fn raw_forward(self_ptr: *mut Self, now: HrTimerInstant<T>, interval: Delta) -> u64
517 where
518 T: HasHrTimer<T>,
519 {
520 // SAFETY:
521 // * The C API requirements for this function are fulfilled by our safety contract.
522 // * `self_ptr` is guaranteed to point to a valid `Self` via our safety contract
523 unsafe {
524 bindings::hrtimer_forward(Self::raw_get(self_ptr), now.as_nanos(), interval.as_nanos())
525 }
526 }
527
528 /// Conditionally forward the timer.
529 ///
530 /// If the timer expires after `now`, this function does nothing and returns 0. If the timer
531 /// expired at or before `now`, this function forwards the timer by `interval` until the timer
532 /// expires after `now` and then returns the number of times the timer was forwarded by
533 /// `interval`.
534 ///
535 /// This function is mainly useful for timer types which can provide exclusive access to the
536 /// timer when the timer is not running. For forwarding the timer from within the timer callback
537 /// context, see [`HrTimerCallbackContext::forward()`].
538 ///
539 /// Returns the number of overruns that occurred as a result of the timer expiry change.
540 pub fn forward(self: Pin<&mut Self>, now: HrTimerInstant<T>, interval: Delta) -> u64
541 where
542 T: HasHrTimer<T>,
543 {
544 // SAFETY: `raw_forward` does not move `Self`
545 let this = unsafe { self.get_unchecked_mut() };
546
547 // SAFETY: By existence of `Pin<&mut Self>`, the pointer passed to `raw_forward` points to a
548 // valid `Self` that we have exclusive access to.
549 unsafe { Self::raw_forward(this, now, interval) }
550 }
551
552 /// Conditionally forward the timer.
553 ///
554 /// This is a variant of [`forward()`](Self::forward) that uses an interval after the current
555 /// time of the base clock for the [`HrTimer`].
556 pub fn forward_now(self: Pin<&mut Self>, interval: Delta) -> u64
557 where
558 T: HasHrTimer<T>,
559 {
560 self.forward(HrTimerInstant::<T>::now(), interval)
561 }
562
563 /// Return the time expiry for this [`HrTimer`].
564 ///
565 /// This value should only be used as a snapshot, as the actual expiry time could change after
566 /// this function is called.
567 pub fn expires(&self) -> HrTimerInstant<T>
568 where
569 T: HasHrTimer<T>,
570 {
571 // SAFETY: `self` is an immutable reference and thus always points to a valid `HrTimer`.
572 let c_timer_ptr = unsafe { HrTimer::raw_get(self) };
573
574 // SAFETY:
575 // - Timers cannot have negative ktime_t values as their expiration time.
576 // - There's no actual locking here, a racy read is fine and expected
577 unsafe {
578 Instant::from_ktime(
579 // This `read_volatile` is intended to correspond to a READ_ONCE call.
580 // FIXME(read_once): Replace with `read_once` when available on the Rust side.
581 core::ptr::read_volatile(&raw const ((*c_timer_ptr).node.expires)),
582 )
583 }
584 }
585}
586
587/// Implemented by pointer types that point to structs that contain a [`HrTimer`].
588///
589/// `Self` must be [`Sync`] because it is passed to timer callbacks in another
590/// thread of execution (hard or soft interrupt context).
591///
592/// Starting a timer returns a [`HrTimerHandle`] that can be used to manipulate
593/// the timer. Note that it is OK to call the start function repeatedly, and
594/// that more than one [`HrTimerHandle`] associated with a [`HrTimerPointer`] may
595/// exist. A timer can be manipulated through any of the handles, and a handle
596/// may represent a cancelled timer.
597pub trait HrTimerPointer: Sync + Sized {
598 /// The operational mode associated with this timer.
599 ///
600 /// This defines how the expiration value is interpreted.
601 type TimerMode: HrTimerMode;
602
603 /// A handle representing a started or restarted timer.
604 ///
605 /// If the timer is running or if the timer callback is executing when the
606 /// handle is dropped, the drop method of [`HrTimerHandle`] should not return
607 /// until the timer is stopped and the callback has completed.
608 ///
609 /// Note: When implementing this trait, consider that it is not unsafe to
610 /// leak the handle.
611 type TimerHandle: HrTimerHandle;
612
613 /// Start the timer with expiry after `expires` time units. If the timer was
614 /// already running, it is restarted with the new expiry time.
615 fn start(self, expires: <Self::TimerMode as HrTimerMode>::Expires) -> Self::TimerHandle;
616}
617
618/// Unsafe version of [`HrTimerPointer`] for situations where leaking the
619/// [`HrTimerHandle`] returned by `start` would be unsound. This is the case for
620/// stack allocated timers.
621///
622/// Typical implementers are pinned references such as [`Pin<&T>`].
623///
624/// # Safety
625///
626/// Implementers of this trait must ensure that instances of types implementing
627/// [`UnsafeHrTimerPointer`] outlives any associated [`HrTimerPointer::TimerHandle`]
628/// instances.
629pub unsafe trait UnsafeHrTimerPointer: Sync + Sized {
630 /// The operational mode associated with this timer.
631 ///
632 /// This defines how the expiration value is interpreted.
633 type TimerMode: HrTimerMode;
634
635 /// A handle representing a running timer.
636 ///
637 /// # Safety
638 ///
639 /// If the timer is running, or if the timer callback is executing when the
640 /// handle is dropped, the drop method of [`Self::TimerHandle`] must not return
641 /// until the timer is stopped and the callback has completed.
642 type TimerHandle: HrTimerHandle;
643
644 /// Start the timer after `expires` time units. If the timer was already
645 /// running, it is restarted at the new expiry time.
646 ///
647 /// # Safety
648 ///
649 /// Caller promises keep the timer structure alive until the timer is dead.
650 /// Caller can ensure this by not leaking the returned [`Self::TimerHandle`].
651 unsafe fn start(self, expires: <Self::TimerMode as HrTimerMode>::Expires) -> Self::TimerHandle;
652}
653
654/// A trait for stack allocated timers.
655///
656/// # Safety
657///
658/// Implementers must ensure that `start_scoped` does not return until the
659/// timer is dead and the timer handler is not running.
660pub unsafe trait ScopedHrTimerPointer {
661 /// The operational mode associated with this timer.
662 ///
663 /// This defines how the expiration value is interpreted.
664 type TimerMode: HrTimerMode;
665
666 /// Start the timer to run after `expires` time units and immediately
667 /// after call `f`. When `f` returns, the timer is cancelled.
668 fn start_scoped<T, F>(self, expires: <Self::TimerMode as HrTimerMode>::Expires, f: F) -> T
669 where
670 F: FnOnce() -> T;
671}
672
673// SAFETY: By the safety requirement of [`UnsafeHrTimerPointer`], dropping the
674// handle returned by [`UnsafeHrTimerPointer::start`] ensures that the timer is
675// killed.
676unsafe impl<T> ScopedHrTimerPointer for T
677where
678 T: UnsafeHrTimerPointer,
679{
680 type TimerMode = T::TimerMode;
681
682 fn start_scoped<U, F>(
683 self,
684 expires: <<T as UnsafeHrTimerPointer>::TimerMode as HrTimerMode>::Expires,
685 f: F,
686 ) -> U
687 where
688 F: FnOnce() -> U,
689 {
690 // SAFETY: We drop the timer handle below before returning.
691 let handle = unsafe { UnsafeHrTimerPointer::start(self, expires) };
692 let t = f();
693 drop(handle);
694 t
695 }
696}
697
698/// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a
699/// function to call.
700// This is split from `HrTimerPointer` to make it easier to specify trait bounds.
701pub trait RawHrTimerCallback {
702 /// Type of the parameter passed to [`HrTimerCallback::run`]. It may be
703 /// [`Self`], or a pointer type derived from [`Self`].
704 type CallbackTarget<'a>;
705
706 /// Callback to be called from C when timer fires.
707 ///
708 /// # Safety
709 ///
710 /// Only to be called by C code in the `hrtimer` subsystem. `this` must point
711 /// to the `bindings::hrtimer` structure that was used to start the timer.
712 unsafe extern "C" fn run(this: *mut bindings::hrtimer) -> bindings::hrtimer_restart;
713}
714
715/// Implemented by structs that can be the target of a timer callback.
716pub trait HrTimerCallback {
717 /// The type whose [`RawHrTimerCallback::run`] method will be invoked when
718 /// the timer expires.
719 type Pointer<'a>: RawHrTimerCallback;
720
721 /// Called by the timer logic when the timer fires.
722 fn run(
723 this: <Self::Pointer<'_> as RawHrTimerCallback>::CallbackTarget<'_>,
724 ctx: HrTimerCallbackContext<'_, Self>,
725 ) -> HrTimerRestart
726 where
727 Self: Sized,
728 Self: HasHrTimer<Self>;
729}
730
731/// A handle representing a potentially running timer.
732///
733/// More than one handle representing the same timer might exist.
734///
735/// # Safety
736///
737/// When dropped, the timer represented by this handle must be cancelled, if it
738/// is running. If the timer handler is running when the handle is dropped, the
739/// drop method must wait for the handler to return before returning.
740///
741/// Note: One way to satisfy the safety requirement is to call `Self::cancel` in
742/// the drop implementation for `Self.`
743pub unsafe trait HrTimerHandle {
744 /// Cancel the timer. If the timer is in the running state, block till the
745 /// handler has returned.
746 ///
747 /// Note that the timer might be started by a concurrent start operation. If
748 /// so, the timer might not be in the **stopped** state when this function
749 /// returns.
750 ///
751 /// Returns `true` if the timer was running.
752 fn cancel(&mut self) -> bool;
753}
754
755/// Implemented by structs that contain timer nodes.
756///
757/// Clients of the timer API would usually safely implement this trait by using
758/// the [`crate::impl_has_hr_timer`] macro.
759///
760/// # Safety
761///
762/// Implementers of this trait must ensure that the implementer has a
763/// [`HrTimer`] field and that all trait methods are implemented according to
764/// their documentation. All the methods of this trait must operate on the same
765/// field.
766pub unsafe trait HasHrTimer<T> {
767 /// The operational mode associated with this timer.
768 ///
769 /// This defines how the expiration value is interpreted.
770 type TimerMode: HrTimerMode;
771
772 /// Return a pointer to the [`HrTimer`] within `Self`.
773 ///
774 /// This function is useful to get access to the value without creating
775 /// intermediate references.
776 ///
777 /// # Safety
778 ///
779 /// `this` must be a valid pointer.
780 unsafe fn raw_get_timer(this: *const Self) -> *const HrTimer<T>;
781
782 /// Return a pointer to the struct that is containing the [`HrTimer`] pointed
783 /// to by `ptr`.
784 ///
785 /// This function is useful to get access to the value without creating
786 /// intermediate references.
787 ///
788 /// # Safety
789 ///
790 /// `ptr` must point to a [`HrTimer<T>`] field in a struct of type `Self`.
791 unsafe fn timer_container_of(ptr: *mut HrTimer<T>) -> *mut Self
792 where
793 Self: Sized;
794
795 /// Get pointer to the contained `bindings::hrtimer` struct.
796 ///
797 /// This function is useful to get access to the value without creating
798 /// intermediate references.
799 ///
800 /// # Safety
801 ///
802 /// `this` must be a valid pointer.
803 unsafe fn c_timer_ptr(this: *const Self) -> *const bindings::hrtimer {
804 // SAFETY: `this` is a valid pointer to a `Self`.
805 let timer_ptr = unsafe { Self::raw_get_timer(this) };
806
807 // SAFETY: timer_ptr points to an allocation of at least `HrTimer` size.
808 unsafe { HrTimer::raw_get(timer_ptr) }
809 }
810
811 /// Start the timer contained in the `Self` pointed to by `self_ptr`. If
812 /// it is already running it is removed and inserted.
813 ///
814 /// # Safety
815 ///
816 /// - `this` must point to a valid `Self`.
817 /// - Caller must ensure that the pointee of `this` lives until the timer
818 /// fires or is canceled.
819 unsafe fn start(this: *const Self, expires: <Self::TimerMode as HrTimerMode>::Expires) {
820 // SAFETY: By function safety requirement, `this` is a valid `Self`.
821 unsafe {
822 bindings::hrtimer_start_range_ns(
823 Self::c_timer_ptr(this).cast_mut(),
824 expires.as_nanos(),
825 0,
826 <Self::TimerMode as HrTimerMode>::C_MODE,
827 );
828 }
829 }
830}
831
832/// Restart policy for timers.
833#[derive(Copy, Clone, PartialEq, Eq, Debug)]
834#[repr(u32)]
835pub enum HrTimerRestart {
836 /// Timer should not be restarted.
837 NoRestart = bindings::hrtimer_restart_HRTIMER_NORESTART,
838 /// Timer should be restarted.
839 Restart = bindings::hrtimer_restart_HRTIMER_RESTART,
840}
841
842impl HrTimerRestart {
843 fn into_c(self) -> bindings::hrtimer_restart {
844 self as bindings::hrtimer_restart
845 }
846}
847
848/// Time representations that can be used as expiration values in [`HrTimer`].
849pub trait HrTimerExpires {
850 /// Converts the expiration time into a nanosecond representation.
851 ///
852 /// This value corresponds to a raw ktime_t value, suitable for passing to kernel
853 /// timer functions. The interpretation (absolute vs relative) depends on the
854 /// associated [HrTimerMode] in use.
855 fn as_nanos(&self) -> i64;
856}
857
858impl<C: ClockSource> HrTimerExpires for Instant<C> {
859 #[inline]
860 fn as_nanos(&self) -> i64 {
861 Instant::<C>::as_nanos(self)
862 }
863}
864
865impl HrTimerExpires for Delta {
866 #[inline]
867 fn as_nanos(&self) -> i64 {
868 Delta::as_nanos(*self)
869 }
870}
871
872mod private {
873 use crate::time::ClockSource;
874
875 pub trait Sealed {}
876
877 impl<C: ClockSource> Sealed for super::AbsoluteMode<C> {}
878 impl<C: ClockSource> Sealed for super::RelativeMode<C> {}
879 impl<C: ClockSource> Sealed for super::AbsolutePinnedMode<C> {}
880 impl<C: ClockSource> Sealed for super::RelativePinnedMode<C> {}
881 impl<C: ClockSource> Sealed for super::AbsoluteSoftMode<C> {}
882 impl<C: ClockSource> Sealed for super::RelativeSoftMode<C> {}
883 impl<C: ClockSource> Sealed for super::AbsolutePinnedSoftMode<C> {}
884 impl<C: ClockSource> Sealed for super::RelativePinnedSoftMode<C> {}
885 impl<C: ClockSource> Sealed for super::AbsoluteHardMode<C> {}
886 impl<C: ClockSource> Sealed for super::RelativeHardMode<C> {}
887 impl<C: ClockSource> Sealed for super::AbsolutePinnedHardMode<C> {}
888 impl<C: ClockSource> Sealed for super::RelativePinnedHardMode<C> {}
889}
890
891/// Operational mode of [`HrTimer`].
892pub trait HrTimerMode: private::Sealed {
893 /// The C representation of hrtimer mode.
894 const C_MODE: bindings::hrtimer_mode;
895
896 /// Type representing the clock source.
897 type Clock: ClockSource;
898
899 /// Type representing the expiration specification (absolute or relative time).
900 type Expires: HrTimerExpires;
901}
902
903/// Timer that expires at a fixed point in time.
904pub struct AbsoluteMode<C: ClockSource>(PhantomData<C>);
905
906impl<C: ClockSource> HrTimerMode for AbsoluteMode<C> {
907 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS;
908
909 type Clock = C;
910 type Expires = Instant<C>;
911}
912
913/// Timer that expires after a delay from now.
914pub struct RelativeMode<C: ClockSource>(PhantomData<C>);
915
916impl<C: ClockSource> HrTimerMode for RelativeMode<C> {
917 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL;
918
919 type Clock = C;
920 type Expires = Delta;
921}
922
923/// Timer with absolute expiration time, pinned to its current CPU.
924pub struct AbsolutePinnedMode<C: ClockSource>(PhantomData<C>);
925impl<C: ClockSource> HrTimerMode for AbsolutePinnedMode<C> {
926 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_PINNED;
927
928 type Clock = C;
929 type Expires = Instant<C>;
930}
931
932/// Timer with relative expiration time, pinned to its current CPU.
933pub struct RelativePinnedMode<C: ClockSource>(PhantomData<C>);
934impl<C: ClockSource> HrTimerMode for RelativePinnedMode<C> {
935 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_PINNED;
936
937 type Clock = C;
938 type Expires = Delta;
939}
940
941/// Timer with absolute expiration, handled in soft irq context.
942pub struct AbsoluteSoftMode<C: ClockSource>(PhantomData<C>);
943impl<C: ClockSource> HrTimerMode for AbsoluteSoftMode<C> {
944 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_SOFT;
945
946 type Clock = C;
947 type Expires = Instant<C>;
948}
949
950/// Timer with relative expiration, handled in soft irq context.
951pub struct RelativeSoftMode<C: ClockSource>(PhantomData<C>);
952impl<C: ClockSource> HrTimerMode for RelativeSoftMode<C> {
953 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_SOFT;
954
955 type Clock = C;
956 type Expires = Delta;
957}
958
959/// Timer with absolute expiration, pinned to CPU and handled in soft irq context.
960pub struct AbsolutePinnedSoftMode<C: ClockSource>(PhantomData<C>);
961impl<C: ClockSource> HrTimerMode for AbsolutePinnedSoftMode<C> {
962 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_PINNED_SOFT;
963
964 type Clock = C;
965 type Expires = Instant<C>;
966}
967
968/// Timer with absolute expiration, pinned to CPU and handled in soft irq context.
969pub struct RelativePinnedSoftMode<C: ClockSource>(PhantomData<C>);
970impl<C: ClockSource> HrTimerMode for RelativePinnedSoftMode<C> {
971 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_PINNED_SOFT;
972
973 type Clock = C;
974 type Expires = Delta;
975}
976
977/// Timer with absolute expiration, handled in hard irq context.
978pub struct AbsoluteHardMode<C: ClockSource>(PhantomData<C>);
979impl<C: ClockSource> HrTimerMode for AbsoluteHardMode<C> {
980 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_HARD;
981
982 type Clock = C;
983 type Expires = Instant<C>;
984}
985
986/// Timer with relative expiration, handled in hard irq context.
987pub struct RelativeHardMode<C: ClockSource>(PhantomData<C>);
988impl<C: ClockSource> HrTimerMode for RelativeHardMode<C> {
989 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_HARD;
990
991 type Clock = C;
992 type Expires = Delta;
993}
994
995/// Timer with absolute expiration, pinned to CPU and handled in hard irq context.
996pub struct AbsolutePinnedHardMode<C: ClockSource>(PhantomData<C>);
997impl<C: ClockSource> HrTimerMode for AbsolutePinnedHardMode<C> {
998 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_ABS_PINNED_HARD;
999
1000 type Clock = C;
1001 type Expires = Instant<C>;
1002}
1003
1004/// Timer with relative expiration, pinned to CPU and handled in hard irq context.
1005pub struct RelativePinnedHardMode<C: ClockSource>(PhantomData<C>);
1006impl<C: ClockSource> HrTimerMode for RelativePinnedHardMode<C> {
1007 const C_MODE: bindings::hrtimer_mode = bindings::hrtimer_mode_HRTIMER_MODE_REL_PINNED_HARD;
1008
1009 type Clock = C;
1010 type Expires = Delta;
1011}
1012
1013/// Privileged smart-pointer for a [`HrTimer`] callback context.
1014///
1015/// Many [`HrTimer`] methods can only be called in two situations:
1016///
1017/// * When the caller has exclusive access to the `HrTimer` and the `HrTimer` is guaranteed not to
1018/// be running.
1019/// * From within the context of an `HrTimer`'s callback method.
1020///
1021/// This type provides access to said methods from within a timer callback context.
1022///
1023/// # Invariants
1024///
1025/// * The existence of this type means the caller is currently within the callback for an
1026/// [`HrTimer`].
1027/// * `self.0` always points to a live instance of [`HrTimer<T>`].
1028pub struct HrTimerCallbackContext<'a, T: HasHrTimer<T>>(NonNull<HrTimer<T>>, PhantomData<&'a ()>);
1029
1030impl<'a, T: HasHrTimer<T>> HrTimerCallbackContext<'a, T> {
1031 /// Create a new [`HrTimerCallbackContext`].
1032 ///
1033 /// # Safety
1034 ///
1035 /// This function relies on the caller being within the context of a timer callback, so it must
1036 /// not be used anywhere except for within implementations of [`RawHrTimerCallback::run`]. The
1037 /// caller promises that `timer` points to a valid initialized instance of
1038 /// [`bindings::hrtimer`].
1039 ///
1040 /// The returned `Self` must not outlive the function context of [`RawHrTimerCallback::run`]
1041 /// where this function is called.
1042 pub(crate) unsafe fn from_raw(timer: *mut HrTimer<T>) -> Self {
1043 // SAFETY: The caller guarantees `timer` is a valid pointer to an initialized
1044 // `bindings::hrtimer`
1045 // INVARIANT: Our safety contract ensures that we're within the context of a timer callback
1046 // and that `timer` points to a live instance of `HrTimer<T>`.
1047 Self(unsafe { NonNull::new_unchecked(timer) }, PhantomData)
1048 }
1049
1050 /// Conditionally forward the timer.
1051 ///
1052 /// This function is identical to [`HrTimer::forward()`] except that it may only be used from
1053 /// within the context of a [`HrTimer`] callback.
1054 pub fn forward(&mut self, now: HrTimerInstant<T>, interval: Delta) -> u64 {
1055 // SAFETY:
1056 // - We are guaranteed to be within the context of a timer callback by our type invariants
1057 // - By our type invariants, `self.0` always points to a valid `HrTimer<T>`
1058 unsafe { HrTimer::<T>::raw_forward(self.0.as_ptr(), now, interval) }
1059 }
1060
1061 /// Conditionally forward the timer.
1062 ///
1063 /// This is a variant of [`HrTimerCallbackContext::forward()`] that uses an interval after the
1064 /// current time of the base clock for the [`HrTimer`].
1065 pub fn forward_now(&mut self, duration: Delta) -> u64 {
1066 self.forward(HrTimerInstant::<T>::now(), duration)
1067 }
1068}
1069
1070/// Use to implement the [`HasHrTimer<T>`] trait.
1071///
1072/// See [`module`] documentation for an example.
1073///
1074/// [`module`]: crate::time::hrtimer
1075#[macro_export]
1076macro_rules! impl_has_hr_timer {
1077 (
1078 impl$({$($generics:tt)*})?
1079 HasHrTimer<$timer_type:ty>
1080 for $self:ty
1081 {
1082 mode : $mode:ty,
1083 field : self.$field:ident $(,)?
1084 }
1085 $($rest:tt)*
1086 ) => {
1087 // SAFETY: This implementation of `raw_get_timer` only compiles if the
1088 // field has the right type.
1089 unsafe impl$(<$($generics)*>)? $crate::time::hrtimer::HasHrTimer<$timer_type> for $self {
1090 type TimerMode = $mode;
1091
1092 #[inline]
1093 unsafe fn raw_get_timer(
1094 this: *const Self,
1095 ) -> *const $crate::time::hrtimer::HrTimer<$timer_type> {
1096 // SAFETY: The caller promises that the pointer is not dangling.
1097 unsafe { ::core::ptr::addr_of!((*this).$field) }
1098 }
1099
1100 #[inline]
1101 unsafe fn timer_container_of(
1102 ptr: *mut $crate::time::hrtimer::HrTimer<$timer_type>,
1103 ) -> *mut Self {
1104 // SAFETY: As per the safety requirement of this function, `ptr`
1105 // is pointing inside a `$timer_type`.
1106 unsafe { ::kernel::container_of!(ptr, $timer_type, $field) }
1107 }
1108 }
1109 }
1110}
1111
1112mod arc;
1113pub use arc::ArcHrTimerHandle;
1114mod pin;
1115pub use pin::PinHrTimerHandle;
1116mod pin_mut;
1117pub use pin_mut::PinMutHrTimerHandle;
1118// `box` is a reserved keyword, so prefix with `t` for timer
1119mod tbox;
1120pub use tbox::BoxHrTimerHandle;