Refactor tutorial 02

02_runtime_init/Makefile

@@ -13,16 +13,16 @@ ifeq ($(BSP),rpi3)
 	OUTPUT            = kernel8.img
 	QEMU_BINARY       = qemu-system-aarch64
 	QEMU_MACHINE_TYPE = raspi3
-	QEMU_RELEASE_ARGS = -serial stdio -display none
-	LINKER_FILE       = src/bsp/rpi/link.ld
+	QEMU_RELEASE_ARGS = -d in_asm -display none
+	LINKER_FILE       = src/bsp/raspberrypi/link.ld
 	RUSTC_MISC_ARGS   = -C target-cpu=cortex-a53
 else ifeq ($(BSP),rpi4)
 	TARGET            = aarch64-unknown-none-softfloat
 	OUTPUT            = kernel8.img
 	# QEMU_BINARY       = qemu-system-aarch64
 	# QEMU_MACHINE_TYPE =
-	# QEMU_RELEASE_ARGS = -serial stdio -display none
-	LINKER_FILE       = src/bsp/rpi/link.ld
+	# QEMU_RELEASE_ARGS = -d in_asm -display none
+	LINKER_FILE       = src/bsp/raspberrypi/link.ld
 	RUSTC_MISC_ARGS   = -C target-cpu=cortex-a72
 endif
 
@@ -60,8 +60,7 @@ $(OUTPUT): $(CARGO_OUTPUT)
 	$(OBJCOPY_CMD) $< $(OUTPUT)
 
 doc:
-	cargo xdoc --target=$(TARGET) --features bsp_$(BSP) --document-private-items
-	xdg-open target/$(TARGET)/doc/kernel/index.html
+	cargo xdoc --target=$(TARGET) --features bsp_$(BSP) --document-private-items --open
 
 ifeq ($(QEMU_MACHINE_TYPE),)
 qemu:

02_runtime_init/README.md

@@ -2,194 +2,22 @@
 
 ## tl;dr
 
-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.
+We extend `cpu.S` to call into Rust code for the first time. There,we zero the [bss] section before
+execution is halted with a call to `panic()`. Check out `make qemu` again to see the additional code
+run.
+
+## Notable additions
 
 - More sections in linker script:
      - `.rodata`, `.data`
      - `.bss`
 - `_start()`:
      - Halt core if core != `core0`.
-     - `core0` jumps to `runtime_init()` Rust function.
+     - `core0` jumps to the `runtime_init()` Rust function.
 - `runtime_init()` in `runtime_init.rs`
      - Zeros the `.bss` section.
-     - Calls `kernel_init()`, which calls `panic!()`, which eventually halts
-       `core0` as well.
+     - Calls `kernel_init()`, which calls `panic!()`, which eventually halts `core0` as well.
 
 [bss]: https://en.wikipedia.org/wiki/.bss
 
 ## Diff to previous
