Merge #562

562: Replace default WFI with simpler NOP r=korken89 a=AfoHT

As noted by #561 there are multiple issues with various hardware implementations and debugging together with sleep modes.

As RTIC strives to be a generic framework (even though this is an implementation targeting cortex-m) the decision having `WFI` as the default `idle` task causes issues in some hardware, raising the barrier to entry.

This changes the default behaviour to do a simple `NOP` instead, adding documentation how to provide a custom `idle` task achieving the old default behaviour. Also removes the automatic setting of SLEEPONEXIT bit when no `idle` was provided, delegating this to the user.

This was discussed on the weekly meeting 2021-12-14 and this was the favoured solution.

Fixes #561 

Co-authored-by: Henrik Tjäder <henrik@grepit.se>

1 files changed, 26 insertions, 5 deletions

diff --git a/book/en/src/by-example/app_idle.md b/book/en/src/by-example/app_idle.md
index 1eb14722..66f40497 100644
--- a/book/en/src/by-example/app_idle.md
+++ b/book/en/src/by-example/app_idle.md
@@ -8,11 +8,6 @@ When present, the runtime will execute the `idle` task after `init`. Unlike
 `init`, `idle` will run *with interrupts enabled* and it's not allowed to return
 so it must run forever.
 
-When no `idle` function is declared, the runtime sets the [SLEEPONEXIT] bit and
-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`, locally declared resources will have `'static` lifetimes that are safe to access.
 
 The example below shows that `idle` runs after `init`.
@@ -25,3 +20,29 @@ The example below shows that `idle` runs after `init`.
 $ cargo run --target thumbv7m-none-eabi --example idle
 {{#include ../../../../ci/expected/idle.run}}
 ```
+
+By default the RTIC `idle` task does not try to optimise for any specific targets.
+
+A common useful optimisation is to enable the [SLEEPONEXIT] and allow the MCU
+to enter sleep when reaching `idle`.
+
+>**Caution** some hardware unless configured disables the debug unit during sleep mode.
+>
+>Consult your hardware specific documentation as this is outside the scope of RTIC.
+
+The following example shows how to enable sleep by setting the
+[`SLEEPONEXIT`][SLEEPONEXIT] and providing a custom `idle` task replacing the
+default [`nop()`][NOP] with [`wfi()`][WFI].
+
+[SLEEPONEXIT]: https://developer.arm.com/docs/100737/0100/power-management/sleep-mode/sleep-on-exit-bit
+[WFI]: https://developer.arm.com/documentation/dui0662/b/The-Cortex-M0--Instruction-Set/Miscellaneous-instructions/WFI
+[NOP]: https://developer.arm.com/documentation/dui0662/b/The-Cortex-M0--Instruction-Set/Miscellaneous-instructions/NOP
+
+``` rust
+{{#include ../../../../examples/idle-wfi.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example idle-wfi
+{{#include ../../../../ci/expected/idle-wfi.run}}
+```