diff --git a/book/en/src/by-example/app_idle.md b/book/en/src/by-example/app_idle.md index 1eb1472204..66f40497fb 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/ci/expected/idle-wfi.run b/ci/expected/idle-wfi.run new file mode 100644 index 0000000000..4307776304 --- /dev/null +++ b/ci/expected/idle-wfi.run @@ -0,0 +1,2 @@ +init +idle diff --git a/examples/idle-wfi.rs b/examples/idle-wfi.rs new file mode 100644 index 0000000000..4a8a8dee2b --- /dev/null +++ b/examples/idle-wfi.rs @@ -0,0 +1,47 @@ +//! examples/idle-wfi.rs + +#![deny(unsafe_code)] +#![deny(warnings)] +#![no_main] +#![no_std] + +use panic_semihosting as _; + +#[rtic::app(device = lm3s6965)] +mod app { + use cortex_m_semihosting::{debug, hprintln}; + + #[shared] + struct Shared {} + + #[local] + struct Local {} + + #[init] + fn init(mut cx: init::Context) -> (Shared, Local, init::Monotonics) { + hprintln!("init").unwrap(); + + // Set the ARM SLEEPONEXIT bit to go to sleep after handling interrupts + // See https://developer.arm.com/docs/100737/0100/power-management/sleep-mode/sleep-on-exit-bit + cx.core.SCB.set_sleepdeep(); + + (Shared {}, Local {}, init::Monotonics()) + } + + #[idle(local = [x: u32 = 0])] + fn idle(cx: idle::Context) -> ! { + // Locals in idle have lifetime 'static + let _x: &'static mut u32 = cx.local.x; + + hprintln!("idle").unwrap(); + + debug::exit(debug::EXIT_SUCCESS); // Exit QEMU simulator + + loop { + // Now Wait For Interrupt is used instead of a busy-wait loop + // to allow MCU to sleep between interrupts + // https://developer.arm.com/documentation/ddi0406/c/Application-Level-Architecture/Instruction-Details/Alphabetical-list-of-instructions/WFI + rtic::export::wfi() + } + } +} diff --git a/macros/src/codegen/idle.rs b/macros/src/codegen/idle.rs index d653931655..0dededa4e6 100644 --- a/macros/src/codegen/idle.rs +++ b/macros/src/codegen/idle.rs @@ -85,7 +85,7 @@ pub fn codegen( vec![], None, quote!(loop { - rtic::export::wfi() + rtic::export::nop() }), ) } diff --git a/macros/src/codegen/pre_init.rs b/macros/src/codegen/pre_init.rs index 42cc055298..7aaf20fc79 100644 --- a/macros/src/codegen/pre_init.rs +++ b/macros/src/codegen/pre_init.rs @@ -122,12 +122,5 @@ pub fn codegen(app: &App, analysis: &Analysis, extra: &Extra) -> Vec