Finished interrupts chapter #56

BartMassey · 2025-07-20T03:40:09Z

This PR is multiple changes that end up with a new chapter on interrupts. It also does reorganization to get the chapters in the right order. It may have also accidentally touched other things.

This probably should not be merged lightly: a check for paper-bag issues by somebody would be absolutely great.

On the bright side, when we're done everybody gets a chance to make a siren.

Thanks much to Arnav Gupta @guptaarnav for writing the bulk of the interrupts chapter. I just finished it off.

BartMassey · 2025-07-20T03:49:42Z

Dangit. Forgot to mention the lovely chapter on peripherals and polling that @guptaarnav wrote that's in here. Thanks for that as well!

eldruin

Sounds great to me. Thank you for all your work.
However, this is too big for me to review in detail at the moment, though.
If somebody else wants to review, that would be great. Regardless of them being part of the WG or not.
Otherwise, you have my blessing to just merge it.

therealprof · 2025-07-22T18:45:55Z

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

+1. Check for button presses
+2. Blink the LED
+
+But the processor can only do one thing at a time.  If we press a button during the blink delay, the processor won't be able to respond until the delay is over and the loop starts again.  As a result, we get a much less responsive program (try for yourself and see how worse it is).


worse than what? Not checking for button presses? But that's a different thing.

Thanks. Will replace with "see how much worse the button lag is".

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

therealprof · 2025-07-22T19:32:56Z

mdbook/src/15-interrupts/README.md

+### Handling Interrupts
+
+Computation is always contextual: the core always needs memory to load inputs and store outputs to.
+Our microcontroller is of what's known as a load-store-architecture, and as such the core does not


The explanation of a load-store-architecture is a bit weird. Instead of explaining what it doesn't do confusingly using the words store and load, I'd turn it around and say: it's a load and store architecture because typically the data needs to be loaded from memory into registers before doing computation and store the results back to memory afterwards. I also wouldn't refer to registers as "scratch pad memory" but rather something like in-core storage locations.

This sounds right. Will deal with it.

therealprof · 2025-07-22T19:50:02Z

mdbook/src/15-interrupts/README.md

+
+The ISR handler function is "special". The name `GPIOTE` is required here, and the function must be
+decorated with `#[interrupt]` so that it returns using a return-from-interrupt instruction rather
+than the normal way. The function may not take arguments and must return `()`.


I'm kind of missing the important detail here that this #[interrupt] does three things (not just one):

It rewrites the function to make be an interrupt handler (including the return from interrupt)

It renames the function to be not callable from the Rust program

It adds it to the interrupt table of the program so the processor knows which function to execute

Great comment. (Also (4) ensures that the type signature is fn()->().)

Will fix.

mdbook/src/15-interrupts/README.md

therealprof · 2025-07-22T20:03:23Z

mdbook/src/15-interrupts/README.md

+
+When you push the A Button, you will see an "ouch" message and then a panic. Why does the interrupt
+handler call `panic!()`? Try commenting the `panic!()` call out and see what happens when you push
+the button. You will see "ouch" messages scroll off the screen. The GPIOTE records when an interrupt


