Merge #533

533: More docs updates r=AfoHT a=korken89



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

3 files changed, 17 insertions, 3 deletions

diff --git a/book/en/src/by-example/app_init.md b/book/en/src/by-example/app_init.md
index 7a73e1b..3112ccf 100644
--- a/book/en/src/by-example/app_init.md
+++ b/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.
 
diff --git a/book/en/src/by-example/hardware_tasks.md b/book/en/src/by-example/hardware_tasks.md
index 5f7b26f..cb0cf9f 100644
--- a/book/en/src/by-example/hardware_tasks.md
+++ b/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
-mut` variables are safe to use within a hardware task.
+interrupt handler.
 
 ``` rust
 {{#include ../../../../examples/hardware.rs}}
diff --git a/book/en/src/by-example/software_tasks.md b/book/en/src/by-example/software_tasks.md
index 0c9b62e..f78efea 100644
--- a/book/en/src/by-example/software_tasks.md
+++ b/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