From b71df58f2fb4ed85d4c8cf806d5837ce63c73f31 Mon Sep 17 00:00:00 2001
From: Emil Fresk <emil.fresk@gmail.com>
Date: Wed, 22 Sep 2021 13:22:45 +0200
Subject: The great docs update

---
 book/en/src/by-example/app_idle.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 book/en/src/by-example/app_idle.md

(limited to 'book/en/src/by-example/app_idle.md')

diff --git a/book/en/src/by-example/app_idle.md b/book/en/src/by-example/app_idle.md
new file mode 100644
index 0000000..1eb1472
--- /dev/null
+++ b/book/en/src/by-example/app_idle.md
@@ -0,0 +1,27 @@
+# The background task `#[idle]`
+
+A function marked with the `idle` attribute can optionally appear in the
+module. This function is used as the special *idle task* and must have
+signature `fn(idle::Context) -> !`.
+
+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`.
+
+``` rust
+{{#include ../../../../examples/idle.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example idle
+{{#include ../../../../ci/expected/idle.run}}
+```
-- 
cgit v1.2.3