Book: Major rework for RTIC v2

12 files changed, 434 insertions, 209 deletions

diff --git a/book/en/src/by-example/app.md b/book/en/src/by-example/app.md
index 2c6aca7..cef8288 100644
--- a/book/en/src/by-example/app.md
+++ b/book/en/src/by-example/app.md
@@ -2,25 +2,31 @@
 
 ## Requirements on the `app` attribute
 
-All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute
-only applies to a `mod`-item containing the RTIC application. The `app`
-attribute has a mandatory `device` argument that takes a *path* as a value.
-This must be a full path pointing to a
-*peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or
-newer.
+All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute only applies to a `mod`-item containing the RTIC application. The `app` attribute has a mandatory `device` argument that takes a *path* as a value. This must be a full path pointing to a *peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or newer.
 
-The `app` attribute will expand into a suitable entry point and thus replaces
-the use of the [`cortex_m_rt::entry`] attribute.
+The `app` attribute will expand into a suitable entry point and thus replaces the use of the [`cortex_m_rt::entry`] attribute.
 
 [`app`]: ../../../api/cortex_m_rtic_macros/attr.app.html
 [`svd2rust`]: https://crates.io/crates/svd2rust
 [`cortex_m_rt::entry`]: ../../../api/cortex_m_rt_macros/attr.entry.html
 
+## Structure and zero-cost concurrency
+
+An RTIC `app` is an executable system model for since-core applications, declaring a set of `local` and `shared` resources operated on by a set of `init`, `idle`, *hardware* and *software* tasks. In short the `init` task runs before any other task returning the set of `local` and `shared` resources. Tasks run preemptively based on their associated static priority, `idle` has the lowest priority (and can be used for background work, and/or to put the system to sleep until woken by some event). Hardware tasks are bound to underlying hardware interrupts, while software tasks are scheduled by asynchronous executors (one for each software task priority). 
+
+At compile time the task/resource model is analyzed under the Stack Resource Policy (SRP) and executable code generated with the following outstanding properties:
+
+- guaranteed race-free resource access and deadlock-free execution on a single-shared stack
+  - hardware task scheduling is performed directly by the hardware, and
+  - software task scheduling is performed by auto generated async executors tailored to the application.
+
+Overall, the generated code infers no additional overhead in comparison to a hand-written implementation, thus in Rust terms RTIC offers a zero-cost abstraction to concurrency.
+
 ## An RTIC application example
 
 To give a flavour of RTIC, the following example contains commonly used features.
 In the following sections we will go through each feature in detail.
 
 ``` rust
-{{#include ../../../../examples/common.rs}}
+{{#include ../../../../rtic/examples/common.rs}}
 ```
diff --git a/book/en/src/by-example/app_idle.md b/book/en/src/by-example/app_idle.md
index 537902a..4856ee1 100644
--- a/book/en/src/by-example/app_idle.md
+++ b/book/en/src/by-example/app_idle.md
@@ -1,52 +1,47 @@
 # The background task `#[idle]`
 
-A function marked with the `idle` attribute can optionally appear in the
-module. This becomes the special *idle task* and must have signature
-`fn(idle::Context) -> !`.
+A function marked with the `idle` attribute can optionally appear in the module. This becomes 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 must never return,
-as the `-> !` function signature indicates.
+When present, the runtime will execute the `idle` task after `init`. Unlike `init`, `idle` will run *with interrupts enabled* and must never return, as the `-> !` function signature indicates.
 [The Rust type `!` means “never”][nevertype].
 
 [nevertype]: https://doc.rust-lang.org/core/primitive.never.html
 
