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>

2 files changed, 26 insertions, 10 deletions

diff --git a/book/en/src/by-example/app_idle.md b/book/en/src/by-example/app_idle.md
index 1eb1472..66f4049 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}}
+```
diff --git a/book/ru/src/by-example/app.md b/book/ru/src/by-example/app.md
index c2b518f..5259bfa 100644
--- a/book/ru/src/by-example/app.md
+++ b/book/ru/src/by-example/app.md
@@ -70,11 +70,6 @@ $ cargo run --example init
 `init`, `idle` будет запущена *с включенными прерываниями* и она не может вернуть результат,
 а значит должна работать вечно.
 
-Если функция `idle` не определена, среда вполнения устанавливает бит [SLEEPONEXIT], а затем
-отправляет микроконтроллер в сон после запуска `init`.
-
-[SLEEPONEXIT]: https://developer.arm.com/docs/100737/0100/Power-management/Sleep-mode/Sleep-on-exit-bit
-
 Как и в  `init`, `static mut` переменные будут трансформированы в `&'static mut` ссылки,
 безопасные для доступа. Обратите внимание, данная возможность может
 быть удалена в следующем релизе, см. `task_local` ресурсы.