Merge #533

533: More docs updates r=AfoHT a=korken89



Co-authored-by: Emil Fresk <emil.fresk@gmail.com>

README.md

@@ -48,8 +48,6 @@ Formerly known as Real-Time For the Masses.
 
 ## Requirements
 
-- Rust 1.36.0+
-
 - Applications must be written using the 2018 edition.
 
 ### Crate `cortex-m` 0.6 vs 0.7 in RTIC 0.5.x

book/en/src/SUMMARY.md

@@ -4,13 +4,13 @@
 
 - [RTIC by example](./by-example.md)
   - [The `app`](./by-example/app.md)
-  - [App initialization](./by-example/app_init.md)
   - [Resources](./by-example/resources.md)
-  - [The background task](./by-example/app_idle.md)
+  - [The init task](./by-example/app_init.md)
+  - [The idle task](./by-example/app_idle.md)
   - [Defining tasks](./by-example/app_task.md)
+    - [Hardware tasks](./by-example/hardware_tasks.md)
     - [Software tasks & `spawn`](./by-example/software_tasks.md)
     - [Message passing & `capacity`](./by-example/message_passing.md)
-    - [Hardware tasks](./by-example/hardware_tasks.md)
     - [Task priorities](./by-example/app_priorities.md)
     - [Monotonic & `spawn_{at/after}`](./by-example/monotonic.md)
   - [Starting a new project](./by-example/starting_a_project.md)
@@ -18,7 +18,7 @@
   - [Tips & Tricks](./by-example/tips.md)
     - [Implementing Monotonic](./by-example/tips_monotonic_impl.md)
     - [Resource de-structure-ing](./by-example/tips_destructureing.md)
-    - [Using indirection](./by-example/tips_indirection.md)
+    - [Avoid copies when message passing](./by-example/tips_indirection.md)
     - [`'static` super-powers](./by-example/tips_static_lifetimes.md)
     - [Inspecting generated code](./by-example/tips_view_code.md)
     - [Running tasks from RAM](./by-example/tips_from_ram.md)

book/en/src/by-example/app_init.md

@@ -1,4 +1,4 @@
-# App initialization and `#[init]`
+# App initialization and the `#[init]` task
 
 An RTIC application is required an `init` task setting up the system. The corresponding function must have the signature `fn(init::Context) -> (Shared, Local, init::Monotonics)`, where `Shared` and `Local` are the resource structures defined by the user.
 

book/en/src/by-example/hardware_tasks.md

@@ -1,5 +1,9 @@
 # Hardware tasks
 
+In it's core RTIC is based on using the interrupt controller in the hardware to do scheduling and
+run tasks, as all tasks in the framework are run as interrupt handlers (except `#[init]` and
+`#[idle]`). This also means that you can directly bind tasks to interrupt handlers.
+
 To declare interrupt handlers the  `#[task]` attribute takes a `binds = InterruptName` argument whose
 value is the name of the interrupt to which the handler will be bound to; the
 function used with this attribute becomes the interrupt handler. Within the
@@ -10,8 +14,7 @@ Providing an interrupt name that does not exist will cause a compile error to he
 errors.
 
 The example below demonstrates the use of the `#[task]` attribute to declare an
-interrupt handler. Like in the case of `#[init]` and `#[idle]` local `static
+interrupt handler.
-mut` variables are safe to use within a hardware task.
 
 ``` rust
 {{#include ../../../../examples/hardware.rs}}

book/en/src/by-example/software_tasks.md

@@ -1,9 +1,20 @@
 # Software tasks & spawn
 
+Software tasks, as hardware tasks, are run as interrupt handlers where all software tasks at the
+same priority shares a "free" interrupt handler to run from, called a dispatcher. These free
+interrupts are interrupt vectors not used by hardware tasks.
+
 To declare tasks in the framework the `#[task]` attribute is used on a function.
 By default these tasks are referred to as software tasks as they do not have a direct coupling to
 an interrupt handler. Software tasks can be spawned (started) using the `task_name::spawn()` static
 method which will directly run the task given that there are no higher priority tasks running.
+
+To indicate to the framework which interrupts are free for use to dispatch software tasks with the
+`#[app]` attribute has a `dispatchers = [FreeInterrupt1, FreeInterrupt2, ...]` argument. You need
+to provide as many dispatchers as there are priority levels used by software tasks, as an
+dispatcher is assigned per interrupt level. The framework will also give a compile error if there
+are not enough dispatchers provided.
+
 This is exemplified in the following:
 
 ``` rust