diff --git a/book/en/src/by-example/hardware_tasks.md b/book/en/src/by-example/hardware_tasks.md index 30b88d0df8..7f8d3c6e14 100644 --- a/book/en/src/by-example/hardware_tasks.md +++ b/book/en/src/by-example/hardware_tasks.md @@ -14,11 +14,18 @@ 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. +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). + +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]` attribute to declare 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. ``` 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 f244ca68b1..ea40697d27 100644 --- a/book/en/src/by-example/software_tasks.md +++ b/book/en/src/by-example/software_tasks.md @@ -1,19 +1,25 @@ # Software tasks & spawn -Software tasks are tasks which are not directly assigned to a specific interrupt vector. +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 a “dispatcher” interrupt vector running +at the same priority as the software task. -They run as interrupt handlers where all software tasks at the -same priority level shares a "free" interrupt handler acting as a dispatcher. -Thus, what differentiates software and hardware tasks are the dispatcher versus -bound interrupt vector. - -These free interrupts used as dispatchers are interrupt vectors not used by hardware tasks. +Thus, software tasks are tasks which are not directly assigned to a specific interrupt vector. The `#[task]` attribute used on a function declare it as a software tasks. +Observe the absence of a `binds = InterruptName` argument to the attribute. 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. -A list of “free” and usable interrupts allows the framework to dispatch software tasks. +All software tasks at the same priority level shares an interrupt handler acting as a dispatcher. +What differentiates software and hardware tasks are the dispatcher versus bound interrupt vector. + +The interrupt vectors used as dispatchers can not be used by hardware tasks. + +A list of “free” (not in use by hardware tasks) and usable interrupts allows the framework +to dispatch software tasks. + This list of dispatchers, `dispatchers = [FreeInterrupt1, FreeInterrupt2, ...]` is an argument to the `#[app]` attribute.