kernel/time/hrtimer.rs

1 // SPDX-License-Identifier: GPL-2.0
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.
12 //! - Stopped: initialized but not started, or cancelled, or not restarted.
13 //! - Started: initialized and started or restarted.
14 //! - Running: executing the callback.
30 //!                       +---------------------------------------------------------------------+
35 //!                       |                                      +------------------------+     |
39 //!           +-----------------+      Start      +------------------+           +--------+-----+--+
40 //!           |                 +---------------->|                  |           |                 |
42 //! --------->|    Stopped      |                 |      Started     +---------->|     Running     |
44 //!           |                 |<----------------+                  |           |                 |
45 //!           +-----------------+                 +---------------+--+           +-----------------+
48 //!                                                     +---------+
53 //! A timer is initialized in the **stopped** state. A stopped timer can be
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
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**
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
67 //! A `restart` operation on a timer in the **stopped** state is equivalent to a
75 /// A type-alias to refer to the [`Instant<C>`] for a given `T` from [`HrTimer<T>`].
80 /// A timer backed by a C `struct hrtimer`.
84 /// * `self.timer` is initialized by `bindings::hrtimer_setup`.
89     timer: Opaque<bindings::hrtimer>,
97 // SAFETY: Timer operations are locked on the C side, so it is safe to operate
98 // on a timer from multiple threads.
102     /// Return an initializer for a new timer instance.
103     pub fn new() -> impl PinInit<Self>
109             // INVARIANT: We initialize `timer` with `hrtimer_setup` below.
110             timer <- Opaque::ffi_init(move |place: *mut bindings::hrtimer| {
135     unsafe fn raw_get(this: *const Self) -> *mut bindings::hrtimer {
136         // SAFETY: The field projection to `timer` does not go out of bounds,
139         unsafe { Opaque::cast_into(core::ptr::addr_of!((*this).timer)) }
142     /// Cancel an initialized and potentially running timer.
144     /// If the timer handler is running, this function will block until the
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
153     /// returned when the timer was started.
161     pub(crate) unsafe fn raw_cancel(this: *const Self) -> bool {
172     /// Forward the timer expiry for a given timer pointer.
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.
180     unsafe fn raw_forward(self_ptr: *mut Self, now: HrTimerInstant<T>, interval: Delta) -> u64
192     /// Conditionally forward the timer.
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
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
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
216     /// Conditionally forward the timer.
220     pub fn forward_now(self: Pin<&mut Self>, interval: Delta) -> u64
231     pub fn expires(&self) -> HrTimerInstant<T>
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
253 /// `Self` must be [`Sync`] because it is passed to timer callbacks in another
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
259 /// exist. A timer can be manipulated through any of the handles, and a handle
260 /// may represent a cancelled timer.
262     /// The operational mode associated with this timer.
267     /// A handle representing a started or restarted timer.
269     /// If the timer is running or if the timer callback is executing when the
271     /// until the timer is stopped and the callback has completed.
277     /// Start the timer with expiry after `expires` time units. If the timer was
279     fn start(self, expires: <Self::TimerMode as HrTimerMode>::Expires) -> Self::TimerHandle;
294     /// The operational mode associated with this timer.
299     /// A handle representing a running timer.
303     /// If the timer is running, or if the timer callback is executing when the
305     /// until the timer is stopped and the callback has completed.
308     /// Start the timer after `expires` time units. If the timer was already
313     /// Caller promises keep the timer structure alive until the timer is dead.
315     unsafe fn start(self, expires: <Self::TimerMode as HrTimerMode>::Expires) -> Self::TimerHandle;
323 /// timer is dead and the timer handler is not running.
325     /// The operational mode associated with this timer.
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
334         F: FnOnce() -> T;
338 // handle returned by [`UnsafeHrTimerPointer::start`] ensures that the timer is
350     ) -> U
352         F: FnOnce() -> U,
354         // SAFETY: We drop the timer handle below before returning.
362 /// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a
370     /// Callback to be called from C when timer fires.
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;
379 /// Implemented by structs that can be the target of a timer callback.
382     /// the timer expires.
385     /// Called by the timer logic when the timer fires.
389     ) -> HrTimerRestart
395 /// A handle representing a potentially running timer.
397 /// More than one handle representing the same timer might exist.
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
408     /// Cancel the timer. If the timer is in the running state, block till the
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
415     /// Returns `true` if the timer was running.
416     fn cancel(&mut self) -> bool;
419 /// Implemented by structs that contain timer nodes.
421 /// Clients of the timer API would usually safely implement this trait by using
431     /// The operational mode associated with this timer.
444     unsafe fn raw_get_timer(this: *const Self) -> *const HrTimer<T>;
455     unsafe fn timer_container_of(ptr: *mut HrTimer<T>) -> *mut Self
467     unsafe fn c_timer_ptr(this: *const Self) -> *const bindings::hrtimer {
475     /// Start the timer contained in the `Self` pointed to by `self_ptr`. If
480     /// - `this` must point to a valid `Self`.
481     /// - Caller must ensure that the pointee of `this` lives until the timer
500     /// Timer should not be restarted.
502     /// Timer should be restarted.
507     fn into_c(self) -> bindings::hrtimer_restart {
517     /// timer functions. The interpretation (absolute vs relative) depends on the
519     fn as_nanos(&self) -> i64;
524     fn as_nanos(&self) -> i64 {
531     fn as_nanos(&self) -> i64 {
567 /// Timer that expires at a fixed point in time.
577 /// Timer that expires after a delay from now.
587 /// Timer with absolute expiration time, pinned to its current CPU.
596 /// Timer with relative expiration time, pinned to its current CPU.
605 /// Timer with absolute expiration, handled in soft irq context.
614 /// Timer with relative expiration, handled in soft irq context.
623 /// Timer with absolute expiration, pinned to CPU and handled in soft irq context.
632 /// Timer with absolute expiration, pinned to CPU and handled in soft irq context.
641 /// Timer with absolute expiration, handled in hard irq context.
650 /// Timer with relative expiration, handled in hard irq context.
659 /// Timer with absolute expiration, pinned to CPU and handled in hard irq context.
668 /// Timer with relative expiration, pinned to CPU and handled in hard irq context.
677 /// Privileged smart-pointer for a [`HrTimer`] callback context.
685 /// This type provides access to said methods from within a timer callback context.
699     /// This function relies on the caller being within the context of a timer callback, so it must
701     /// caller promises that `timer` points to a valid initialized instance of
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
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)
714     /// Conditionally forward the timer.
718     pub fn forward(&mut self, now: HrTimerInstant<T>, interval: Delta) -> u64 {
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>`
725     /// Conditionally forward the timer.
729     pub fn forward_now(&mut self, duration: Delta) -> u64 {
759             ) -> *const $crate::time::hrtimer::HrTimer<$timer_type> {
767             ) -> *mut Self {
776 mod arc;
777 pub use arc::ArcHrTimerHandle;
782 // `box` is a reserved keyword, so prefix with `t` for timer