diff options
Diffstat (limited to 'embassy-time/src/driver.rs')
| -rw-r--r-- | embassy-time/src/driver.rs | 17 |
1 files changed, 13 insertions, 4 deletions
diff --git a/embassy-time/src/driver.rs b/embassy-time/src/driver.rs index 5fe7becaf..2afa454fe 100644 --- a/embassy-time/src/driver.rs +++ b/embassy-time/src/driver.rs | |||
| @@ -7,11 +7,16 @@ | |||
| 7 | //! - Define a struct `MyDriver` | 7 | //! - Define a struct `MyDriver` |
| 8 | //! - Implement [`Driver`] for it | 8 | //! - Implement [`Driver`] for it |
| 9 | //! - Register it as the global driver with [`time_driver_impl`](crate::time_driver_impl). | 9 | //! - Register it as the global driver with [`time_driver_impl`](crate::time_driver_impl). |
| 10 | //! - Enable the Cargo features `embassy-executor/time` and one of `embassy-time/tick-*` corresponding to the | 10 | //! - Enable the Cargo feature `embassy-executor/time` |
| 11 | //! tick rate of your driver. | ||
| 12 | //! | 11 | //! |
| 13 | //! If you wish to make the tick rate configurable by the end user, you should do so by exposing your own | 12 | //! If your driver has a single set tick rate, enable the corresponding [`tick-hz-*`](crate#tick-rate) feature, |
| 14 | //! Cargo features and having each enable the corresponding `embassy-time/tick-*`. | 13 | //! which will prevent users from needing to configure it themselves (or selecting an incorrect configuration). |
| 14 | //! | ||
| 15 | //! If your driver supports a small number of set tick rates, expose your own cargo features and have each one | ||
| 16 | //! enable the corresponding `embassy-time/tick-*`. | ||
| 17 | //! | ||
| 18 | //! Otherwise, don’t enable any `tick-hz-*` feature to let the user configure the tick rate themselves by | ||
| 19 | //! enabling a feature on `embassy-time`. | ||
| 15 | //! | 20 | //! |
| 16 | //! # Linkage details | 21 | //! # Linkage details |
| 17 | //! | 22 | //! |
| @@ -108,6 +113,10 @@ pub trait Driver: Send + Sync + 'static { | |||
| 108 | /// The `Driver` implementation should guarantee that the alarm callback is never called synchronously from `set_alarm`. | 113 | /// The `Driver` implementation should guarantee that the alarm callback is never called synchronously from `set_alarm`. |
| 109 | /// Rather - if `timestamp` is already in the past - `false` should be returned and alarm should not be set, | 114 | /// Rather - if `timestamp` is already in the past - `false` should be returned and alarm should not be set, |
| 110 | /// or alternatively, the driver should return `true` and arrange to call the alarm callback as soon as possible, but not synchronously. | 115 | /// or alternatively, the driver should return `true` and arrange to call the alarm callback as soon as possible, but not synchronously. |
| 116 | /// There is a rare third possibility that the alarm was barely in the future, and by the time it was enabled, it had slipped into the | ||
| 117 | /// past. This is can be detected by double-checking that the alarm is still in the future after enabling it; if it isn't, `false` | ||
| 118 | /// should also be returned to indicate that the callback may have been called already by the alarm, but it is not guaranteed, so the | ||
| 119 | /// caller should also call the callback, just like in the more common `false` case. (Note: This requires idempotency of the callback.) | ||
| 111 | /// | 120 | /// |
| 112 | /// When callback is called, it is guaranteed that now() will return a value greater or equal than timestamp. | 121 | /// When callback is called, it is guaranteed that now() will return a value greater or equal than timestamp. |
| 113 | /// | 122 | /// |