From 56822dd3b8e343a16c86960cffbaa6e48f363a16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Sat, 18 Dec 2021 22:36:11 +0100 Subject: [PATCH] Docs: Tips touchup --- book/en/src/by-example/tips_destructureing.md | 5 ++-- book/en/src/by-example/tips_from_ram.md | 3 +-- book/en/src/by-example/tips_indirection.md | 5 ++-- book/en/src/by-example/tips_monotonic_impl.md | 26 ++++++++++--------- .../src/by-example/tips_static_lifetimes.md | 16 ++++++------ book/en/src/by-example/tips_view_code.md | 8 +++--- 6 files changed, 33 insertions(+), 30 deletions(-) diff --git a/book/en/src/by-example/tips_destructureing.md b/book/en/src/by-example/tips_destructureing.md index 7b864c4666..4637b48343 100644 --- a/book/en/src/by-example/tips_destructureing.md +++ b/book/en/src/by-example/tips_destructureing.md @@ -1,7 +1,8 @@ # Resource de-structure-ing -When having a task taking multiple resources it can help in readability to split -up the resource struct. Here are two examples on how this can be done: +Destructuring task resources might help readability if a task takes multiple +resources. +Here are two examples on how to split up the resource struct: ``` rust {{#include ../../../../examples/destructure.rs}} diff --git a/book/en/src/by-example/tips_from_ram.md b/book/en/src/by-example/tips_from_ram.md index 6aef2f704e..ecb5dde195 100644 --- a/book/en/src/by-example/tips_from_ram.md +++ b/book/en/src/by-example/tips_from_ram.md @@ -6,7 +6,7 @@ RTIC v0.4.0 was to allow inter-operation with other attributes. For example, the improve performance in some cases. > **IMPORTANT**: In general, the `link_section`, `export_name` and `no_mangle` -> attributes are very powerful but also easy to misuse. Incorrectly using any of +> attributes are powerful but also easy to misuse. Incorrectly using any of > these attributes can cause undefined behavior; you should always prefer to use > safe, higher level attributes around them like `cortex-m-rt`'s `interrupt` and > `exception` attributes. @@ -42,4 +42,3 @@ $ cargo nm --example ramfunc --release | grep ' foo::' $ cargo nm --example ramfunc --release | grep ' bar::' {{#include ../../../../ci/expected/ramfunc.grep.bar}} ``` - diff --git a/book/en/src/by-example/tips_indirection.md b/book/en/src/by-example/tips_indirection.md index 22c5774630..1a330c5162 100644 --- a/book/en/src/by-example/tips_indirection.md +++ b/book/en/src/by-example/tips_indirection.md @@ -3,7 +3,9 @@ Message passing always involves copying the payload from the sender into a static variable and then from the static variable into the receiver. Thus sending a large buffer, like a `[u8; 128]`, as a message involves two expensive -`memcpy`s. To minimize the message passing overhead one can use indirection: +`memcpy`s. + +Indirection can minimize message passing overhead: instead of sending the buffer by value, one can send an owning pointer into the buffer. @@ -23,4 +25,3 @@ Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes. $ cargo run --target thumbv7m-none-eabi --example pool {{#include ../../../../ci/expected/pool.run}} ``` - diff --git a/book/en/src/by-example/tips_monotonic_impl.md b/book/en/src/by-example/tips_monotonic_impl.md index 210a08e669..99e155d049 100644 --- a/book/en/src/by-example/tips_monotonic_impl.md +++ b/book/en/src/by-example/tips_monotonic_impl.md @@ -1,18 +1,21 @@ # Implementing a `Monotonic` timer for scheduling -The framework is very flexible in that it can utilize any timer which has compare-match and (optional) -overflow interrupts for scheduling. The only thing needed to make a timer usable with RTIC is to -implement the [`rtic_monotonic::Monotonic`] trait. +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_monotonic::Monotonic`] trait. -Implementing time that supports a vast range is generally **very** difficult, and in RTIC 0.5 it was a -common problem how to implement time handling and not get stuck in weird special cases. Moreover -it was difficult to understand the relation between time and the timers used for scheduling. For -RTIC 0.6 we have moved to assume the user has a time library, e.g. [`fugit`] or [`embedded_time`], -as the basis for all time-based operations when implementing `Monotonic`. This is why in RTIC 0.6 -it is almost trivial to implement the `Monotonic` trait and use any timer in a system for scheduling. +Implementing time counting that supports large time spans is generally **difficult**, in RTIC 0.5 +implementing time handling was a common problem. +Moreover, the relation between time and timers used for scheduling was difficult to understand. -The trait documents the requirements for each method, however below you can find a list of -implementations in the wild that can be used as inspiration: +For RTIC 0.6 we have moved to assume the user has a time library, e.g. [`fugit`] or [`embedded_time`], +as the basis for all time-based operations when implementing `Monotonic`. +This makes it almost trivial to implement the `Monotonic` trait allowing the use of any timer in +the system for scheduling. + +The trait documents the requirements for each method, +and for inspiration here is a list of `Monotonic` implementations: - [`STM32F411 series`], implemented for the 32-bit timers - [`Nordic nRF52 series`], implemented for the 32-bit timers @@ -28,4 +31,3 @@ If you know of more implementations feel free to add them to this list. [`Nordic nRF52 series`]: https://github.com/kalkyl/nrf-play/blob/main/src/bin/mono.rs [`Systick based`]: https://github.com/rtic-rs/systick-monotonic [`DWT and Systick based`]: https://github.com/rtic-rs/dwt-systick-monotonic - diff --git a/book/en/src/by-example/tips_static_lifetimes.md b/book/en/src/by-example/tips_static_lifetimes.md index 3ea08166e4..8d3a832c4e 100644 --- a/book/en/src/by-example/tips_static_lifetimes.md +++ b/book/en/src/by-example/tips_static_lifetimes.md @@ -1,17 +1,17 @@ # 'static super-powers -As discussed earlier `local` resources are given `'static` lifetime in `#[init]` and `#[idle]`, -this can be used to allocate an object and then split it up or give the pre-allocated object to a -task, driver or some other object. -This is very useful when needing to allocate memory for drivers, such as USB drivers, and using -data structures that can be split such as [`heapless::spsc::Queue`]. +In `#[init]` and `#[idle]` `local` resources has `'static` lifetime. -In the following example an [`heapless::spsc::Queue`] is given to two different tasks for lock-free access -to the shared queue. +Useful when pre-allocating and/or splitting resources between tasks, drivers +or some other object. +This comes in handy when drivers, such as USB drivers, need to allocate memory and +when using splittable data structures such as [`heapless::spsc::Queue`]. + +In the following example two different tasks share a [`heapless::spsc::Queue`] +for lock-free access to the shared queue. [`heapless::spsc::Queue`]: https://docs.rs/heapless/0.7.5/heapless/spsc/struct.Queue.html - ``` rust {{#include ../../../../examples/static.rs}} ``` diff --git a/book/en/src/by-example/tips_view_code.md b/book/en/src/by-example/tips_view_code.md index 8f0d86b591..736b7ac895 100644 --- a/book/en/src/by-example/tips_view_code.md +++ b/book/en/src/by-example/tips_view_code.md @@ -7,7 +7,7 @@ options: You can inspect the file `rtic-expansion.rs` inside the `target` directory. This file contains the expansion of the `#[rtic::app]` item (not your whole program!) of the *last built* (via `cargo build` or `cargo check`) RTIC application. The -expanded code is not pretty printed by default so you'll want to run `rustfmt` +expanded code is not pretty printed by default, so you'll want to run `rustfmt` on it before you read it. ``` console @@ -15,7 +15,7 @@ $ cargo build --example foo $ rustfmt target/rtic-expansion.rs -$ tail target/rtic-expansion.rs +tail target/rtic-expansion.rs ``` ``` rust @@ -43,6 +43,6 @@ crate and print the output to the console. [`cargo-expand`]: https://crates.io/crates/cargo-expand ``` console -$ # produces the same output as before -$ cargo expand --example smallest | tail +# produces the same output as before +cargo expand --example smallest | tail ```