kernel/time/hrtimer.rs

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.
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 timer backed by a C `struct hrtimer`.
79 /// * `self.timer` is initialized by `bindings::hrtimer_setup`.
84     timer: Opaque<bindings::hrtimer>,  field
93 // SAFETY: Timer operations are locked on the C side, so it is safe to operate
94 // on a timer from multiple threads.
98     /// Return an initializer for a new timer instance.
104             // INVARIANT: We initialize `timer` with `hrtimer_setup` below.  in new()
105             timer <- Opaque::ffi_init(move |place: *mut bindings::hrtimer| {  in new()
132         // SAFETY: The field projection to `timer` does not go out of bounds,  in raw_get()
135         unsafe { Opaque::raw_get(core::ptr::addr_of!((*this).timer)) }  in raw_get()
138     /// Cancel an initialized and potentially running timer.
140     /// If the timer handler is running, this function will block until the
143     /// Note that the timer might be started by a concurrent start operation. If
144     /// so, the timer might not be in the **stopped** state when this function
149     /// returned when the timer was started.
171 /// `Self` must be [`Sync`] because it is passed to timer callbacks in another
174 /// Starting a timer returns a [`HrTimerHandle`] that can be used to manipulate
175 /// the timer. Note that it is OK to call the start function repeatedly, and
177 /// exist. A timer can be manipulated through any of the handles, and a handle
178 /// may represent a cancelled timer.
180     /// A handle representing a started or restarted timer.
182     /// If the timer is running or if the timer callback is executing when the
184     /// until the timer is stopped and the callback has completed.
190     /// Start the timer with expiry after `expires` time units. If the timer was
207     /// A handle representing a running timer.
211     /// If the timer is running, or if the timer callback is executing when the
213     /// until the timer is stopped and the callback has completed.
216     /// Start the timer after `expires` time units. If the timer was already
221     /// Caller promises keep the timer structure alive until the timer is dead.
231 /// timer is dead and the timer handler is not running.
233     /// Start the timer to run after `expires` time units and immediately
234     /// after call `f`. When `f` returns, the timer is cancelled.
241 // handle returned by [`UnsafeHrTimerPointer::start`] ensures that the timer is
251         // SAFETY: We drop the timer handle below before returning.  in start_scoped()
259 /// Implemented by [`HrTimerPointer`] implementers to give the C timer callback a
267     /// Callback to be called from C when timer fires.
272     /// to the `bindings::hrtimer` structure that was used to start the timer.
276 /// Implemented by structs that can be the target of a timer callback.
279     /// the timer expires.
282     /// Called by the timer logic when the timer fires.
288 /// A handle representing a potentially running timer.
290 /// More than one handle representing the same timer might exist.
294 /// When dropped, the timer represented by this handle must be cancelled, if it
295 /// is running. If the timer handler is running when the handle is dropped, the
301     /// Cancel the timer. If the timer is in the running state, block till the
304     /// Note that the timer might be started by a concurrent start operation. If
305     /// so, the timer might not be in the **stopped** state when this function
310 /// Implemented by structs that contain timer nodes.
312 /// Clients of the timer API would usually safely implement this trait by using
361     /// Start the timer contained in the `Self` pointed to by `self_ptr`. If
367     /// - Caller must ensure that the pointee of `this` lives until the timer
386     /// Timer should not be restarted.
389     /// Timer should be restarted.
405     /// Timer expires at the given expiration time.
407     /// Timer expires after the given expiration time interpreted as a duration from now.
409     /// Timer does not move between CPU cores.
411     /// Timer handler is executed in soft irq context.
413     /// Timer handler is executed in hard irq context.
415     /// Timer expires at the given expiration time.
416     /// Timer does not move between CPU cores.
418     /// Timer expires after the given expiration time interpreted as a duration from now.
419     /// Timer does not move between CPU cores.
421     /// Timer expires at the given expiration time.
422     /// Timer handler is executed in soft irq context.
424     /// Timer expires after the given expiration time interpreted as a duration from now.
425     /// Timer handler is executed in soft irq context.
427     /// Timer expires at the given expiration time.
428     /// Timer does not move between CPU cores.
429     /// Timer handler is executed in soft irq context.
431     /// Timer expires after the given expiration time interpreted as a duration from now.
432     /// Timer does not move between CPU cores.
433     /// Timer handler is executed in soft irq context.
435     /// Timer expires at the given expiration time.
436     /// Timer handler is executed in hard irq context.
438     /// Timer expires after the given expiration time interpreted as a duration from now.
439     /// Timer handler is executed in hard irq context.
441     /// Timer expires at the given expiration time.
442     /// Timer does not move between CPU cores.
443     /// Timer handler is executed in hard irq context.
445     /// Timer expires after the given expiration time interpreted as a duration from now.
446     /// Timer does not move between CPU cores.
447     /// Timer handler is executed in hard irq context.
518 // `box` is a reserved keyword, so prefix with `t` for timer