That is the case in this particular example (hopefully? I haven't checked), however there can be different effects in play here as interrupts can work in many different ways depending on the implementation and the peripherals which trigger them, too. Especially with Input pins, you can have level or edge triggering, sometimes you need to manually clear the event, sometimes they're auto cleared when you read the state, sometimes they retrigger the interrupt, sometimes they do it only exactly once.

Yes. I will add a few sentences explaining that other microcontrollers and peripherals may work differently. Your summary is great.

Upon further reading we probably need to talk about per-port and per-pin (channel) interrupts on the nRF52833. It looks like the nRF is more configurable than I thought: can allow edge, rising-edge, falling-edge, high and low triggers. It looks like edge-triggered interrupts are triggered once per transition, but level-triggered interrupts will run continuously until the latch is reset. In both cases it is advisable (and probably necessary) to clear the interrupt event.

It's an interesting question how much of this the HAL does (and should) support. I'll investigate.

therealprof · 2025-07-22T20:05:37Z

mdbook/src/15-interrupts/README.md

+keep the interrupt handlers short and quick.
+
+When the ISR function returns (using a magic instruction), the CPU looks to see if interrupts have
+happened that need to be handled, and if so calls one of the handlers (according to a priority order


No, it calls the specific handler assigned to each interrupt.

Not quite getting the distinction here. I'll clean up the text to be clearer about what happens. Maybe something like this?

Another interrupt may have happened while the current interrupt is being processed. These interrupts will "pend": the CPU will keep track of which interrupts have not yet been handled. When the current ISR function returns, the CPU will call the ISR handler for the highest-priority pending interrupt.

Naw, that's not enough. I will add a paragraph about interrupt priority, and indicate here that an interrupt handler can itself be interrupted (I think?) by a higher-priority interrupt. If a lower-priority interrupt occurs it will pend. I think? Interrupts are hard.

Maybe we should include an example showing interrupt priorities in action?

My point is: When you declare an interrupt handler in Rust via the #[interrupt] macro (as mentioned in another comment), the macro creates a special "anonymous" function which is entered into .interrupt table of the linked program. Each interrupt has exactly one entry per available interrupt, you can re-use one interrupt handler for multiple (and figure out in the interrupt handler which interrupt was actually pended) but you can't have multiple interrupt handler entry points per interrupt.

Indeed the function of the NVIC (hence the N for nested) is to call the interrupt handlers per assigned priority and preempt or interrupt execution if higher priority interrupts are pending (and resume execution accordingly once their interrupt handler has finished). To avoid that, and e.g. access shared ressources, one can disable interrupts temporarily (for this core only) which is called a "critical section" or modify the priorities of the interrupts, which is a can of worms, though. 😉

Yes. I won't get into priority inversion here 😀 but will add text to explain the existence and function of the interrupt table.

trappitsch · 2025-07-23T19:32:07Z

mdbook/src/08-inputs-and-outputs/README.md

+
+[pinmap table]: https://tech.microbit.org/hardware/schematic/#v2-pinmap
+
+Reading the state of a GPIO input involves checking whether the voltage level at the pin is high (1) or low (0). The buttons on the micro:bit are connected to pins; when the buttons are pressed, they pull the voltage at the pin low (to 0V ground).


Not sure if the (1) and (0) here are more confusing, as the sentence talks about voltage levels. Maybe putting it at 3V, 0V for high and low might be more consistent?

Text adjusted for next push. Thanks much!

trappitsch · 2025-07-23T19:43:29Z

mdbook/src/08-inputs-and-outputs/examples/blink-held.rs

I don't seem to see this example included in the book at the moment...

Yeah, should go at the end of "Polling Sucks" where we're talking about superloops. Thanks for the catch; fixed in next push.

trappitsch · 2025-07-26T01:06:07Z

mdbook/src/15-interrupts/nvic-and-interrupt-priority.md

+The NVIC can receive requests to trigger an interrupt from many peripherals. It's even common for a
+peripheral to have multiple possible interrupts, for example a GPIO port having an interrupt for
+each pin, or a UART having both a "data received" and "data finished transmission" interrupt. The
+job of the NVIC is to prioritise these interrupts, remember which ones still need to be procesed,


small typo in processed (second s missing)

trappitsch · 2025-07-26T01:09:22Z

mdbook/src/15-interrupts/nvic-and-interrupt-priority.md

+handle another that's higher priority.  This is called "preemption" and allows processors to respond
+very quickly to critical events.  For example, a robot controller might use low-priority interrupts
+to keep track sending status information to the operator, but also have a high-priority interrupt to
+detect an emergency stop button being pushed so it can immediately stop moving the motors. You


Nitpicking here, but aren't emergency stop buttons (at least the nice big red ones) most of the time hooked straight into power supply lines? Sensor detects imminent collision and needs to interrupt whatever the program is doing might be more real in the sense intended here.

trappitsch · 2025-07-26T01:50:35Z

mdbook/src/15-interrupts/waiting-to-be-interrupted.md

@@ -0,0 +1,14 @@
+# Waiting for an interrupt (wfi, wfe, nop)


The title mentions wfe as well, which is however not discussed in the text...

trappitsch · 2025-07-28T07:33:15Z

mdbook/src/15-interrupts/the-mb2-speaker.md

+the tiny rectangular hole — the "speaker port" — on the side of the device.  Do this fast enough,
+and the pressure changes will make a sound.
+
+<img class="white_bg" height="350" title="Speaker" src="../assets/speaker.svg" />


In a dark theme, the image is barely visible as there is no background color. Currently, mdbook doesnt seem to support the #only-dark, #only-light tags for images to create two images that are shown in either light or dark mode.
Looking at the Rust book as an example, the solution seems for the moment to give images solid white backgrounds. Attached an svg, if you like to use it, where I just took the existing figure and added a solid white background.

Thanks. I had intended the background to be solid white when I drew it, but apparently screwed up. Will fix.

trappitsch · 2025-07-28T07:43:47Z

mdbook/src/15-interrupts/addendum-pwm.md

@@ -0,0 +1,33 @@
+# Addendum: PWM


This file doesn't currently show up in the book itself...

Co-authored-by: Daniel Egger <[email protected]>

BartMassey · 2025-07-29T22:30:57Z

I think I've got everything noted in review comments above (and some other stuff also). Please let me know if you spot anything still lacking in the Input and Output or Interrupts chapters.

Thanks much to everybody who wrote this and everybody who provided review and help.

trappitsch · 2025-07-30T19:48:23Z

mdbook/src/15-interrupts/README.md

+
+**Note** As with most microcontrollers, there is a lot of flexibility in when the GPIOTE can generate an interrupt. Interrupts can be generated on low-to-high pin transition, high-to-low (as here), any change ("edge"), when low, or when high. On the nRF52833, interrupts generate an event that must be manually cleared in the ISR to ensure that the ISR is not called a second time for the same interrupt. Other microcontrollers may work a little differently — you should read Rust crate and microcontroller documentation to understand the details on a different board.
+
+When you push the A Button, you will see an "ouch" message and then a panic. Why does the interrupt handler call `panic!()`? Try commenting the `panic!()` call out and see what happens when you push the button. You will see "ouch" messages scroll off the screen. The NVIC records when an interrupt has been issued: that "event" is kept until it is explicitly cleared by the running program. Without the `panic!()`, when the interrupt handler returns the NVIC will (in this case) re-enable the interrupt, notice that there is still an interrupt event pending, and run the handler again. This will continue forever: each time the interrupt handler returns it will be called again. In the next section we will see how to clear the interrupt indication from within the interrupt handler.


Last sentence: "In the next section...": Technically, how to do this shows up in section 15.2 currently and not 15.1. Maybe replace with "Soon" to keep it in a non-section-number-referring way?

trappitsch · 2025-07-30T19:52:16Z

mdbook/src/15-interrupts/sharing-data-with-globals.md

+the count display into the main loop, to show that the count is shared between the interrupt handler
+and the rest of the program.
+
+Give this example (`examples/count.rs`) a run and note that the count is bumped up 1 on every push


Since examples/count.rs is not included in the text, it would be nice to provide a link to it.

trappitsch · 2025-07-30T19:52:30Z

mdbook/src/15-interrupts/sharing-data-with-globals.md

+Really, though, that `rprintln!()` in the interrupt handler is bad practice: while the interrupt
+handler is running the printing code, nothing else can move forward. Let's move the reporting to the
+main loop, just after the `wfi()` "wait for interrupt". The count will then be reported every time
+an interrupt handler finishes (`examples/count-bounce.rs`). Again, the count is bumped up 1 on every


Same here for examples/count-bounce.rs

trappitsch · 2025-07-30T20:09:05Z

Noticed a couple of small things above. Overall, this is a really smooth and instructive read, very well written chapters!

BartMassey · 2025-07-31T01:51:22Z

Thanks for the catches! Corrected, I think.

BartMassey requested a review from a team as a code owner July 20, 2025 03:40

BartMassey added enhancement New feature or request help wanted Extra attention is needed high priority Should be dealt with soon labels Jul 20, 2025

eldruin approved these changes Jul 21, 2025

View reviewed changes

therealprof reviewed Jul 22, 2025

View reviewed changes

mdbook/src/08-inputs-and-outputs/polling.md Outdated Show resolved Hide resolved

therealprof reviewed Jul 22, 2025

View reviewed changes

mdbook/src/15-interrupts/README.md Outdated Show resolved Hide resolved

therealprof reviewed Jul 22, 2025

View reviewed changes

trappitsch reviewed Jul 23, 2025

View reviewed changes

trappitsch reviewed Jul 26, 2025

View reviewed changes

trappitsch reviewed Jul 28, 2025

View reviewed changes

BartMassey added 10 commits July 29, 2025 15:28

finished first interrupt example

dbe4aab

removed unused interrupt example

cf4c921

added second example; needs debugging

109eedd

added forgotten interrupt example

259531b

added first-draft text of interrupt chapter

daff3e0

finished initial edit of interrupts, added subsections

5f74b91

cleaned up pokier.rs

529ace1

fixed some text in interrupts

977394b

added more content to sharing-data-with-globals

5035fc4

added more content to interrupts chapter

8924ab6

guptaarnav and others added 22 commits July 29, 2025 15:28

polling chapter initial draft

3062d99

small change to volatile reads in polling chapter

fa44239

small polling ch changes

06a44bc

editing ch15 summary

42daee0

starting ch15 interrupts

fa8dac3

trying again

56fbdef

finished draft polling chapter

0ddf745

wrapping up interrupt draft

1d9385e

cleaned up 08 polling-led-toggle.rs

056a56b

added 08 blink-held example

747fed6

cleaned up issues in 08 code

8fb5b33

made slight change to 15 waiting section

ae07805

removed last trace of 15 concurrency

3ad6505

fixed chapter numbering and linking issues

750db85

fixed chapter number in reference, again

4638f49

added speaker section to interrupt chapter

09da4f1

added interrupt challenge problem

b7737a3

added PWM addendum to interrupts

0306bc9

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

c5dd30f

Co-authored-by: Daniel Egger <[email protected]>

Update mdbook/src/15-interrupts/README.md

5134ee3

Co-authored-by: Daniel Egger <[email protected]>

rolled up changes suggested by review of PR #56

90a7fcf

made a final editing pass; believe ready to publish

2208e10

BartMassey force-pushed the ch-interrupts branch from c56c7bf to 2208e10 Compare July 29, 2025 22:29

trappitsch reviewed Jul 30, 2025

View reviewed changes

fixed a few more reported mistakes in interrupts chapter

f5d30f5


		[pinmap table]: https://tech.microbit.org/hardware/schematic/#v2-pinmap

		Reading the state of a GPIO input involves checking whether the voltage level at the pin is high (1) or low (0). The buttons on the micro:bit are connected to pins; when the buttons are pressed, they pull the voltage at the pin low (to 0V ground).


		Note As with most microcontrollers, there is a lot of flexibility in when the GPIOTE can generate an interrupt. Interrupts can be generated on low-to-high pin transition, high-to-low (as here), any change ("edge"), when low, or when high. On the nRF52833, interrupts generate an event that must be manually cleared in the ISR to ensure that the ISR is not called a second time for the same interrupt. Other microcontrollers may work a little differently — you should read Rust crate and microcontroller documentation to understand the details on a different board.

		When you push the A Button, you will see an "ouch" message and then a panic. Why does the interrupt handler call `panic!()`? Try commenting the `panic!()` call out and see what happens when you push the button. You will see "ouch" messages scroll off the screen. The NVIC records when an interrupt has been issued: that "event" is kept until it is explicitly cleared by the running program. Without the `panic!()`, when the interrupt handler returns the NVIC will (in this case) re-enable the interrupt, notice that there is still an interrupt event pending, and run the handler again. This will continue forever: each time the interrupt handler returns it will be called again. In the next section we will see how to clear the interrupt indication from within the interrupt handler.

Finished interrupts chapter #56

Are you sure you want to change the base?

Finished interrupts chapter #56

Uh oh!

Conversation

BartMassey commented Jul 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BartMassey commented Jul 20, 2025

Uh oh!

eldruin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BartMassey commented Jul 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trappitsch commented Jul 30, 2025

Uh oh!

BartMassey commented Jul 31, 2025

Uh oh!

Uh oh!

BartMassey commented Jul 20, 2025 •

edited

Loading