build(09): Adapt Makefile for Pi 5 and hybrid debugging

Updates the Makefile in '09_privilege_level' to support the new Raspberry Pi 5 target and its JTAG-based workflow.

- Adds a 'bsp_rpi5' configuration block, setting the CPU to cortex-a76.
- Adds a new 'sd_image' target that builds the halt stub.
- Implements OS-aware logic to use local 'openocd' and 'gdb' on macOS while retaining the Docker-based commands for Linux.

Author: devansh-lodha

09_privilege_level/Makefile

@@ -1,6 +1,7 @@
 ## SPDX-License-Identifier: MIT OR Apache-2.0
 ##
-## Copyright (c) 2018-2023 Andre Richter <[email protected]>
+## Copyright (c) 2018-2025 Andre Richter <[email protected]>
+## Copyright (c) 2025 Devansh Lodha <[email protected]>
 
 include ../common/docker.mk
 include ../common/format.mk
@@ -49,6 +50,20 @@ else ifeq ($(BSP),rpi4)
     JTAG_BOOT_IMAGE   = ../X1_JTAG_boot/jtag_boot_rpi4.img
     LD_SCRIPT_PATH    = $(shell pwd)/src/bsp/raspberrypi
     RUSTC_MISC_ARGS   = -C target-cpu=cortex-a72
+else ifeq ($(BSP),rpi5)
+    TARGET            = aarch64-unknown-none-softfloat
+    KERNEL_BIN        = kernel8.img
+    QEMU_BINARY       = qemu-system-aarch64
+    QEMU_MACHINE_TYPE =
+    QEMU_RELEASE_ARGS = -serial stdio -display none
+    OBJDUMP_BINARY    = aarch64-none-elf-objdump
+    NM_BINARY         = aarch64-none-elf-nm
+    READELF_BINARY    = aarch64-none-elf-readelf
+    GDB_BINARY        = aarch64-elf-gdb
+    OPENOCD_ARG       = -f ../debug/pi5/cmsis-dap.cfg -f ../debug/pi5/raspberrypi5.cfg
+    GDB_INIT_FILE     = ../debug/pi5/gdb-init.txt
+    LD_SCRIPT_PATH    = $(shell pwd)/src/bsp/raspberrypi5
+    RUSTC_MISC_ARGS   = -C target-cpu=cortex-a76
 endif
 
 # Export for build.rs.
@@ -66,7 +81,7 @@ LAST_BUILD_CONFIG    = target/$(BSP).build_config
 KERNEL_ELF      = target/$(TARGET)/release/kernel
 # This parses cargo's dep-info file.
 # https://doc.rust-lang.org/cargo/guide/build-cache.html#dep-info-files
-KERNEL_ELF_DEPS = $(filter-out %: ,$(file < $(KERNEL_ELF).d)) $(KERNEL_MANIFEST) $(LAST_BUILD_CONFIG)
+KERNEL_ELF_DEPS = $(filter-out %: ,$(shell cat $(KERNEL_ELF).d 2>/dev/null)) $(KERNEL_MANIFEST) $(LAST_BUILD_CONFIG)
 
 
 
@@ -86,10 +101,10 @@ COMPILER_ARGS = --target=$(TARGET) \
     $(FEATURES)                    \
     --release
 
-RUSTC_CMD   = cargo rustc $(COMPILER_ARGS)
-DOC_CMD     = cargo doc $(COMPILER_ARGS)
-CLIPPY_CMD  = cargo clippy $(COMPILER_ARGS)
-OBJCOPY_CMD = rust-objcopy \
+BASE_RUSTC_CMD   = cargo rustc $(COMPILER_ARGS)
+BASE_DOC_CMD     = cargo doc $(COMPILER_ARGS)
+BASE_CLIPPY_CMD  = cargo clippy $(COMPILER_ARGS)
+BASE_OBJCOPY_CMD = rust-objcopy \
     --strip-all            \
     -O binary
 
@@ -98,38 +113,38 @@ EXEC_TEST_DISPATCH = ruby ../common/tests/dispatch.rb
 EXEC_MINIPUSH      = ruby ../common/serial/minipush.rb
 
 ##------------------------------------------------------------------------------
-## Dockerization
+## OS-dependent commands and Dockerization
 ##------------------------------------------------------------------------------
