diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md index c5e69e5b86..40832844af 100644 --- a/book/en/src/SUMMARY.md +++ b/book/en/src/SUMMARY.md @@ -16,11 +16,11 @@ - [Delay and Timeout using Monotonics](./by-example/delay.md) - [The minimal app](./by-example/app_minimal.md) - [Tips & Tricks](./by-example/tips/index.md) - - [Implementing Monotonic](./by-example/tips/monotonic_impl.md) - [Resource de-structure-ing](./by-example/tips/destructureing.md) - [Avoid copies when message passing](./by-example/tips/indirection.md) - [`'static` super-powers](./by-example/tips/static_lifetimes.md) - [Inspecting generated code](./by-example/tips/view_code.md) +- [Monotonics & the Timer Queue](./monotonic_impl.md) - [RTIC vs. the world](./rtic_vs.md) - [RTIC and Embassy](./rtic_and_embassy.md) - [Awesome RTIC examples](./awesome_rtic.md) diff --git a/book/en/src/by-example/delay.md b/book/en/src/by-example/delay.md index a6ad0e0a02..09091fc245 100644 --- a/book/en/src/by-example/delay.md +++ b/book/en/src/by-example/delay.md @@ -6,6 +6,8 @@ This can be achieved by instantiating a monotonic timer (for implementations, se [`rtic-monotonics`]: https://github.com/rtic-rs/rtic/tree/master/rtic-monotonics [`rtic-time`]: https://github.com/rtic-rs/rtic/tree/master/rtic-time +[`Monotonic`]: https://docs.rs/rtic-time/latest/rtic_time/trait.Monotonic.html +[Implementing a `Monotonic`]: ../../monotonic_impl.md ``` rust,noplayground ... @@ -25,12 +27,6 @@ async fn foo(_cx: foo::Context) { ``` - - -Technically, the timer queue is implemented as a list based priority queue, where list-nodes are statically allocated as part of the underlying task `Future`. Thus, the timer queue is infallible at run-time (its size and allocation are determined at compile time). - -Similarly the channels implementation, the timer-queue implementation relies on a global *Critical Section* (CS) for race protection. For the examples a CS implementation is provided by adding `--features test-critical-section` to the build options. -
A complete example @@ -48,6 +44,9 @@ $ cargo run --target thumbv7m-none-eabi --example async-delay --features test-cr
+> Interested in contributing new implementations of [`Monotonic`], or more information about the inner workings of monotonics? +> Check out the [Implementing a `Monotonic`] chapter! + ## Timeout Rust [`Future`]s (underlying Rust `async`/`await`) are composable. This makes it possible to `select` in between `Futures` that have completed. diff --git a/book/en/src/by-example/tips/monotonic_impl.md b/book/en/src/by-example/tips/monotonic_impl.md deleted file mode 100644 index 9f88c19750..0000000000 --- a/book/en/src/by-example/tips/monotonic_impl.md +++ /dev/null @@ -1,25 +0,0 @@ -# Implementing a `Monotonic` timer for scheduling - -The framework is flexible because it can use any timer which has compare-match and optionally supporting overflow interrupts for scheduling. The single requirement to make a timer usable with RTIC is implementing the `rtic-time::Monotonic` trait. - -For RTIC 1.0 and 2.0 we instead assume the user has a time library, e.g. [`fugit`], as the basis for all time-based operations when implementing `Monotonic`. These libraries make it much easier to correctly implement the `Monotonic` trait, allowing the use of almost any timer in the system for scheduling. - -The trait documents the requirements for each method. There are reference implementations available in [`rtic-monotonics`] that can be used for inspriation. - -- [`Systick based`], runs at a fixed interrupt (tick) rate - with some overhead but simple and provides support for large time spans -- [`RP2040 Timer`], a "proper" implementation with support for waiting for long periods without interrupts. Clearly demonstrates how to use the `TimerQueue` to handle scheduling. -- [`nRF52 timers`] implements monotonic & Timer Queue for the RTC and normal timers in nRF52's - -## Contributing - -Contributing new implementations of `Monotonic` can be done in multiple ways: -* Implement the trait behind a feature flag in [`rtic-monotonics`], and create a PR for them to be included in the main RTIC repository. This way, the implementations of are in-tree, and RTIC can guarantee their correctness, and can update them in the case of a new release. -* Implement the changes in an external repository. - -[`rtic-monotonics`]: https://github.com/rtic-rs/rtic/tree/master/rtic-monotonics/ -[`rtic_time::Monotonic`]: https://docs.rs/rtic_time/ -[`fugit`]: https://docs.rs/fugit/ -[`Systick based`]: https://github.com/rtic-monotonics -[`rtic-monotonics`]: https://github.com/rtic-rs/rtic/blob/master/rtic-monotonics -[`RP2040 Timer`]: https://github.com/rtic-rs/rtic/blob/master/rtic-monotonics/src/rp2040.rs -[`nRF52 timers`]: https://github.com/rtic-rs/rtic/blob/master/rtic-monotonics/src/nrf.rs \ No newline at end of file diff --git a/book/en/src/monotonic_impl.md b/book/en/src/monotonic_impl.md new file mode 100644 index 0000000000..97c0da89c0 --- /dev/null +++ b/book/en/src/monotonic_impl.md @@ -0,0 +1,38 @@ +# The magic behind Monotonics + +Internally, all monotonics use a [Timer Queue](#the-timer-queue), which is a priority queue with entries describing the time at which their respective `Future`s should complete. + +## Implementing a `Monotonic` timer for scheduling + +The [`rtic-time`] framework is flexible because it can use any timer which has compare-match and optionally supporting overflow interrupts for scheduling. The single requirement to make a timer usable with RTIC is implementing the [`rtic-time::Monotonic`] trait. + +For RTIC 2.0, we assume that the user has a time library, e.g. [`fugit`], as the basis for all time-based operations when implementing [`Monotonic`]. These libraries make it much easier to correctly implement the [`Monotonic`] trait, allowing the use of almost any timer in the system for scheduling. + +The trait documents the requirements for each method. There are reference implementations available in [`rtic-monotonics`] that can be used for inspriation. + +- [`Systick based`], runs at a fixed interrupt (tick) rate - with some overhead but simple and provides support for large time spans +- [`RP2040 Timer`], a "proper" implementation with support for waiting for long periods without interrupts. Clearly demonstrates how to use the [`TimerQueue`] to handle scheduling. +- [`nRF52 timers`] implements monotonic & Timer Queue for the RTC and normal timers in nRF52's + +## Contributing + +Contributing new implementations of `Monotonic` can be done in multiple ways: +* Implement the trait behind a feature flag in [`rtic-monotonics`], and create a PR for them to be included in the main RTIC repository. This way, the implementations of are in-tree, RTIC can guarantee their correctness, and can update them in the case of a new release. +* Implement the changes in an external repository. Doing so will not have them included in [`rtic-monotonics`], but may make it easier to do so in the future. + +[`rtic-monotonics`]: https://github.com/rtic-rs/rtic/tree/master/rtic-monotonics/ +[`fugit`]: https://docs.rs/fugit/ +[`Systick based`]: https://github.com/rtic-monotonics +[`rtic-monotonics`]: https://github.com/rtic-rs/rtic/blob/master/rtic-monotonics +[`RP2040 Timer`]: https://github.com/rtic-rs/rtic/blob/master/rtic-monotonics/src/rp2040.rs +[`nRF52 timers`]: https://github.com/rtic-rs/rtic/blob/master/rtic-monotonics/src/nrf.rs +[`rtic-time`]: https://docs.rs/rtic-time/latest/rtic_time +[`rtic-time::Monotonic`]: https://docs.rs/rtic-time/latest/rtic_time/trait.Monotonic.html +[`Monotonic`]: https://docs.rs/rtic-time/latest/rtic_time/trait.Monotonic.html +[`TimerQueue`]: https://docs.rs/rtic-time/latest/rtic_time/struct.TimerQueue.html + +## The timer queue + +The timer queue is implemented as a list based priority queue, where list-nodes are statically allocated as part of the `Future` created when `await`-ing a Future created when waiting for the monotonic. Thus, the timer queue is infallible at run-time (its size and allocation are determined at compile time). + +Similarly the channels implementation, the timer-queue implementation relies on a global *Critical Section* (CS) for race protection. For the examples a CS implementation is provided by adding `--features test-critical-section` to the build options. \ No newline at end of file