wrapping up interrupt draft

Author: guptaarnav

mdbook/src/08-inputs-and-outputs/polling-sucks.md

@@ -66,4 +66,10 @@ Superloops work and are often used in embedded systems, but the programmer has t
 
 Doing multiple things at once is called *concurrent* programming, and shows up in many places in programming, but especially in embedded systems.  There's a whole host of techniques for implementing systems that concurrently interact with peripherals while maintaining a high degree of responsiveness (e.g. interrupt handling, cooperative multitasking, event queues, etc.).  We'll explore some of these in later chapters.
 
+There is a good introduction to concurrency in an embedded context [here] that
+you might read through before proceeding.
+
+[here]: https://docs.rust-embedded.org/book/concurrency/index.html
+
+
 For now, let's take a deeper look into what's happening when we call `button_a.is_low()` or `display_pins.row1.set_high()`.

mdbook/src/15-interrupts/Cargo.toml

@@ -11,6 +11,7 @@ microbit-v2 = "0.15"
 panic-rtt-target = "0.1"
 rtt-target = "0.5"
 
+
 [dependencies.cortex-m]
 version = "0.7"
 features = ["critical-section-single-core"]

mdbook/src/15-interrupts/debouncing.md

@@ -23,6 +23,10 @@ interrupt handler sees that the timer is running, it can just do nothing.
 The implementation of all this can be seen in the next example (`examples/count-debounce.rs`). When
 you run the example you should see one count per button press.
 
+```rust
+{{#include examples/count-debounce.rs}}
+```
+
 > **NOTE** The buttons on the MB2 are a little fiddly: it's pretty easy to push one down enough to
 feel a "click" but not enough to actually make contact with the switch. I recommend using a
 fingernail to press the button when testing.

mdbook/src/15-interrupts/examples/count-debounce.rs

@@ -1,7 +1,10 @@
 #![no_main]
 #![no_std]
 
-use core::sync::atomic::{AtomicUsize, Ordering::{Acquire, AcqRel}};
+use core::sync::atomic::{
+    AtomicUsize,
+    Ordering::{AcqRel, Acquire},
+};
 
 use cortex_m::asm;
 use cortex_m_rt::entry;
@@ -10,12 +13,11 @@ use panic_rtt_target as _;
 use rtt_target::{rprintln, rtt_init_print};
 
 use microbit::{
-    Board,
     hal::{
-        self,
-        gpiote,
+        self, gpiote,
         pac::{self, interrupt},
     },
+    Board,
 };
 
 static COUNTER: AtomicUsize = AtomicUsize::new(0);

mdbook/src/15-interrupts/my-solution.md

@@ -0,0 +1,14 @@
+# Waiting for an interrupt (wfi, wfe, nop)
+
+You may have wondered why we have been using `asm::wfi()` (wait for instruction) in our main loop instead of
+something like `asm::nop()`.
+
+As discussed before, `asm::nop()` means no-op(eration), and is an instruction that the CPU executes without doing anything .  We definitely could have used `asm::nop()` in our main loop instead, and the program would have behaved the same way.  The microcontroller, on the other hand, would behave differently. 
+
+Calling `asm::wfi()` puts the CPU into wfi mode.  When the CPU is in wfi mode, it will sleep until an interrupt wakes it up.  During sleep, the CPU will stop fetching instructions, turn off clocks and peripherals, and enter a low-power state, but still keep the core running.  When an interrupt occurs, the CPU will wake up and execute as normal.  
+
+The main difference between `asm::wfi()` and `asm::nop()` is that the NOP instruction is still an instruction.  It still needs to be fetched from the program memory and be executed even though the execution doesn't do anything.  Most microcontrollers you'll find out there have a low-power mode (some even have several, each with varying things staying on and each with different power consumption characteristics) that can, and *should* in a lot of cases, be used to save power.
+
+You'll find some interrupt-driven programs that consist of nothing but `asm::wfi()` in the main loop, with all program logic being implemented in the interrupt handlers.
+
+

mdbook/src/15-interrupts/turn-signaller-revisited.md

@@ -5,13 +5,6 @@ game that you can play on an MB2 using its 5×5 LED matrix as a display and its
 controls. In doing so, we will build on some of the concepts covered in the earlier chapters of this
 book, and also learn about some new peripherals and concepts.
 
-In particular, we will be using the concept of hardware interrupts to allow our program to interact
-with multiple peripherals at once. Interrupts are a common way to implement concurrency in embedded
-contexts. There is a good introduction to concurrency in an embedded context [here] that
-you might read through before proceeding.
-
-[here]: https://docs.rust-embedded.org/book/concurrency/index.html
-
 ## Modularity
 
 The source code here is more modular than it probably should be. This fine-grained modularity allows

mdbook/src/15-interrupts/waiting-for-an-interrupt.md

@@ -66,10 +66,7 @@
   - [NVIC and interrupt priority](15-interrupts/nvic-and-interrupt-priority.md)
   - [Sharing data with globals](15-interrupts/sharing-data-with-globals.md)
   - [Debouncing](15-interrupts/debouncing.md)
-  - [Waiting for an interrupt (wfi, wfe, nop)](15-interrupts/waiting-for-an-interrupt.md)
-  - [Turn signaller revisited](15-interrupts/turn-signaller-revisited.md)
-  - [My solution](15-interrupts/my-solution.md)
-  - [Concurrency](15-interrupts/concurrency.md)
+  - [Waiting to be interrupted](15-interrupts/waiting-to-be-interrupted.md)
 - [Snake game](16-snake-game/README.md)
   - [Game logic](16-snake-game/game-logic.md)
   - [Controls](16-snake-game/controls.md)