The great docs update

1 files changed, 24 insertions, 0 deletions

diff --git a/book/en/src/by-example/hardware_tasks.md b/book/en/src/by-example/hardware_tasks.md
new file mode 100644
index 0000000..5f7b26f
--- /dev/null
+++ b/book/en/src/by-example/hardware_tasks.md
@@ -0,0 +1,24 @@
+# Hardware tasks
+
+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
+framework these type of tasks are referred to as *hardware* tasks, because they
+start executing in reaction to a hardware event.
+
+Providing an interrupt name that does not exist will cause a compile error to help with accidental
+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.
+
+``` rust
+{{#include ../../../../examples/hardware.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example hardware
+{{#include ../../../../ci/expected/hardware.run}}
+```
+