-```diff
-
-diff -uNr 01_wait_forever/Cargo.toml 02_runtime_init/Cargo.toml
---- 01_wait_forever/Cargo.toml
-+++ 02_runtime_init/Cargo.toml
-@@ -14,4 +14,3 @@
- bsp_rpi4 = []
-
- [dependencies]
--
-
-diff -uNr 01_wait_forever/src/arch/aarch64/start.S 02_runtime_init/src/arch/aarch64/start.S
---- 01_wait_forever/src/arch/aarch64/start.S
-+++ 02_runtime_init/src/arch/aarch64/start.S
-@@ -7,5 +7,15 @@
- .global _start
-
- _start:
--1:  wfe         // Wait for event
--    b       1b  // In case an event happened, jump back to 1
-+    mrs     x1, mpidr_el1   // Read Multiprocessor Affinity Register
-+    and     x1, x1, #3      // Clear all bits except [1:0], which hold core id
-+    cbz     x1, 2f          // Jump to label 2 if we are core 0
-+1:  wfe                     // Wait for event
-+    b       1b              // In case an event happened, jump back to 1
-+2:                          // If we are here, we are core0
-+    ldr     x1, =_start     // Load address of function "_start()"
-+    mov     sp, x1          // Set start of stack to before our code, aka first
-+                            // address before "_start()"
-+    bl      runtime_init    // Jump to the "runtime_init()" kernel function
-+    b       1b              // We should never reach here. But just in case,
-+                            // park this core aswell
-
-diff -uNr 01_wait_forever/src/bsp/rpi/link.ld 02_runtime_init/src/bsp/rpi/link.ld
---- 01_wait_forever/src/bsp/rpi/link.ld
-+++ 02_runtime_init/src/bsp/rpi/link.ld
-@@ -13,5 +13,24 @@
-         *(.text._start) *(.text*)
-     }
-
-+    .rodata :
-+    {
-+        *(.rodata*)
-+    }
-+
-+    .data :
-+    {
-+        *(.data*)
-+    }
-+
-+    /* Section is zeroed in u64 chunks, align start and end to 8 bytes */
-+    .bss ALIGN(8):
-+    {
-+        __bss_start = .;
-+        *(.bss*);
-+        . = ALIGN(8);
-+        __bss_end = .;
-+    }
-+
-     /DISCARD/ : { *(.comment*) }
- }
-
-diff -uNr 01_wait_forever/src/main.rs 02_runtime_init/src/main.rs
---- 01_wait_forever/src/main.rs
-+++ 02_runtime_init/src/main.rs
-@@ -16,9 +16,20 @@
- // the first function to run.
- mod arch;
-
-+// `_start()` then calls `runtime_init()`, which on completion, jumps to `kernel_init()`.
-+mod runtime_init;
-+
- // Conditionally includes the selected `BSP` code.
- mod bsp;
-
-+mod memory;
- mod panic_wait;
-
--// Kernel code coming next tutorial.
-+/// Early init code.
-+///
-+/// # Safety
-+///
-+/// - Only a single core must be active and running this function.
-+unsafe fn kernel_init() -> ! {
-+    panic!()
-+}
-
-diff -uNr 01_wait_forever/src/memory.rs 02_runtime_init/src/memory.rs
---- 01_wait_forever/src/memory.rs
-+++ 02_runtime_init/src/memory.rs
-@@ -0,0 +1,25 @@
-+// SPDX-License-Identifier: MIT OR Apache-2.0
-+//
-+// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
-+
-+//! Memory Management.
-+
-+use core::ops::Range;
-+
-+/// Zero out a memory region.
-+///
-+/// # Safety
-+///
-+/// - `range.start` and `range.end` must be valid.
-+/// - `range.start` and `range.end` must be `T` aligned.
-+pub unsafe fn zero_volatile<T>(range: Range<*mut T>)
-+where
-+    T: From<u8>,
-+{
-+    let mut ptr = range.start;
-+
-+    while ptr < range.end {
-+        core::ptr::write_volatile(ptr, T::from(0));
-+        ptr = ptr.offset(1);
-+    }
-+}
-
-diff -uNr 01_wait_forever/src/runtime_init.rs 02_runtime_init/src/runtime_init.rs
---- 01_wait_forever/src/runtime_init.rs
-+++ 02_runtime_init/src/runtime_init.rs
-@@ -0,0 +1,50 @@
-+// SPDX-License-Identifier: MIT OR Apache-2.0
-+//
-+// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
-+
-+//! Rust runtime initialization code.
-+
-+use crate::memory;
-+use core::ops::Range;
-+
-+/// Return the range spanning the .bss section.
-+///
-+/// # Safety
-+///
-+/// - The symbol-provided addresses must be valid.
-+/// - The symbol-provided addresses must be usize aligned.
-+unsafe fn bss_range() -> Range<*mut usize> {
-+    extern "C" {
-+        // Boundaries of the .bss section, provided by linker script symbols.
-+        static mut __bss_start: usize;
-+        static mut __bss_end: usize;
-+    }
-+
-+    Range {
-+        start: &mut __bss_start,
-+        end: &mut __bss_end,
-+    }
-+}
-+
-+/// Zero out the .bss section.
-+///
-+/// # Safety
-+///
-+/// - Must only be called pre `kernel_init()`.
-+#[inline(always)]
-+unsafe fn zero_bss() {
-+    memory::zero_volatile(bss_range());
-+}
-+
-+/// Equivalent to `crt0` or `c0` code in C/C++ world. Clears the `bss` section, then jumps to kernel
-+/// init code.
-+///
-+/// # Safety
-+///
-+/// - Only a single core must be active and running this function.
-+#[no_mangle]
-+pub unsafe extern "C" fn runtime_init() -> ! {
-+    zero_bss();
-+
-+    crate::kernel_init()
-+}
-
-```

