refactor: 📦 Clean up code

Debugging with jtag.
Explicitly default to no features.
Allow unused allocator code.
Add board selection.
Add RPi4 datasheet.
Add explanation on bss alignment type.

Makefile.toml

@@ -47,7 +47,7 @@ TARGET_JSON = "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/targets/${TARGET}.json"
 PLATFORM_TARGET="--target=${TARGET_JSON} --features=${TARGET_FEATURES} ${RUST_LIBS}"
 
 DEVICE_FEATURES = "noserial"
-QEMU_FEATURES = "qemu"
+QEMU_FEATURES = "qemu,rpi3"
 
 OBJCOPY = "rust-objcopy" # Part of `cargo objcopy` in cargo-binutils
 OBJCOPY_PARAMS = "--strip-all -O binary"
@@ -86,7 +86,7 @@ command = "cargo"
 args = ["modules", "tree"]
 
 [tasks.build]
-env = { "TARGET_FEATURES" = "" }
+env = { "TARGET_FEATURES" = "${TARGET_BOARD}" }
 command = "cargo"
 args = ["build", "@@split(PLATFORM_TARGET, )", "--release"]
 
@@ -111,7 +111,7 @@ command = "cargo"
 args = ["doc", "--open", "--no-deps", "@@split(PLATFORM_TARGET, )"]
 
 [tasks.clippy]
-env = { "TARGET_FEATURES" = "", "CLIPPY_FEATURES" = { value = "--features=${CLIPPY_FEATURES}", condition = { env_set = ["CLIPPY_FEATURES"] } } }
+env = { "TARGET_FEATURES" = "rpi3", "CLIPPY_FEATURES" = { value = "--features=${CLIPPY_FEATURES}", condition = { env_set = ["CLIPPY_FEATURES"] } } }
 command = "cargo"
 args = ["clippy", "@@split(PLATFORM_TARGET, )", "@@remove-empty(CLIPPY_FEATURES)", "--", "-D", "warnings"]
 

machine/Cargo.toml

@@ -16,12 +16,16 @@ edition = "2021"
 maintenance = { status = "experimental" }
 
 [features]
+default = []
 noserial = []
 # Enable JTAG debugging of kernel - enable jtag helpers and
 # block waiting for JTAG probe attach at the start of kernel main.
 jtag = []
 # Build for running under QEMU with semihosting, so various halt/reboot options would for example quit QEMU instead.
-qemu = []
+qemu = ["rpi3"]
+# Mutually exclusive features to choose a target board
+rpi3 = []
+rpi4 = []
 
 [dependencies]
 r0 = "1.0"

machine/src/arch/aarch64/boot.rs

@@ -44,6 +44,7 @@ macro_rules! entry {
 unsafe fn reset() -> ! {
     extern "C" {
         // Boundaries of the .bss section, provided by the linker script
+        // The type, `u64`, indicates that the memory is 8-byte aligned
         static mut __BSS_START: u64;
         static mut __BSS_END: u64;
     }

machine/src/arch/aarch64/jtag.rs

@@ -1,16 +1,17 @@
 //! JTAG helper functions.
 
-use cortex_a::asm;
+use {
+    core::ptr::{read_volatile, write_volatile},
+    cortex_a::asm,
+};
 
 #[no_mangle]
 static mut WAIT_FLAG: bool = true;
 
 /// Wait for debugger to attach.
 /// Then in gdb issue `> set var *(&WAIT_FLAG) = 0`
-/// from inside this function's frame to contiue running.
+/// from inside this function's frame to continue running.
 pub fn wait_debugger() {
-    use core::ptr::{read_volatile, write_volatile};
-
     while unsafe { read_volatile(&WAIT_FLAG) } {
         asm::nop();
     }

machine/src/devices/console.rs

@@ -89,7 +89,6 @@ impl Console {
         }
     }
 
-    #[inline(always)]
     fn current_ptr(&self) -> &dyn ConsoleOps {
         match &self.output {
             Output::None(i) => i,

machine/src/lib.rs

@@ -38,6 +38,7 @@ pub static CONSOLE: sync::NullLock<devices::Console> = sync::NullLock::new(devic
 
 /// The global allocator for DMA-able memory. That is, memory which is tagged
 /// non-cacheable in the page tables.
+#[allow(dead_code)]
 static DMA_ALLOCATOR: sync::NullLock<mm::BumpAllocator> =
     sync::NullLock::new(mm::BumpAllocator::new(
         // @todo Init this after we loaded boot memory map

machine/src/mm/bump_allocator.rs

@@ -55,6 +55,7 @@ unsafe impl Allocator for BumpAllocator {
 
 impl BumpAllocator {
     /// Create a named bump allocator between start and end addresses.
+    #[allow(dead_code)]
     pub const fn new(pool_start: usize, pool_end: usize, name: &'static str) -> Self {
         Self {
             next: Cell::new(pool_start),

nucleus/Cargo.toml

@@ -22,6 +22,9 @@ noserial = ["machine/noserial"]
 jtag = ["machine/jtag"]
 # Build for running under QEMU with semihosting, so various halt/reboot options would for example quit QEMU instead.
 qemu = ["machine/qemu"]
+# Mutually exclusive features to choose a target board
+rpi3 = ["machine/rpi3"]
+rpi4 = ["machine/rpi4"]
 
 [dependencies]
 machine = { path = "../machine" }

ocd/rpi3_target.cfg

@@ -1,6 +1,8 @@
 # Broadcom bcm2837 on Raspberry Pi 3 as JTAG target
 # From https://www.suse.com/c/debugging-raspberry-pi-3-with-jtag/
 
+echo "Booting JTAG for Raspberry Pi 3"
+
 if { [info exists CHIPNAME] } {
     set _CHIPNAME $CHIPNAME
 } else {

ocd/rpi4_target.cfg

@@ -2,6 +2,8 @@
 # From https://gist.github.com/tnishinaga/46a3380e1f47f5e892bbb74e55b3cf3e
 # See also https://xihan94.gitbook.io/raspberry-pi/raspberry-pi-4-bringup
 
+echo "Booting JTAG for Raspberry Pi 4"
+
 if { [info exists CHIPNAME] } {
     set _CHIPNAME $CHIPNAME
 } else {