From f6832bec311c2a712034490c352ecf27e13de7ec Mon Sep 17 00:00:00 2001 From: Andre Richter Date: Tue, 31 Dec 2019 00:00:09 +0100 Subject: [PATCH] Add ToC --- 01_wait_forever/README.md | 6 +++--- 02_runtime_init/README.md | 4 +++- 03_hacky_hello_world/README.md | 5 +++-- 05_safe_globals/README.md | 2 +- 07_uart_chainloader/README.md | 4 ++-- 08_timestamps/README.md | 2 ++ 09_hw_debug_JTAG/README.md | 22 ++++++++++++++++++++-- 10_privilege_level/README.md | 17 ++++++++++++++--- 11_virtual_memory/README.md | 14 ++++++++++++++ 12_cpu_exceptions_part1/README.md | 15 +++++++++++++++ 10 files changed, 77 insertions(+), 14 deletions(-) diff --git a/01_wait_forever/README.md b/01_wait_forever/README.md index 5abac1b2..e2ec9292 100644 --- a/01_wait_forever/README.md +++ b/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 ``` diff --git a/02_runtime_init/README.md b/02_runtime_init/README.md index 6714662c..f4c4a62c 100644 --- a/02_runtime_init/README.md +++ b/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 diff --git a/03_hacky_hello_world/README.md b/03_hacky_hello_world/README.md index 6ffa8232..0f37c56d 100644 --- a/03_hacky_hello_world/README.md +++ b/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 diff --git a/05_safe_globals/README.md b/05_safe_globals/README.md index 95d4a672..2976e362 100644 --- a/05_safe_globals/README.md +++ b/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 diff --git a/07_uart_chainloader/README.md b/07_uart_chainloader/README.md index 563eb99e..2160f6e9 100644 --- a/07_uart_chainloader/README.md +++ b/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 diff --git a/08_timestamps/README.md b/08_timestamps/README.md index 7b80a603..6552d3f8 100644 --- a/08_timestamps/README.md +++ b/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 diff --git a/09_hw_debug_JTAG/README.md b/09_hw_debug_JTAG/README.md index 6dbbae55..f17f976e 100644 --- a/09_hw_debug_JTAG/README.md +++ b/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 diff --git a/10_privilege_level/README.md b/10_privilege_level/README.md index 4f2d8436..d44fb880 100644 --- a/10_privilege_level/README.md +++ b/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: diff --git a/11_virtual_memory/README.md b/11_virtual_memory/README.md index 8f666114..7bcb178a 100644 --- a/11_virtual_memory/README.md +++ b/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 diff --git a/12_cpu_exceptions_part1/README.md b/12_cpu_exceptions_part1/README.md index 17ce4e61..f06ed02c 100644 --- a/12_cpu_exceptions_part1/README.md +++ b/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