Add ToC

01_wait_forever/README.md

@@ -31,13 +31,13 @@ Project skeleton is set up; Code just halts all CPU cores executing the kernel c
 
 [inner attributes]: https://doc.rust-lang.org/reference/attributes.html
 
-### Give it a try
+### Test it
 
 In the project folder, invoke QEMU and observe the CPU core spinning on `wfe`:
 ```console
 make qemu
 [...]
-IN: 
-0x00080000:  d503205f  wfe      
+IN:
+0x00080000:  d503205f  wfe
 0x00080004:  17ffffff  b        #0x80000
 ```

02_runtime_init/README.md

@@ -2,7 +2,7 @@
 
 ## tl;dr
 
-We are calling into Rust code for the first time and zero the [bss](https://en.wikipedia.org/wiki/.bss) section.
+We are calling into Rust code for the first time and zero the [bss] section.
 Check out `make qemu` again to see the additional code run.
 
 - More sections in linker script:
@@ -16,6 +16,8 @@ Check out `make qemu` again to see the additional code run.
      - Calls `kernel_init()`, which calls `panic!()`, which eventually halts
        `core0` as well.
 
+[bss]: https://en.wikipedia.org/wiki/.bss
+
 ## Diff to previous
 ```diff
 

03_hacky_hello_world/README.md

@@ -12,9 +12,10 @@ Using  the real hardware `UART` is enabled step-by-step in following tutorials.
 - Panic handler `print!()`s supplied error messages.
     - This is showcased in `main()`.
 
-### Give it a try
+### Test it
 
-QEMU is no longer run in assembly mode. It will from now on show the output of `UART0`.
+QEMU is no longer running in assembly mode. It will from now on show the output
+of the `console`.
 
 ```console
 make qemu

05_safe_globals/README.md

@@ -39,7 +39,7 @@ you can check out implemntations in the [spin crate] or the [parking lot crate].
 [spin crate]: https://github.com/mvdnes/spin-rs
 [parking lot crate]: https://github.com/Amanieu/parking_lot
 
-### Give it a try
+### Test it
 
 ```console
 make qemu

07_uart_chainloader/README.md

@@ -25,7 +25,7 @@ You can try it with this tutorial already:
 make chainboot
 [...]
 ### Listening on /dev/ttyUSB0
- __  __ _      _ _                 _ 
+ __  __ _      _ _                 _
 |  \/  (_)_ _ (_) |   ___  __ _ __| |
 | |\/| | | ' \| | |__/ _ \/ _` / _` |
 |_|  |_|_|_||_|_|____\___/\__,_\__,_|
@@ -49,7 +49,7 @@ In this tutorial, a version of the kernel from the previous tutorial is loaded
 for demo purposes. In subsequent tuts, it will be the working directory's
 kernel.
 
-### Observing the jump
+## Test it
 
 The `Makefile` in this tutorial has an additional target, `qemuasm`, that lets
 you nicely observe the jump from the loaded address (`0x80_XXX`) to the

08_timestamps/README.md

@@ -5,6 +5,8 @@
 We add abstractions for the architectural timer, implement it for `aarch64` and
 use it to annotate prints with timestamps; A `warn!()` macro is added.
 
+## Test it
+
 Check it out via chainboot (added in previous tutorial):
 ```console
 make chainboot

09_hw_debug_JTAG/README.md

@@ -10,6 +10,26 @@ In the exact order as listed:
 4. In new terminal, `make openocd` and keep terminal open.
 5. In new terminal, `make gdb` or make `make gdb-opt0`.
 
+![JTAG live demo](../doc/jtag_demo.gif)
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Outline](#outline)
+- [Software Setup](#software-setup)
+- [Hardware Setup](#hardware-setup)
+  * [Wiring](#wiring)
+- [Getting ready to connect](#getting-ready-to-connect)
+- [OpenOCD](#openocd)
+- [GDB](#gdb)
+  * [Remarks](#remarks)
+    + [Optimization](#optimization)
+    + [GDB control](#gdb-control)
+- [Notes on USB connection constraints](#notes-on-usb-connection-constraints)
+- [Additional resources](#additional-resources)
+- [Acknowledgments](#acknowledgments)
+- [Diff to previous](#diff-to-previous)
+
 ## Introduction
 
 In the upcoming tutorials, we are going to touch sensitive areas of the RPi's SoC that can make our
@@ -24,8 +44,6 @@ simulate down to the very last bit.
 So lets introduce `JTAG` debugging. Once set up, it will allow us to single-step through our kernel
 on the real HW. How cool is that?!
 
-![JTAG live demo](../doc/jtag_demo.gif)
-
 ## Outline
 
 From kernel perspective, this tutorial is the same as the previous one. We are just wrapping

10_privilege_level/README.md

@@ -2,8 +2,19 @@
 
 ## tl;dr
 
-In early boot code, we transition from the `Hypervisor` privilege level (`EL2` in AArch64) to the
-`Kernel` (`EL1`) privilege level.
+In early boot code, we transition from the `Hypervisor` privilege level (`EL2`
+in AArch64) to the `Kernel` (`EL1`) privilege level.
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Scope of this tutorial](#scope-of-this-tutorial)
+- [Checking for EL2 in the entrypoint](#checking-for-el2-in-the-entrypoint)
+- [Transition preparation](#transition-preparation)
+- [Returning from an exception that never happened](#returning-from-an-exception-that-never-happened)
+- [Are we stackless?](#are-we-stackless)
+- [Test it](#test-it)
+- [Diff to previous](#diff-to-previous)
 
 ## Introduction
 
@@ -172,7 +183,7 @@ Disassembly of section .text:
 Looks good! Thanks zero-overhead abstractions in the
 [cortex-a](https://github.com/rust-embedded/cortex-a) crate! :heart_eyes:
 
-## Testing
+## Test it
 
 In `main.rs`, we additionally inspect if the mask bits in `SPSR_EL2` made it to `EL1` as well:
 

11_virtual_memory/README.md

@@ -5,6 +5,20 @@
 The `MMU` is turned on; A simple scheme is used: static `64 KiB` page tables; For educational
 purposes, we write to a remapped `UART`.
 
+## Table of Contents
+
+- [Introduction](#introduction)
+- [MMU and paging theory](#mmu-and-paging-theory)
+- [Approach](#approach)
+  * [BSP: `bsp/rpi/virt_mem_layout.rs`](#bsp-bsprpivirt_mem_layoutrs)
+  * [Arch: `arch/aarch64/mmu.rs`](#arch-archaarch64mmurs)
+  * [`link.ld`](#linkld)
+- [Address translation examples](#address-translation-examples)
+  * [Address translation using a 64 KiB page descriptor](#address-translation-using-a-64-kib-page-descriptor)
+- [Zero-cost abstraction](#zero-cost-abstraction)
+- [Test it](#test-it)
+- [Diff to previous](#diff-to-previous)
+
 ## Introduction
 
 Virtual memory is an immensely complex, but important and powerful topic. In this tutorial, we start

12_cpu_exceptions_part1/README.md

@@ -9,6 +9,21 @@ development and runtime.
 For demo purposes, MMU `page faults` are used to demonstrate (i) returning from an exception and
 (ii) the default `panic!` behavior.
 
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Exception Types](#exception-types)
+- [Exception entry](#exception-entry)
+  * [Exception Vectors](#exception-vectors)
+- [Handler Code and Offsets](#handler-code-and-offsets)
+- [Rust and Assembly Implementation](#rust-and-assembly-implementation)
+  * [Context Save and Restore](#context-save-and-restore)
+  * [Exception Vector Table](#exception-vector-table)
+  * [Implementing handlers](#implementing-handlers)
+- [Causing an Exception - Testing the Code](#causing-an-exception---testing-the-code)
+- [Test it](#test-it)
+- [Diff to previous](#diff-to-previous)
+
 ## Introduction
 
 Now that we are executing in `EL1`, and have activated the `MMU`, time is due for implementing `CPU