-Like in `init`, locally declared resources will have `'static` lifetimes that
-are safe to access.
+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}}
+{{#include ../../../../rtic/examples/idle.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example idle
-{{#include ../../../../ci/expected/idle.run}}
+{{#include ../../../../rtic/ci/expected/idle.run}}
 ```
 
 By default, the RTIC `idle` task does not try to optimize for any specific targets.
 
-A common useful optimization is to enable the [SLEEPONEXIT] and allow the MCU
-to enter sleep when reaching `idle`.
+A common useful optimization 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.
+>**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`][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}}
+{{#include ../../../../rtic/examples/idle-wfi.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example idle-wfi
-{{#include ../../../../ci/expected/idle-wfi.run}}
+{{#include ../../../../rtic/ci/expected/idle-wfi.run}}
 ```
+
+> **Notice**: The `idle` task cannot be used together with *software* tasks running at priority zero. The reason is that `idle` is running as a non-returning Rust function at priority zero. Thus there would be no way for an executor at priority zero to give control to *software* tasks at the same priority.
diff --git a/book/en/src/by-example/app_init.md b/book/en/src/by-example/app_init.md
index 5bf6200..62fb55b 100644
--- a/book/en/src/by-example/app_init.md
+++ b/book/en/src/by-example/app_init.md
@@ -1,35 +1,28 @@
 # App initialization and the `#[init]` task
 
 An RTIC application requires an `init` task setting up the system. The corresponding `init` function must have the
-signature `fn(init::Context) -> (Shared, Local, init::Monotonics)`, where `Shared` and `Local` are resource
+signature `fn(init::Context) -> (Shared, Local)`, where `Shared` and `Local` are the resource
 structures defined by the user.
 
-The `init` task executes after system reset, [after an optionally defined `pre-init` code section][pre-init] and an always occurring internal RTIC
-initialization.
-
+The `init` task executes after system reset (after the optionally defined [pre-init] and internal RTIC
+initialization). The `init` task runs *with interrupts disabled* and has exclusive access to Cortex-M (the
+`bare_metal::CriticalSection` token is available as `cs`) while device specific peripherals are available through
+the `core` and `device` fields of `init::Context`.
 [pre-init]: https://docs.rs/cortex-m-rt/latest/cortex_m_rt/attr.pre_init.html
-
-The `init` and optional `pre-init` tasks runs *with interrupts disabled* and have exclusive access to Cortex-M (the
-`bare_metal::CriticalSection` token is available as `cs`).
-
-Device specific peripherals are available through the `core` and `device` fields of `init::Context`.
-
 ## Example
 
-The example below shows the types of the `core`, `device` and `cs` fields, and showcases the use of a `local`
-variable with `'static` lifetime.
-Such variables can be delegated from the `init` task to other tasks of the RTIC application.
+The example below shows the types of the `core`, `device` and `cs` fields, and showcases the use of a `local` variable with `'static` lifetime. Such variables can be delegated from the `init` task to other tasks of the RTIC application.
 
-The `device` field is only available when the `peripherals` argument is set to the default value `true`.
+The `device` field is available when the `peripherals` argument is set to the default value `true`.
 In the rare case you want to implement an ultra-slim application you can explicitly set `peripherals` to `false`.
 
 ``` rust
-{{#include ../../../../examples/init.rs}}
+{{#include ../../../../rtic/examples/init.rs}}
 ```
 
 Running the example will print `init` to the console and then exit the QEMU process.
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example init
-{{#include ../../../../ci/expected/init.run}}
+{{#include ../../../../rtic/ci/expected/init.run}}
 ```
diff --git a/book/en/src/by-example/app_minimal.md b/book/en/src/by-example/app_minimal.md
index d0ff40a..f241089 100644
--- a/book/en/src/by-example/app_minimal.md
+++ b/book/en/src/by-example/app_minimal.md
@@ -3,5 +3,19 @@
 This is the smallest possible RTIC application:
 
 ``` rust
-{{#include ../../../../examples/smallest.rs}}
+{{#include ../../../../rtic/examples/smallest.rs}}
 ```
+
+RTIC is designed with resource efficiency in mind. RTIC itself does not rely on any dynamic memory allocation, thus RAM requirement is dependent only on the application. The flash memory footprint is below 1kB including the interrupt vector table.
+
+For a minimal example you can expect something like:
+``` console
+$ cargo size --example smallest --target thumbv7m-none-eabi --release
+Finished release [optimized] target(s) in 0.07s
+   text    data     bss     dec     hex filename
+    924       0       0     924     39c smallest
+```
+
+<!-- ---
+
+Technically, RTIC will generate a statically allocated future for each *software* task (holding the execution context, including the `Context` struct and stack allocated variables). Futures associated to the same static priority will share an asynchronous stack during execution.  -->
diff --git a/book/en/src/by-example/app_priorities.md b/book/en/src/by-example/app_priorities.md
index 8cee749..f03ebf7 100644
--- a/book/en/src/by-example/app_priorities.md
+++ b/book/en/src/by-example/app_priorities.md
@@ -4,23 +4,18 @@
 
 The `priority` argument declares the static priority of each `task`.
 
-For Cortex-M, tasks can have priorities in the range `1..=(1 << NVIC_PRIO_BITS)`
-where `NVIC_PRIO_BITS` is a constant defined in the `device` crate.
+For Cortex-M, tasks can have priorities in the range `1..=(1 << NVIC_PRIO_BITS)` where `NVIC_PRIO_BITS` is a constant defined in the `device` crate.
 
-Omitting the `priority` argument the task priority defaults to `1`.
-The `idle` task has a non-configurable static priority of `0`, the lowest priority.
+Omitting the `priority` argument the task priority defaults to `1`. The `idle` task has a non-configurable static priority of `0`, the lowest priority.
 
 > A higher number means a higher priority in RTIC, which is the opposite from what
 > Cortex-M does in the NVIC peripheral.
 > Explicitly, this means that number `10` has a **higher** priority than number `9`.
 
-The highest static priority task takes precedence when more than one
-task are ready to execute.
+The highest static priority task takes precedence when more than one task are ready to execute.
 
 The following scenario demonstrates task prioritization:
-Spawning a higher priority task A during execution of a lower priority task B suspends
-task B. Task A has higher priority thus preempting task B which gets suspended
-until task A completes execution. Thus, when task A completes task B resumes execution.
+Spawning a higher priority task A during execution of a lower priority task B pends task A. Task A has higher priority thus preempting task B which gets suspended until task A completes execution. Thus, when task A completes task B resumes execution.
 
 ```text
 Task Priority
@@ -39,23 +34,17 @@ Task Priority
 The following example showcases the priority based scheduling of tasks:
 
 ``` rust
-{{#include ../../../../examples/preempt.rs}}
+{{#include ../../../../rtic/examples/preempt.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example preempt
-{{#include ../../../../ci/expected/preempt.run}}
+{{#include ../../../../rtic/ci/expected/preempt.run}}
 ```
 
-Note that the task `bar` does *not* preempt task `baz` because its priority
-is the *same* as `baz`'s. The higher priority task `bar` runs before `foo`
-when `baz`returns. When `bar` returns `foo` can resume.
+Note that the task `bar` does *not* preempt task `baz` because its priority is the *same* as `baz`'s. The higher priority task `bar` runs before `foo` when `baz`returns. When `bar` returns `foo` can resume.
 
-One more note about priorities: choosing a priority higher than what the device
-supports will result in a compilation error.
-
-The error is cryptic due to limitations in the Rust language
-if `priority = 9` for task `uart0_interrupt` in `example/common.rs` this looks like:
+One more note about priorities: choosing a priority higher than what the device supports will result in a compilation error. The error is cryptic due to limitations in the Rust language, if `priority = 9` for task `uart0_interrupt` in `example/common.rs` this looks like:
 
 ```text
    error[E0080]: evaluation of constant value failed
@@ -68,5 +57,4 @@ if `priority = 9` for task `uart0_interrupt` in `example/common.rs` this looks l
 
 ```
 
-The error message incorrectly points to the starting point of the macro, but at least the
-value subtracted (in this case 9) will suggest which task causes the error.
+The error message incorrectly points to the starting point of the macro, but at least the value subtracted (in this case 9) will suggest which task causes the error.
diff --git a/book/en/src/by-example/app_task.md b/book/en/src/by-example/app_task.md
index d83f1ff..e0c67ad 100644
--- a/book/en/src/by-example/app_task.md
+++ b/book/en/src/by-example/app_task.md
@@ -1,21 +1,18 @@
+<!-- Should probably be removed -->
+
 # Defining tasks with `#[task]`
 
 Tasks, defined with `#[task]`, are the main mechanism of getting work done in RTIC.
 
 Tasks can
 
-* Be spawned (now or in the future, also by themselves)
-* Receive messages (passing messages between tasks)
-* Be prioritized, allowing preemptive multitasking
+* Be spawned (now or in the future)
+* Receive messages (message passing)
+* Prioritized allowing preemptive multitasking
 * Optionally bind to a hardware interrupt
 
-RTIC makes a distinction between “software tasks” and “hardware tasks”.
-
-*Hardware tasks* are tasks that are bound to a specific interrupt vector in the MCU while software tasks are not.
-
-This means that if a hardware task is bound to, lets say, a UART RX interrupt, the task will be run every
-time that interrupt triggers, usually when a character is received.
+RTIC makes a distinction between “software tasks” and “hardware tasks”. Hardware tasks are tasks that are bound to a specific interrupt vector in the MCU while software tasks are not.
 
-*Software tasks* are explicitly spawned in a task, either immediately or using the Monotonic timer mechanism. 
+This means that if a hardware task is bound to an UART RX interrupt the task will run every time this interrupt triggers, usually when a character is received.
 
 In the coming pages we will explore both tasks and the different options available.
diff --git a/book/en/src/by-example/channel.md b/book/en/src/by-example/channel.md
new file mode 100644
index 0000000..99bfedd
--- /dev/null
+++ b/book/en/src/by-example/channel.md
@@ -0,0 +1,112 @@
+# Communication over channels.
+
+Channels can be used to communicate data between running *software* tasks. The channel is essentially a wait queue, allowing tasks with multiple producers and a single receiver. A channel is constructed in the `init` task and backed by statically allocated memory. Send and receive endpoints are distributed to *software* tasks:
+
+```rust
+...
+const CAPACITY: usize = 5;
+#[init]
+    fn init(_: init::Context) -> (Shared, Local) {
+        let (s, r) = make_channel!(u32, CAPACITY);
+        receiver::spawn(r).unwrap();
+        sender1::spawn(s.clone()).unwrap();
+        sender2::spawn(s.clone()).unwrap();
+        ...
+```
+
+In this case the channel holds data of `u32` type with a capacity of 5  elements. 
+
+## Sending data
+
+The `send` method post a message on the channel as shown below:
+
+```rust
+#[task]
+async fn sender1(_c: sender1::Context, mut sender: Sender<'static, u32, CAPACITY>) {
+    hprintln!("Sender 1 sending: 1");
+    sender.send(1).await.unwrap();
+}
+```
+
+## Receiving data
+
+The receiver can `await` incoming messages:
+
+```rust
+#[task]
+async fn receiver(_c: receiver::Context, mut receiver: Receiver<'static, u32, CAPACITY>) {
+    while let Ok(val) = receiver.recv().await {
+        hprintln!("Receiver got: {}", val);
+        ...
+    }
+}
+```
+
+For a complete example:
+
+``` rust
+{{#include ../../../../rtic/examples/async-channel.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-channel --features test-critical-section 
+{{#include ../../../../rtic/ci/expected/async-channel.run}}
+```
+
+Also sender endpoint can be awaited. In case there the channel capacity has not been reached, `await` the sender can progress immediately, while in the case the capacity is reached, the sender is blocked until there is free space in the queue. In this way data is never lost.
+
+In the below example the `CAPACITY` has been reduced to 1, forcing sender tasks to wait until the data in the channel has been received.
+
+``` rust
+{{#include ../../../../rtic/examples/async-channel-done.rs}}
+```
+
+Looking at the output, we find that `Sender 2` will wait until the data sent by `Sender 1` as been received. 
+
+> **NOTICE** *Software* tasks at the same priority are executed asynchronously to each other, thus **NO** strict order can be assumed. (The presented order here applies only to the current implementation, and may change between RTIC framework releases.)
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-channel-done --features test-critical-section 
+{{#include ../../../../rtic/ci/expected/async-channel-done.run}}
+```
+
+## Error handling
+
+In case all senders have been dropped `await` on an empty receiver channel results in an error. This allows to gracefully implement different types of shutdown operations.
+
+``` rust
+{{#include ../../../../rtic/examples/async-channel-no-sender.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-channel-no-sender --features test-critical-section  
+{{#include ../../../../rtic/ci/expected/async-channel-no-sender.run}}
+```
+
+Similarly, `await` on a send channel results in an error in case the receiver has been dropped. This allows to gracefully implement application level error handling.
+
+The resulting error returns the data back to the sender, allowing the sender to take appropriate action (e.g., storing the data to later retry sending it).
+
+``` rust
+{{#include ../../../../rtic/examples/async-channel-no-receiver.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-channel-no-receiver --features test-critical-section 
+{{#include ../../../../rtic/ci/expected/async-channel-no-receiver.run}}
+```
+
+
+
+## Try API
+
+In cases you wish the sender to proceed even in case the channel is full. To that end, a `try_send` API is provided.
+
+``` rust
+{{#include ../../../../rtic/examples/async-channel-try.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-channel-try --features test-critical-section 
+{{#include ../../../../rtic/ci/expected/async-channel-try.run}}
+```
\ No newline at end of file
diff --git a/book/en/src/by-example/delay.md b/book/en/src/by-example/delay.md
new file mode 100644
index 0000000..d35d9da
--- /dev/null
+++ b/book/en/src/by-example/delay.md
@@ -0,0 +1,116 @@
+# Tasks with delay
+
+A convenient way to express *miniminal* timing requirements is by means of delaying progression. 
+
+This can be achieved by instantiating a monotonic timer:
+
+```rust
+...
+rtic_monotonics::make_systick_timer_queue!(TIMER);
+
+#[init]
+fn init(cx: init::Context) -> (Shared, Local) {        
+    let systick = Systick::start(cx.core.SYST, 12_000_000);
+    TIMER.initialize(systick);
+    ... 
+```
+
+A *software* task can `await` the delay to expire:
+
+```rust
+#[task]
+async fn foo(_cx: foo::Context) {
+    ...
+    TIMER.delay(100.millis()).await;
+    ...
+```
+
+Technically, the timer queue is implemented as a list based priority queue, where list-nodes are statically allocated as part of the underlying task `Future`. Thus, the timer queue is infallible at run-time (its size and allocation is determined at compile time).
+
+For a complete example:
+
+``` rust
+{{#include ../../../../rtic/examples/async-delay.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-delay --features test-critical-section 
+{{#include ../../../../rtic/ci/expected/async-delay.run}}
+```
+
+## Timeout
+
+Rust `Futures` (underlying Rust `async`/`await`) are composable. This makes it possible to `select` in between `Futures` that have completed.
+
+A common use case is transactions with associated timeout. In the examples shown below, we introduce a fake HAL device which performs some transaction. We have modelled the time it takes based on the input parameter (`n`) as `350ms + n * 100ms)`. 
+
+Using the `select_biased` macro from the `futures` crate it may look like this:
+
+```rust
+// Call hal with short relative timeout using `select_biased`
+select_biased! {
+    v = hal_get(&TIMER, 1).fuse() => hprintln!("hal returned {}", v),
+    _ = TIMER.delay(200.millis()).fuse() =>  hprintln!("timeout", ), // this will finish first
+}
+```
+
+Assuming the `hal_get` will take 450ms to finish, a short timeout of 200ms will expire.
+
+```rust
+// Call hal with long relative timeout using `select_biased`
+select_biased! {
+    v = hal_get(&TIMER, 1).fuse() => hprintln!("hal returned {}", v), // hal finish first
+    _ = TIMER.delay(1000.millis()).fuse() =>  hprintln!("timeout", ),
+}
+```
+
+By extending the timeout to 1000ms, the `hal_get` will finish first.
+
+Using `select_biased` any number of futures can be combined, so its very powerful. However, as the timeout pattern is frequently used, it is directly supported by the RTIC [rtc-monotonics] and [rtic-time] crates. The second example from above using `timeout_after`:
+
+```rust
+// Call hal with long relative timeout using monotonic `timeout_after`
+match TIMER.timeout_after(1000.millis(), hal_get(&TIMER, 1)).await {
+    Ok(v) => hprintln!("hal returned {}", v),
+    _ => hprintln!("timeout"),
+}
+```
+
+In cases you want exact control over time without drift. For this purpose we can use exact points in time using `Instance`, and spans of time using `Duration`. Operations on the `Instance` and `Duration` types are given by the [fugit] crate.
+
+[fugit]: https://crates.io/crates/fugit
+
+```rust
+// get the current time instance
+let mut instant = TIMER.now();
+
+// do this 3 times
+for n in 0..3 {
+    // exact point in time without drift
+    instant += 1000.millis();
+    TIMER.delay_until(instant).await;
+
+    // exact point it time for timeout
+    let timeout = instant + 500.millis();
+    hprintln!("now is {:?}, timeout at {:?}", TIMER.now(), timeout);
+
+    match TIMER.timeout_at(timeout, hal_get(&TIMER, n)).await {
+        Ok(v) => hprintln!("hal returned {} at time {:?}", v, TIMER.now()),
+        _ => hprintln!("timeout"),
+    }
+}
+```
+
+`instant = TIMER.now()` gives the baseline (i.e., the exact current point in time). We want to call `hal_get` after 1000ms relative to this exact point in time. This can be accomplished by `TIMER.delay_until(instant).await;`. We define the absolute point in time for the `timeout`, and call `TIMER.timeout_at(timeout, hal_get(&TIMER, n)).await`. For the first loop iteration `n == 0`, and the `hal_get` will take 350ms (and finishes before the timeout). For the second iteration `n == 1`, and `hal_get` will take 450ms (and again succeeds to finish before the timeout).  For the third iteration `n == 2` (`hal_get` will take 5500ms to finish). In this case we will run into a timeout.
+
+
+The complete example:
+
+``` rust
+{{#include ../../../../rtic/examples/async-timeout.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example async-timeout --features test-critical-section 
+{{#include ../../../../rtic/ci/expected/async-timeout.run}}
+```
diff --git a/book/en/src/by-example/hardware_tasks.md b/book/en/src/by-example/hardware_tasks.md
index 2d405d3..e3e51ac 100644
--- a/book/en/src/by-example/hardware_tasks.md
+++ b/book/en/src/by-example/hardware_tasks.md
@@ -1,39 +1,27 @@
 # Hardware tasks
 
-At its core RTIC is using a hardware interrupt controller ([ARM NVIC on cortex-m][NVIC])
-to schedule and start execution of tasks. All tasks except `pre-init`, `#[init]` and `#[idle]`
-run as interrupt handlers.
+At its core RTIC is using the hardware interrupt controller ([ARM NVIC on cortex-m][NVIC]) to perform scheduling and executing tasks, and all (*hardware*) tasks except `#[init]` and `#[idle]` run as interrupt handlers. This also means that you can manually bind tasks to interrupt handlers.
 
-Hardware tasks are explicitly bound to interrupt handlers.
+To bind an interrupt use the `#[task]` attribute argument `binds = InterruptName`. This task becomes the interrupt handler for this hardware interrupt vector.
 
-To bind a task to an interrupt, use the `#[task]` attribute argument `binds = InterruptName`.
-This task then becomes the interrupt handler for this hardware interrupt vector.
+All tasks bound to an explicit interrupt are *hardware tasks* since they start execution in reaction to a hardware event (interrupt).
 
-All tasks bound to an explicit interrupt are called *hardware tasks* since they
-start execution in reaction to a hardware event.
+Specifying a non-existing interrupt name will cause a compilation error. The interrupt names are commonly defined by [PAC or HAL][pacorhal] crates.
 
-Specifying a non-existing interrupt name will cause a compilation error. The interrupt names
-are commonly defined by [PAC or HAL][pacorhal] crates.
+Any available interrupt vector should work, but different hardware might have added special properties to select interrupt priority levels, such as the [nRF “softdevice”](https://github.com/rtic-rs/cortex-m-rtic/issues/434).
 
-Any available interrupt vector should work. Specific devices may bind
-specific interrupt priorities to specific interrupt vectors outside
-user code control. See for example the 
-[nRF “softdevice”](https://github.com/rtic-rs/cortex-m-rtic/issues/434).
-
-Beware of using interrupt vectors that are used internally by hardware features;
-RTIC is unaware of such hardware specific details.
+Beware of re-purposing interrupt vectors used internally by hardware features, RTIC is unaware of such hardware specific details.
 
 [pacorhal]: https://docs.rust-embedded.org/book/start/registers.html
 [NVIC]: https://developer.arm.com/documentation/100166/0001/Nested-Vectored-Interrupt-Controller/NVIC-functional-description/NVIC-interrupts
 
-The example below demonstrates the use of the `#[task(binds = InterruptName)]` attribute to declare a
-hardware task bound to an interrupt handler.
+The example below demonstrates the use of the `#[task(binds = InterruptName)]` attribute to declare a hardware task bound to an interrupt handler. In the example the interrupt triggering task execution is manually pended (`rtic::pend(Interrupt::UART0)`). However, in the typical case, interrupts are pended by the hardware peripheral. RTIC does not interfere with mechanisms for clearing peripheral interrupts, so any hardware specific implementation is completely up to the implementer.
 
 ``` rust
-{{#include ../../../../examples/hardware.rs}}
+{{#include ../../../../rtic/examples/hardware.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example hardware
-{{#include ../../../../ci/expected/hardware.run}}
+{{#include ../../../../rtic/ci/expected/hardware.run}}
 ```
diff --git a/book/en/src/by-example/resources.md b/book/en/src/by-example/resources.md
index 30089d3..ea67b26 100644
--- a/book/en/src/by-example/resources.md
+++ b/book/en/src/by-example/resources.md
@@ -1,176 +1,138 @@
 # Resource usage
 
-The RTIC framework manages shared and task local resources allowing persistent data
-storage and safe accesses without the use of `unsafe` code.
+The RTIC framework manages shared and task local resources allowing persistent data storage and safe accesses without the use of `unsafe` code.
 
-RTIC resources are visible only to functions declared within the `#[app]` module and the framework
-gives the user complete control (on a per-task basis) over resource accessibility.
+RTIC resources are visible only to functions declared within the `#[app]` module and the framework gives the user complete control (on a per-task basis) over resource accessibility.
 
-Declaration of system-wide resources is done by annotating **two** `struct`s within the `#[app]` module
-with the attribute `#[local]` and `#[shared]`.
-Each field in these structures corresponds to a different resource (identified by field name).
-The difference between these two sets of resources will be covered below.
+Declaration of system-wide resources is done by annotating **two** `struct`s within the `#[app]` module with the attribute `#[local]` and `#[shared]`. Each field in these structures corresponds to a different resource (identified by field name). The difference between these two sets of resources will be covered below.
 
-Each task must declare the resources it intends to access in its corresponding metadata attribute
-using the `local` and `shared` arguments. Each argument takes a list of resource identifiers.
-The listed resources are made available to the context under the `local` and `shared` fields of the
-`Context` structure.
+Each task must declare the resources it intends to access in its corresponding metadata attribute using the `local` and `shared` arguments. Each argument takes a list of resource identifiers. The listed resources are made available to the context under the `local` and `shared` fields of the `Context` structure.
 
-The `init` task returns the initial values for the system-wide (`#[shared]` and `#[local]`)
-resources, and the set of initialized timers used by the application. The monotonic timers will be
-further discussed in [Monotonic & `spawn_{at/after}`](./monotonic.md).
+The `init` task returns the initial values for the system-wide (`#[shared]` and `#[local]`) resources.
+ 
+<!-- and the set of initialized timers used by the application. The monotonic timers will be
+further discussed in [Monotonic & `spawn_{at/after}`](./monotonic.md). -->
 
 ## `#[local]` resources
 
-`#[local]` resources are locally accessible to a specific task, meaning that only that task can
-access the resource and does so without locks or critical sections. This allows for the resources,
-commonly drivers or large objects, to be initialized in `#[init]` and then be passed to a specific
-task.
+`#[local]` resources accessible only to a single task. This task is given unique access to the resource without the use of locks or critical sections.
 
-Thus, a task `#[local]` resource can only be accessed by one singular task.
-Attempting to assign the same `#[local]` resource to more than one task is a compile-time error.
+This allows for the resources, commonly drivers or large objects, to be initialized in `#[init]` and then be passed to a specific task. (Thus, a task `#[local]` resource can only be accessed by one single task.) Attempting to assign the same `#[local]` resource to more than one task is a compile-time error.
 
-Types of `#[local]` resources must implement a [`Send`] trait as they are being sent from `init`
-to a target task, crossing a thread boundary.
+Types of `#[local]` resources must implement [`Send`] trait as they are being sent from `init` to the target task and thus crossing the *thread* boundary.
 
 [`Send`]: https://doc.rust-lang.org/stable/core/marker/trait.Send.html
 
-The example application shown below contains two tasks where each task has access to its own
-`#[local]` resource; the `idle` task has its own `#[local]` as well.
+The example application shown below contains three tasks `foo`, `bar` and `idle`, each having access to its own `#[local]` resource.
 
 ``` rust
-{{#include ../../../../examples/locals.rs}}
+{{#include ../../../../rtic/examples/locals.rs}}
 ```
 
 Running the example:
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example locals
-{{#include ../../../../ci/expected/locals.run}}
+{{#include ../../../../rtic/ci/expected/locals.run}}
 ```
 
-Local resources in `#[init]` and `#[idle]` have `'static`
-lifetimes. This is safe since both tasks are not re-entrant.
-
 ### Task local initialized resources
 
-Local resources can also be specified directly in the resource claim like so:
-`#[task(local = [my_var: TYPE = INITIAL_VALUE, ...])]`; this allows for creating locals which do no need to be
-initialized in `#[init]`.
+A special use-case of local resources are the ones specified directly in the task declaration, `#[task(local = [my_var: TYPE = INITIAL_VALUE, ...])]`. This allows for creating locals which do no need to be initialized in `#[init]`. Moreover, local resources in `#[init]` and `#[idle]` have `'static` lifetimes, this is safe since both are not re-entrant.
 
-Types of `#[task(local = [..])]` resources have to be neither [`Send`] nor [`Sync`] as they
-are not crossing any thread boundary.
+Types of `#[task(local = [..])]` resources have to be neither [`Send`] nor [`Sync`] as they are not crossing any thread boundary.
 
 [`Sync`]: https://doc.rust-lang.org/stable/core/marker/trait.Sync.html
 
 In the example below the different uses and lifetimes are shown:
 
 ``` rust
-{{#include ../../../../examples/declared_locals.rs}}
+{{#include ../../../../rtic/examples/declared_locals.rs}}
 ```
 
-<!-- ``` console
-$ cargo run --target thumbv7m-none-eabi --example declared_locals
-{{#include ../../../../ci/expected/declared_locals.run}}
-``` -->
+You can run the application, but as the example is designed merely to showcase the lifetime properties there is no output (it suffices to build the application).
+
+``` console
+$ cargo build --target thumbv7m-none-eabi --example declared_locals
+```
+<!-- {{#include ../../../../rtic/ci/expected/declared_locals.run}} -->
 
 ## `#[shared]` resources and `lock`
 
-Critical sections are required to access `#[shared]` resources in a data race-free manner and to
-achieve this the `shared` field of the passed `Context` implements the [`Mutex`] trait for each
-shared resource accessible to the task. This trait has only one method, [`lock`], which runs its
-closure argument in a critical section.
+Critical sections are required to access `#[shared]` resources in a data race-free manner and to achieve this the `shared` field of the passed `Context` implements the [`Mutex`] trait for each shared resource accessible to the task. This trait has only one method, [`lock`], which runs its closure argument in a critical section.
 
 [`Mutex`]: ../../../api/rtic/trait.Mutex.html
 [`lock`]: ../../../api/rtic/trait.Mutex.html#method.lock
 
-The critical section created by the `lock` API is based on dynamic priorities: it temporarily
-raises the dynamic priority of the context to a *ceiling* priority that prevents other tasks from
-preempting the critical section. This synchronization protocol is known as the
-[Immediate Ceiling Priority Protocol (ICPP)][icpp], and complies with
-[Stack Resource Policy (SRP)][srp] based scheduling of RTIC.
+The critical section created by the `lock` API is based on dynamic priorities: it temporarily raises the dynamic priority of the context to a *ceiling* priority that prevents other tasks from preempting the critical section. This synchronization protocol is known as the [Immediate Ceiling Priority Protocol (ICPP)][icpp], and complies with [Stack Resource Policy (SRP)][srp] based scheduling of RTIC.
 
 [icpp]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol
 [srp]: https://en.wikipedia.org/wiki/Stack_Resource_Policy
 
-In the example below we have three interrupt handlers with priorities ranging from one to three.
-The two handlers with the lower priorities contend for a `shared` resource and need to succeed in locking the
-resource in order to access its data. The highest priority handler, which does not access the `shared`
-resource, is free to preempt a critical section created by the lowest priority handler.
+In the example below we have three interrupt handlers with priorities ranging from one to three. The two handlers with the lower priorities contend for the `shared` resource and need to lock the resource for accessing the data. The highest priority handler, which do not access the `shared` resource, is free to preempt the critical section created by the lowest priority handler.
 
 ``` rust
-{{#include ../../../../examples/lock.rs}}
+{{#include ../../../../rtic/examples/lock.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example lock
-{{#include ../../../../ci/expected/lock.run}}
+{{#include ../../../../rtic/ci/expected/lock.run}}
 ```
 
 Types of `#[shared]` resources have to be [`Send`].
 
 ## Multi-lock
 
-As an extension to `lock`, and to reduce rightward drift, locks can be taken as tuples. The
-following examples show this in use:
+As an extension to `lock`, and to reduce rightward drift, locks can be taken as tuples. The following examples show this in use:
 
 ``` rust
-{{#include ../../../../examples/multilock.rs}}
+{{#include ../../../../rtic/examples/multilock.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example multilock
-{{#include ../../../../ci/expected/multilock.run}}
+{{#include ../../../../rtic/ci/expected/multilock.run}}
 ```
 
 ## Only shared (`&-`) access
 
-By default, the framework assumes that all tasks require exclusive access (`&mut-`) to resources,
-but it is possible to specify that a task only requires shared access (`&-`) to a resource using the
-`&resource_name` syntax in the `shared` list.
+By default, the framework assumes that all tasks require exclusive mutable access (`&mut-`) to resources, but it is possible to specify that a task only requires shared access (`&-`) to a resource using the `&resource_name` syntax in the `shared` list.
 
-The advantage of specifying shared access (`&-`) to a resource is that no locks are required to
-access the resource even if the resource is contended by more than one task running at different
-priorities. The downside is that the task only gets a shared reference (`&-`) to the resource,
-limiting the operations it can perform on it, but where a shared reference is enough this approach
-reduces the number of required locks. In addition to simple immutable data, this shared access can
-be useful where the resource type safely implements interior mutability, with appropriate locking
-or atomic operations of its own.
+The advantage of specifying shared access (`&-`) to a resource is that no locks are required to access the resource even if the resource is contended by more than one task running at different priorities. The downside is that the task only gets a shared reference (`&-`) to the resource, limiting the operations it can perform on it, but where a shared reference is enough this approach reduces the number of required locks. In addition to simple immutable data, this shared access can be useful where the resource type safely implements interior mutability, with appropriate locking or atomic operations of its own.
 
-Note that in this release of RTIC it is not possible to request both exclusive access (`&mut-`)
-and shared access (`&-`) to the *same* resource from different tasks. Attempting to do so will
-result in a compile error.
+Note that in this release of RTIC it is not possible to request both exclusive access (`&mut-`) and shared access (`&-`) to the *same* resource from different tasks. Attempting to do so will result in a compile error.
 
-In the example below a key (e.g. a cryptographic key) is loaded (or created) at runtime and then
-used from two tasks that run at different priorities without any kind of lock.
+In the example below a key (e.g. a cryptographic key) is loaded (or created) at runtime (returned by `init`) and then used from two tasks that run at different priorities without any kind of lock.
 
 ``` rust
-{{#include ../../../../examples/only-shared-access.rs}}
+{{#include ../../../../rtic/examples/only-shared-access.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example only-shared-access
-{{#include ../../../../ci/expected/only-shared-access.run}}
+{{#include ../../../../rtic/ci/expected/only-shared-access.run}}
 ```
 
-## Lock-free resource access of shared resources
+## Lock-free access of shared resources
 
-A critical section is *not* required to access a `#[shared]` resource that's only accessed by tasks
-running at the *same* priority. In this case, you can opt out of the `lock` API by adding the
-`#[lock_free]` field-level attribute to the resource declaration (see example below). Note that
-this is merely a convenience to reduce needless resource locking code, because even if the
+A critical section is *not* required to access a `#[shared]` resource that's only accessed by tasks running at the *same* priority. In this case, you can opt out of the `lock` API by adding the `#[lock_free]` field-level attribute to the resource declaration (see example below). 
+
+<!-- Note that this is merely a convenience to reduce needless resource locking code, because even if the
 `lock` API is used, at runtime the framework will **not** produce a critical section due to how
-the underlying resource-ceiling preemption works.
+the underlying resource-ceiling preemption works. -->
+
+To adhere to the Rust [aliasing] rule, a resource may be either accessed through multiple immutable references or a singe mutable reference (but not both at the same time). 
+
+[aliasing]: https://doc.rust-lang.org/nomicon/aliasing.html
 
-Also worth noting: using `#[lock_free]` on resources shared by
-tasks running at different priorities will result in a *compile-time* error -- not using the `lock`
-API would be a data race in that case.
+Using `#[lock_free]` on resources shared by tasks running at different priorities will result in a *compile-time* error -- not using the `lock` API would violate the aforementioned alias rule. Similarly, for each priority there can be only a single *software* task accessing a shared resource (as an `async` task may yield execution to other *software* or *hardware* tasks running at the same priority). However, under this single-task restriction, we make the observation that the resource is in effect no longer `shared` but rather `local`. Thus, using a `#[lock_free]` shared resource will result in a *compile-time* error -- where applicable, use a `#[local]` resource instead.
 
 ``` rust
-{{#include ../../../../examples/lock-free.rs}}
+{{#include ../../../../rtic/examples/lock-free.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example lock-free
-{{#include ../../../../ci/expected/lock-free.run}}
+{{#include ../../../../rtic/ci/expected/lock-free.run}}
 ```
diff --git a/book/en/src/by-example/software_tasks.md b/book/en/src/by-example/software_tasks.md
index 8ee185b..2752707 100644
--- a/book/en/src/by-example/software_tasks.md
+++ b/book/en/src/by-example/software_tasks.md
@@ -1,47 +1,99 @@
 # Software tasks & spawn
 
-The RTIC concept of a software task shares a lot with that of [hardware tasks](./hardware_tasks.md)
-with the core difference that a software task is not explicitly bound to a specific
-interrupt vector, but rather bound to a “dispatcher” interrupt vector running
-at the intended priority of the software task (see below).
+The RTIC concept of a *software* task shares a lot with that of [hardware tasks](./hardware_tasks.md) with the core difference that a software task is not explicitly bound to a specific
+interrupt vector, but rather to a “dispatcher” interrupt vector running at the same priority as the software task.
 
-Thus, software tasks are tasks which are not *directly* bound to an interrupt vector.
+Similarly to *hardware* tasks, the `#[task]` attribute used on a function declare it as a task. The absence of a `binds = InterruptName` argument to the attribute declares the function as a *software task*. 
 
-The `#[task]` attributes used on a function determine if it is
-software tasks, specifically the absence of a `binds = InterruptName`
-argument to the attribute definition.
+The static method `task_name::spawn()` spawns (starts) a software task and given that there are no higher priority tasks running the task will start executing directly.
 
-The static method `task_name::spawn()` spawns (schedules) a software
-task by registering it with a specific dispatcher.  If there are no
-higher priority tasks available to the scheduler (which serves a set
-of dispatchers), the task will start executing directly.
+The *software* task itself is given as an `async` Rust function, which allows the user to optionally `await` future events. This allows to blend reactive programming (by means of *hardware* tasks) with sequential programming (by means of *software* tasks).
 
-All software tasks at the same priority level share an interrupt handler bound to their dispatcher.
-What differentiates software and hardware tasks is the usage of either a dispatcher or a bound interrupt vector.
+Whereas, *hardware* tasks are assumed to run-to-completion (and return), *software* tasks may be started (`spawned`) once and run forever, with the side condition that any loop (execution path) is broken by at least one `await` (yielding operation). 
 
-The interrupt vectors used as dispatchers cannot be used by hardware tasks.
+All *software* tasks at the same priority level shares an interrupt handler acting as an async executor dispatching the software tasks. 
 
-Availability of a set of “free” (not in use by hardware tasks) and usable interrupt vectors allows the framework
-to dispatch software tasks via dedicated interrupt handlers.
+This list of dispatchers, `dispatchers = [FreeInterrupt1, FreeInterrupt2, ...]` is an argument to the `#[app]` attribute, where you define the set of free and usable interrupts.
 
-This set of dispatchers, `dispatchers = [FreeInterrupt1, FreeInterrupt2, ...]` is an
-argument to the `#[app]` attribute.
+Each interrupt vector acting as dispatcher gets assigned to one priority level meaning that the list of dispatchers need to cover all priority levels used by software tasks.
 
-Each interrupt vector acting as dispatcher gets assigned to a unique priority level meaning that
-the list of dispatchers needs to cover all priority levels used by software tasks.
+Example: The `dispatchers =` argument needs to have at least 3 entries for an application using three different priorities for software tasks.
 
-Example: The `dispatchers =` argument needs to have at least 3 entries for an application using
-three different priorities for software tasks.
-
-The framework will give a compilation error if there are not enough dispatchers provided.
+The framework will give a compilation error if there are not enough dispatchers provided, or if a clash occurs between the list of dispatchers and interrupts bound to *hardware* tasks.
 
 See the following example:
 
 ``` rust
-{{#include ../../../../examples/spawn.rs}}
+{{#include ../../../../rtic/examples/spawn.rs}}
 ```
 
 ``` console
 $ cargo run --target thumbv7m-none-eabi --example spawn
-{{#include ../../../../ci/expected/spawn.run}}
+{{#include ../../../../rtic/ci/expected/spawn.run}}
+```
+You may `spawn` a *software* task again, given that it has run-to-completion (returned). 
+
+In the below example, we `spawn` the *software* task `foo` from the `idle` task. Since the default priority of the *software* task is 1 (higher than `idle`), the dispatcher will execute `foo` (preempting `idle`). Since `foo` runs-to-completion. It is ok to `spawn` the `foo` task again.
+
+Technically the async executor will `poll` the `foo` *future* which in this case leaves the *future* in a *completed* state. 
+
+``` rust
+{{#include ../../../../rtic/examples/spawn_loop.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example spawn_loop
+{{#include ../../../../rtic/ci/expected/spawn_loop.run}}
+```
+
+An attempt to `spawn` an already spawned task (running) task will result in an error. Notice, the that the error is reported before the `foo` task is actually run. This is since, the actual execution of the *software* task is handled by the dispatcher interrupt (`SSIO`), which is not enabled until we exit the `init` task. (Remember, `init` runs in a critical section, i.e. all interrupts being disabled.)
+
+Technically, a `spawn` to a *future* that is not in *completed* state is considered an error.
+
+``` rust
+{{#include ../../../../rtic/examples/spawn_err.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example spawn_err
+{{#include ../../../../rtic/ci/expected/spawn_err.run}}
+```
+
+## Passing arguments
+You can also pass arguments at spawn as follows.
+
+``` rust
+{{#include ../../../../rtic/examples/spawn_arguments.rs}}
 ```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example spawn_arguments
+{{#include ../../../../rtic/ci/expected/spawn_arguments.run}}
+```
+
+## Priority zero tasks
+
+In RTIC tasks run preemptively to each other, with priority zero (0) the lowest priority. You can use priority zero tasks for background work, without any strict real-time requirements. 
+
+Conceptually, one can see such tasks as running in the `main` thread of the application, thus the resources associated are not required the [Send] bound.
+
+[Send]: https://doc.rust-lang.org/nomicon/send-and-sync.html
+
+
+``` rust
+{{#include ../../../../rtic/examples/zero-prio-task.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example zero-prio-task
+{{#include ../../../../rtic/ci/expected/zero-prio-task.run}}
+```
+
+> **Notice**: *software* task at zero priority cannot co-exist with the [idle] task. The reason is that `idle` is running as a non-returning Rust function at priority zero. Thus there would be no way for an executor at priority zero to give control to *software* tasks at the same priority.
+
+---
+
+Application side safety: Technically, the RTIC framework ensures that `poll` is never executed on any *software* task with *completed* future, thus adhering to the soundness rules of async Rust.
+
+
+
diff --git a/book/en/src/by-example/starting_a_project.md b/book/en/src/by-example/starting_a_project.md
index fe7be57..8638f90 100644
--- a/book/en/src/by-example/starting_a_project.md
+++ b/book/en/src/by-example/starting_a_project.md
@@ -10,6 +10,8 @@ If you are targeting ARMv6-M or ARMv8-M-base architecture, check out the section
 This will give you an RTIC application with support for RTT logging with [`defmt`] and stack overflow
 protection using [`flip-link`]. There is also a multitude of examples provided by the community:
 
+For inspiration you may look at the below resources. For now they cover RTIC 1.0.x, but will be updated with RTIC 2.0.x examples over time.
+
 - [`rtic-examples`] - Multiple projects
 - [https://github.com/kalkyl/f411-rtic](https://github.com/kalkyl/f411-rtic)
 - ... More to come