-DOCKER_CMD            = docker run -t --rm -v $(shell pwd):/work/tutorial -w /work/tutorial
-DOCKER_CMD_INTERACT   = $(DOCKER_CMD) -i
-DOCKER_ARG_DIR_COMMON = -v $(shell pwd)/../common:/work/common
-DOCKER_ARG_DIR_JTAG   = -v $(shell pwd)/../X1_JTAG_boot:/work/X1_JTAG_boot
-DOCKER_ARG_DEV        = --privileged -v /dev:/dev
-DOCKER_ARG_NET        = --network host
-
-# DOCKER_IMAGE defined in include file (see top of this file).
-DOCKER_QEMU  = $(DOCKER_CMD_INTERACT) $(DOCKER_IMAGE)
-DOCKER_TOOLS = $(DOCKER_CMD) $(DOCKER_IMAGE)
-DOCKER_TEST  = $(DOCKER_CMD) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)
-DOCKER_GDB   = $(DOCKER_CMD_INTERACT) $(DOCKER_ARG_NET) $(DOCKER_IMAGE)
-
-# Dockerize commands, which require USB device passthrough, only on Linux.
-ifeq ($(shell uname -s),Linux)
-    DOCKER_CMD_DEV = $(DOCKER_CMD_INTERACT) $(DOCKER_ARG_DEV)
+DOCKER_CMD_PREFIX   = docker run -t --rm -v $(shell pwd):/work/tutorial -w /work/tutorial
+DOCKER_CMD_INTERACT = $(DOCKER_CMD_PREFIX) -i
 
-    DOCKER_CHAINBOOT = $(DOCKER_CMD_DEV) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)
-    DOCKER_JTAGBOOT  = $(DOCKER_CMD_DEV) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_ARG_DIR_JTAG) $(DOCKER_IMAGE)
-    DOCKER_OPENOCD   = $(DOCKER_CMD_DEV) $(DOCKER_ARG_NET) $(DOCKER_IMAGE)
-else
-    DOCKER_OPENOCD   = echo "Not yet supported on non-Linux systems."; \#
-endif
+# DOCKER_IMAGE is defined in ../common/docker.mk
+DOCKER_TOOLS_WRAPPER = $(DOCKER_CMD_PREFIX) $(DOCKER_IMAGE)
 
+ifeq ($(shell uname -s),Linux)
+    OPENOCD_CMD = $(DOCKER_CMD_INTERACT) --privileged -v /dev:/dev --network host -v $(shell pwd)/../debug:/work/debug $(DOCKER_IMAGE) openocd
+    GDB_CMD     = $(DOCKER_CMD_INTERACT) --network host -v $(shell pwd)/../debug:/work/debug $(DOCKER_IMAGE) gdb-multiarch
+    STUB_MAKE_CMD = $(DOCKER_TOOLS_WRAPPER) -v $(shell pwd)/../X2_pi5_jtag_halt_stub:/work/X2_pi5_jtag_halt_stub $(MAKE)
+else ifeq ($(shell uname -s),Darwin) # macOS - Use local tools for hardware interaction
+    OPENOCD_CMD = openocd # Assumes OpenOCD is installed locally
+    GDB_CMD     = $(GDB_BINARY) # Assumes aarch64-elf-gdb is in PATH
+    STUB_MAKE_CMD = $(DOCKER_TOOLS_WRAPPER) -v $(shell pwd)/../X2_pi5_jtag_halt_stub:/work/X2_pi5_jtag_halt_stub $(MAKE)
+else # Fallback for other OSes
+    OPENOCD_CMD = echo "OpenOCD on this OS is not supported by this Makefile."; false
+    GDB_CMD     = echo "GDB on this OS is not supported by this Makefile."; false
+endif
 
+# These commands are always local, as per the repository's design
+RUSTC_CMD   = $(BASE_RUSTC_CMD)
+DOC_CMD     = $(BASE_DOC_CMD)
+CLIPPY_CMD  = $(BASE_CLIPPY_CMD)
+OBJCOPY_CMD = $(BASE_OBJCOPY_CMD)
+CLEAN_CMD   = cargo clean
 
 ##--------------------------------------------------------------------------------------------------
 ## Targets
 ##--------------------------------------------------------------------------------------------------
-.PHONY: all doc qemu chainboot clippy clean readelf objdump nm check
+.PHONY: all doc qemu clippy clean readelf objdump nm check
 
 all: $(KERNEL_BIN)
 
@@ -178,16 +193,10 @@ else # QEMU is supported.
 
 qemu: $(KERNEL_BIN)
 	$(call color_header, "Launching QEMU")