02_runtime_init/src/_arch/aarch64/cpu.rs

@@ -2,15 +2,16 @@
 //
 // Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
 
-//! AArch64.
+//! Architectural processor code.
 
-global_asm!(include_str!("aarch64/start.S"));
+// Assembly counterpart to this file.
+global_asm!(include_str!("cpu.S"));
 
 //--------------------------------------------------------------------------------------------------
-// Implementation of the kernel's architecture abstraction code
+// Public Code
 //--------------------------------------------------------------------------------------------------
 
-/// Pause execution on the calling CPU core.
+/// Pause execution on the core.
 #[inline(always)]
 pub fn wait_forever() -> ! {
     unsafe {

02_runtime_init/src/arch.rs

@@ -1,11 +0,0 @@
-// SPDX-License-Identifier: MIT OR Apache-2.0
-//
-// Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
-
-//! Conditional exporting of processor architecture code.
-
-#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
-mod aarch64;
-
-#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
-pub use aarch64::*;

02_runtime_init/src/bsp.rs

@@ -2,10 +2,10 @@
 //
 // Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
 
-//! Conditional exporting of Board Support Packages.
+//! Conditional re-exporting of Board Support Packages.
 
 #[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
-mod rpi;
+mod raspberrypi;
 
 #[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
-pub use rpi::*;
+pub use raspberrypi::*;

02_runtime_init/src/bsp/raspberrypi.rs

@@ -2,6 +2,6 @@
 //
 // Copyright (c) 2018-2020 Andre Richter <andre.o.richter@gmail.com>
 
-//! Board Support Package for the Raspberry Pi.
+//! Top-level BSP file for the Raspberry Pi 3 and 4.
 
 // Coming soon.

02_runtime_init/src/cpu.rs

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2020 Andre Richter <andre.o.richter@gmail.com>
+
+//! Processor code.
+
+#[cfg(target_arch = "aarch64")]
+#[path = "_arch/aarch64/cpu.rs"]
+mod arch_cpu;
+pub use arch_cpu::*;

02_runtime_init/src/main.rs

@@ -5,25 +5,106 @@
 // Rust embedded logo for `make doc`.
 #![doc(html_logo_url = "https://git.io/JeGIp")]
 
-//! The `kernel`
+//! The `kernel` binary.
+//!
+//! # Code organization and architecture
+//!
+//! The code is divided into different *modules*, each representing a typical **subsystem** of the
+//! `kernel`. Top-level module files of subsystems reside directly in the `src` folder. For example,
+//! `src/memory.rs` contains code that is concerned with all things memory management.
+//!
+//! ## Visibility of processor architecture code
+//!
+//! Some of the `kernel`'s subsystems depend on low-level code that is specific to the target
+//! processor architecture. For each supported processor architecture, there exists a subfolder in
+//! `src/_arch`, for example, `src/_arch/aarch64`.
+//!
+//! The architecture folders mirror the subsystem modules laid out in `src`. For example,
+//! architectural code that belongs to the `kernel`'s memory subsystem (`src/memory.rs`) would go
+//! into `src/_arch/aarch64/memory.rs`. The latter file is directly included and re-exported in
+//! `src/memory.rs`, so that the architectural code parts are transparent with respect to the code's
+//! module organization. That means a public function `foo()` defined in
+//! `src/_arch/aarch64/memory.rs` would be reachable as `crate::memory::foo()` only.
+//!
+//! The `_` in `_arch` denotes that this folder is not part of the standard module hierarchy.
+//! Rather, it's contents are conditionally pulled into respective files using the `#[path =
+//! "_arch/xxx/yyy.rs"]` attribute.
+//!
+//! ## BSP code
+//!
+//! `BSP` stands for Board Support Package. `BSP` code is organized under `src/bsp.rs` and contains
+//! target board specific definitions and functions. These are things such as the board's memory map
+//! or instances of drivers for devices that are featured on the respective board.
+//!
+//! Just like processor architecture code, the `BSP` code's module structure tries to mirror the
+//! `kernel`'s subsystem modules, but there is no transparent re-exporting this time. That means
+//! whatever is provided must be called starting from the `bsp` namespace, e.g.
+//! `bsp::driver::driver_manager()`.
+//!
+//! ## Kernel interfaces
+//!
+//! Both `arch` and `bsp` contain code that is conditionally compiled depending on the actual target
+//! and board for which the kernel is compiled. For example, the `interrupt controller` hardware of
+//! the `Raspberry Pi 3` and the `Raspberry Pi 4` is different, but we want the rest of the `kernel`
+//! code to play nicely with any of the two without much hassle.
+//!
+//! In order to provide a clean abstraction between `arch`, `bsp` and `generic kernel code`,
+//! `interface` traits are provided *whenever possible* and *where it makes sense*. They are defined
+//! in the respective subsystem module and help to enforce the idiom of *program to an interface,
+//! not an implementation*. For example, there will be a common IRQ handling interface which the two
+//! different interrupt controller `drivers` of both Raspberrys will implement, and only export the
+//! interface to the rest of the `kernel`.
+//!
+//! ```
+//!         +-------------------+
+//!         | Interface (Trait) |
+//!         |                   |
+//!         +--+-------------+--+
+//!            ^             ^
+//!            |             |
+//!            |             |
+//! +----------+--+       +--+----------+
+//! | kernel code |       |  bsp code   |
+//! |             |       |  arch code  |
+//! +-------------+       +-------------+
+//! ```
+//!
+//! # Summary
+//!
+//! For a logical `kernel` subsystem, corresponding code can be distributed over several physical
+//! locations. Here is an example for the **memory** subsystem:
+//!
+//! - `src/memory.rs` and `src/memory/**/*`
+//!   - Common code that is agnostic of target processor architecture and `BSP` characteristics.
+//!     - Example: A function to zero a chunk of memory.
+//!   - Interfaces for the memory subsystem that are implemented by `arch` or `BSP` code.
+//!     - Example: An `MMU` interface that defines `MMU` function prototypes.
+//! - `src/bsp/__board_name__/memory.rs` and `src/bsp/__board_name__/memory/**/*`
+//!   - `BSP` specific code.
+//!   - Example: The board's memory map (physical addresses of DRAM and MMIO devices).
+//! - `src/_arch/__arch_name__/memory.rs` and `src/_arch/__arch_name__/memory/**/*`
+//!   - Processor architecture specific code.
+//!   - Example: Implementation of the `MMU` interface for the `__arch_name__` processor
+//!     architecture.
+//!
+//! From a namespace perspective, **memory** subsystem code lives in:
+//!
+//! - `crate::memory::*`
+//! - `crate::bsp::memory::*`
 
 #![feature(asm)]
 #![feature(global_asm)]
 #![no_main]
 #![no_std]
 
-// Conditionally includes the selected `architecture` code, which provides the `_start()` function,
-// the first function to run.
-mod arch;
+// `mod cpu` provides the `_start()` function, the first function to run. `_start()` then calls
+// `runtime_init()`, which jumps to `kernel_init()`.
 
-// `_start()` then calls `runtime_init()`, which on completion, jumps to `kernel_init()`.
-mod runtime_init;
-
-// Conditionally includes the selected `BSP` code.
 mod bsp;
-
+mod cpu;
 mod memory;
 mod panic_wait;
+mod runtime_init;
 
 /// Early init code.
 ///

02_runtime_init/src/memory.rs

@@ -6,6 +6,10 @@
 
 use core::ops::Range;
 
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
 /// Zero out a memory region.
 ///
 /// # Safety

02_runtime_init/src/panic_wait.rs

@@ -4,9 +4,10 @@
 
 //! A panic handler that infinitely waits.
 
+use crate::cpu;
 use core::panic::PanicInfo;
 
 #[panic_handler]
 fn panic(_info: &PanicInfo) -> ! {
-    crate::arch::wait_forever()
+    cpu::wait_forever()
 }

02_runtime_init/src/runtime_init.rs

@@ -7,6 +7,10 @@
 use crate::memory;
 use core::ops::Range;
 
+//--------------------------------------------------------------------------------------------------
+// Private Code
+//--------------------------------------------------------------------------------------------------
+
 /// Return the range spanning the .bss section.
 ///
 /// # Safety
@@ -36,6 +40,10 @@ unsafe fn zero_bss() {
     memory::zero_volatile(bss_range());
 }
 
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
 /// Equivalent to `crt0` or `c0` code in C/C++ world. Clears the `bss` section, then jumps to kernel
 /// init code.
 ///