diff options
Diffstat (limited to 'book/en/src/by-example')
| -rw-r--r-- | book/en/src/by-example/app.md | 17 | ||||
| -rw-r--r-- | book/en/src/by-example/tips.md | 23 |
2 files changed, 15 insertions, 25 deletions
diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md index 2c70af0..6a01193 100644 --- a/book/en/src/by-example/app.md +++ b/book/en/src/by-example/app.md @@ -34,14 +34,13 @@ And optionally, device specific peripherals through the `core` and `device` fiel of `init::Context`. `static mut` variables declared at the beginning of `init` will be transformed -into `&'static mut` references that are safe to access. +into `&'static mut` references that are safe to access. Notice, this feature may be deprecated in next release, see `task_local` resources. [`rtic::Peripherals`]: ../../api/rtic/struct.Peripherals.html The example below shows the types of the `core`, `device` and `cs` fields, and showcases safe access to a `static mut` variable. The `device` field is only -available when the `peripherals` argument is set to `true` (it defaults to -`false`). +available when the `peripherals` argument is set to `true` (default). In the rare case you want to implement an ultra-slim application you can explicitly set `peripherals` to `false`. ``` rust {{#include ../../../../examples/init.rs}} @@ -71,12 +70,12 @@ then sends the microcontroller to sleep after running `init`. [SLEEPONEXIT]: https://developer.arm.com/docs/100737/0100/power-management/sleep-mode/sleep-on-exit-bit Like in `init`, `static mut` variables will be transformed into `&'static mut` -references that are safe to access. +references that are safe to access. Notice, this feature may be deprecated in the next release, see `task_local` resources. The example below shows that `idle` runs after `init`. -**Note:** The `loop {}` in idle cannot be empty as this will crash the microcontroller due to a bug -in LLVM which miss-optimizes empty loops to a `UDF` instruction in release mode. +**Note:** The `loop {}` in idle cannot be empty as this will crash the microcontroller due to +LLVM compiling empty loops to an `UDF` instruction in release mode. To avoid UB, the loop needs to imply a "side-effect" by inserting an assembly instruction (e.g., `WFI`) or a `continue`. ``` rust {{#include ../../../../examples/idle.rs}} @@ -146,9 +145,9 @@ $ cargo run --example preempt ``` Note that the task `gpiob` does *not* preempt task `gpioc` because its priority -is the *same* as `gpioc`'s. However, once `gpioc` terminates the execution of -task, `gpiob` is prioritized over `gpioa` due to its higher priority. `gpioa` -is resumed only after `gpiob` terminates. +is the *same* as `gpioc`'s. However, once `gpioc` returns, the execution of +task `gpiob` is prioritized over `gpioa` due to its higher priority. `gpioa` +is resumed only after `gpiob` returns. One more note about priorities: choosing a priority higher than what the device supports (that is `1 << NVIC_PRIO_BITS`) will result in a compile error. Due to diff --git a/book/en/src/by-example/tips.md b/book/en/src/by-example/tips.md index 090b30a..f537173 100644 --- a/book/en/src/by-example/tips.md +++ b/book/en/src/by-example/tips.md @@ -2,15 +2,8 @@ ## Generics -Resources may appear in contexts as resource proxies or as unique references -(`&mut-`) depending on the priority of the task. Because the same resource may -appear as *different* types in different contexts one cannot refactor a common -operation that uses resources into a plain function; however, such refactor is -possible using *generics*. - -All resource proxies implement the `rtic::Mutex` trait. On the other hand, -unique references (`&mut-`) do *not* implement this trait (due to limitations in -the trait system) but one can wrap these references in the [`rtic::Exclusive`] +All resource proxies implement the `rtic::Mutex` trait. +If a resource does not implement this, one can wrap it in the [`rtic::Exclusive`] newtype which does implement the `Mutex` trait. With the help of this newtype one can write a generic function that operates on generic resources and call it from different tasks to perform some operation on the same set of resources. @@ -27,15 +20,13 @@ $ cargo run --example generics {{#include ../../../../ci/expected/generics.run}} ``` -Using generics also lets you change the static priorities of tasks during -development without having to rewrite a bunch code every time. - ## Conditional compilation You can use conditional compilation (`#[cfg]`) on resources (the fields of -`struct Resources`) and tasks (the `fn` items). The effect of using `#[cfg]` -attributes is that the resource / task will *not* be available through the -corresponding `Context` `struct` if the condition doesn't hold. +`#[resources] struct Resources`) and tasks (the `fn` items). +The effect of using `#[cfg]` attributes is that the resource / task +will *not* be available through the corresponding `Context` `struct` +if the condition doesn't hold. The example below logs a message whenever the `foo` task is spawned, but only if the program has been compiled using the `dev` profile. @@ -132,7 +123,7 @@ 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` -over it before you read it. +on it before you read it. ``` console $ cargo build --example foo |