-	@$(DOCKER_QEMU) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)
+	@$(DOCKER_CMD_INTERACT) $(DOCKER_IMAGE) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)
 
 endif
 
-##------------------------------------------------------------------------------
-## Push the kernel to the real HW target
-##------------------------------------------------------------------------------
-chainboot: $(KERNEL_BIN)
-	@$(DOCKER_CHAINBOOT) $(EXEC_MINIPUSH) $(DEV_SERIAL) $(KERNEL_BIN)
-
 ##------------------------------------------------------------------------------
 ## Run clippy
 ##------------------------------------------------------------------------------
@@ -198,21 +207,22 @@ clippy:
 ## Clean
 ##------------------------------------------------------------------------------
 clean:
-	rm -rf target $(KERNEL_BIN)
+	@$(CLEAN_CMD)
+	@rm -f kernel8.img
 
 ##------------------------------------------------------------------------------
 ## Run readelf
 ##------------------------------------------------------------------------------
 readelf: $(KERNEL_ELF)
 	$(call color_header, "Launching readelf")
-	@$(DOCKER_TOOLS) $(READELF_BINARY) --headers $(KERNEL_ELF)
+	@$(DOCKER_TOOLS_WRAPPER) $(READELF_BINARY) --headers $(KERNEL_ELF)
 
 ##------------------------------------------------------------------------------
 ## Run objdump
 ##------------------------------------------------------------------------------
 objdump: $(KERNEL_ELF)
 	$(call color_header, "Launching objdump")
-	@$(DOCKER_TOOLS) $(OBJDUMP_BINARY) --disassemble --demangle \
+	@$(DOCKER_TOOLS_WRAPPER) $(OBJDUMP_BINARY) --disassemble --demangle \
                 --section .text   \
                 --section .rodata \
                 $(KERNEL_ELF) | rustfilt
@@ -222,27 +232,31 @@ objdump: $(KERNEL_ELF)
 ##------------------------------------------------------------------------------
 nm: $(KERNEL_ELF)
 	$(call color_header, "Launching nm")
-	@$(DOCKER_TOOLS) $(NM_BINARY) --demangle --print-size $(KERNEL_ELF) | sort | rustfilt
+	@$(DOCKER_TOOLS_WRAPPER) $(NM_BINARY) --demangle --print-size $(KERNEL_ELF) | sort | rustfilt
 
 
 
 ##--------------------------------------------------------------------------------------------------
 ## Debugging targets
 ##--------------------------------------------------------------------------------------------------
-.PHONY: jtagboot openocd gdb gdb-opt0
+.PHONY: sd_image openocd gdb gdb-opt0
 
 ##------------------------------------------------------------------------------
-## Push the JTAG boot image to the real HW target
+## Build the JTAG halt stub and copy it for SD card use
 ##------------------------------------------------------------------------------
-jtagboot:
-	@$(DOCKER_JTAGBOOT) $(EXEC_MINIPUSH) $(DEV_SERIAL) $(JTAG_BOOT_IMAGE)
+sd_image:
+	$(call color_header, "Building JTAG halt stub for SD card")
+	@$(STUB_MAKE_CMD) -C ../X2_pi5_jtag_halt_stub
+	@cp ../X2_pi5_jtag_halt_stub/halt_stub.img ./kernel8.img
+	$(call color_progress_prefix, "Name")
+	@echo "kernel8.img (Halt Stub)"
 
 ##------------------------------------------------------------------------------
 ## Start OpenOCD session
 ##------------------------------------------------------------------------------
 openocd:
 	$(call color_header, "Launching OpenOCD")
-	@$(DOCKER_OPENOCD) openocd $(OPENOCD_ARG)
+	@$(OPENOCD_CMD) $(OPENOCD_ARG)
 
 ##------------------------------------------------------------------------------
 ## Start GDB session
@@ -251,7 +265,11 @@ gdb: RUSTC_MISC_ARGS += -C debuginfo=2
 gdb-opt0: RUSTC_MISC_ARGS += -C debuginfo=2 -C opt-level=0
 gdb gdb-opt0: $(KERNEL_ELF)
 	$(call color_header, "Launching GDB")
-	@$(DOCKER_GDB) gdb-multiarch -q $(KERNEL_ELF)
+ifeq ($(BSP),rpi5)
+	@$(GDB_CMD) -q -x $(GDB_INIT_FILE) $(KERNEL_ELF)
+else
+	@$(GDB_CMD) -q $(KERNEL_ELF)
+endif