rtic_monotonic/
lib.rs

Help
1//! Core abstractions of the Real-Time Interrupt-driven Concurrency (RTIC) Monotonic timers, used
2//! internally for scheduling and users can use them for time.
3//!
4//! You can write generic *libraries* and HALs using the `Monotonic` trait in this crate. If you
5//! want to write application code then you'll need an *implementation* of the RTIC framework for a
6//! particular architecture. Currently, there are implementations for these architectures and OSes:
7//!
8//! - [ARM Cortex-M](https://crates.io/crates/cortex-m-rtic)
9
10#![deny(missing_docs)]
11#![deny(rust_2021_compatibility)]
12#![deny(rust_2018_compatibility)]
13#![deny(rust_2018_idioms)]
14#![no_std]
15//deny_warnings_placeholder_for_ci
16
17use core::ops::{Add, Sub};
18
19/// # A monotonic clock / counter definition.
20///
21/// ## Correctness
22///
23/// The trait enforces that proper time-math is implemented between `Instant` and `Duration`. This
24/// is a requirement on the time library that the user chooses to use.
25pub trait Monotonic {
26    /// This tells RTIC if it should disable the interrupt bound to the monotonic if there are no
27    /// scheduled tasks. One may want to set this to `false` if one is using the `on_interrupt`
28    /// method to perform housekeeping and need overflow interrupts to happen, such as when
29    /// extending a 16 bit timer to 32/64 bits, even if there are no scheduled tasks.
30    const DISABLE_INTERRUPT_ON_EMPTY_QUEUE: bool = true;
31
32    /// The type for instant, defining an instant in time.
33    ///
34    /// **Note:** In all APIs in RTIC that use instants from this monotonic, this type will be used.
35    type Instant: Ord
36        + Copy
37        + Add<Self::Duration, Output = Self::Instant>
38        + Sub<Self::Duration, Output = Self::Instant>
39        + Sub<Self::Instant, Output = Self::Duration>;
40
41    /// The type for duration, defining an duration of time.
42    ///
43    /// **Note:** In all APIs in RTIC that use duration from this monotonic, this type will be used.
44    type Duration;
45
46    /// Get the current time.
47    fn now(&mut self) -> Self::Instant;
48
49    /// Set the compare value of the timer interrupt.
50    ///
51    /// **Note:** This method does not need to handle race conditions of the monotonic, the timer
52    /// queue in RTIC checks this.
53    fn set_compare(&mut self, instant: Self::Instant);
54
55    /// Clear the compare interrupt flag.
56    fn clear_compare_flag(&mut self);
57
58    /// The time at time zero. Used by RTIC before the monotonic has been initialized.
59    fn zero() -> Self::Instant;
60
61    /// Optionally resets the counter to *zero* for a fixed baseline in a system.
62    ///
63    /// This method will be called *exactly once* by the RTIC runtime after `#[init]` returns and
64    /// before tasks start.
65    ///
66    /// # Safety
67    ///
68    /// ## Correctness
69    ///
70    /// The user may not call this method.
71    unsafe fn reset(&mut self);
72
73    /// Optional. Commonly used for performing housekeeping of a timer when it has been extended,
74    /// e.g. a 16 bit timer extended to 32/64 bits. This will be called at the end of the interrupt
75    /// handler after all other operations have finished.
76    fn on_interrupt(&mut self) {}
77
78    /// Optional. This is used to save power, this is called when the Monotonic interrupt is
79    /// enabled.
80    fn enable_timer(&mut self) {}
81
82    /// Optional. This is used to save power, this is called when the Monotonic interrupt is
83    /// disabled.
84    fn disable_timer(&mut self) {}
85}
rtic_monotonic/lib.rs

rtic_monotonic/
lib.rs
