feat(debug): Add top-level JTAG assets for Pi 5

Adds the necessary infrastructure for a JTAG-based debugging workflow on the Raspberry Pi 5.

This includes a new 'debug/pi5' directory with OpenOCD and GDB configuration files, and a new 'X2_pi5_jtag_halt_stub' project that compiles a simple assembly stub to halt the CPU for debugging.

This lays the foundation for the Pi 5 BSP and debugging targets in the tutorial Makefiles.

Co-authored-by: Devansh Lodha <[email protected]>

Author: devansh-lodha

X2_pi5_jtag_halt_stub/Makefile

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+#
+# Copyright (c) 2025 Devansh Lodha <[email protected]>
+
+# This Makefile is designed to be called from the parent directory's
+# Docker environment, which provides the aarch64-elf toolchain.
+
+CROSS_COMPILE ?= aarch64-elf-
+OBJCOPY = $(CROSS_COMPILE)objcopy
+AS = $(CROSS_COMPILE)as
+LD = $(CROSS_COMPILE)ld
+
+IMG_NAME = halt_stub.img
+ELF_NAME = halt_stub.elf
+OBJ_NAME = start.o
+
+.PHONY: all clean
+
+all: $(IMG_NAME)
+
+$(IMG_NAME): $(ELF_NAME)
+	@echo "--- Building Halt Stub Image ---"
+	@$(OBJCOPY) -O binary $(ELF_NAME) $(IMG_NAME)
+
+$(ELF_NAME): $(OBJ_NAME)
+	@$(LD) -T linker.ld -o $(ELF_NAME) $(OBJ_NAME)
+
+$(OBJ_NAME): start.s
+	@$(AS) -o $(OBJ_NAME) start.s
+
+clean:
+	@rm -f $(IMG_NAME) $(ELF_NAME) $(OBJ_NAME)

X2_pi5_jtag_halt_stub/halt_stub.img

@@ -0,0 +1 @@
+_ ����

X2_pi5_jtag_halt_stub/linker.ld

@@ -0,0 +1,12 @@
+/*
+ * SPDX-License-Identifier: MIT OR Apache-2.0
+ *
+ * Copyright (c) 2025 Devansh Lodha <[email protected]>
+ */
+
+ENTRY(_start)
+SECTIONS
+{
+    . = 0x80000;
+    .text : { *(.text.boot) }
+}

X2_pi5_jtag_halt_stub/start.s

@@ -0,0 +1,11 @@
+/*
+ * SPDX-License-Identifier: MIT OR Apache-2.0
+ *
+ * Copyright (c) 2025 Devansh Lodha <[email protected]>
+ */
+
+.section ".text.boot"
+.global _start
+_start:
+    wfe // Wait for event (low-power idle)
+    b _start

debug/pi5/cmsis-dap.cfg

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+#
+# Copyright (c) 2025 Devansh Lodha <[email protected]>
+
+adapter driver cmsis-dap

debug/pi5/gdb-init.txt

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+#
+# Copyright (c) 2025 Devansh Lodha <[email protected]>
+
+# 1. Connect to the OpenOCD server.
+target remote localhost:3333
+
+# 2. Reset the Pi and halt it at the very beginning.
+monitor reset init
+
+# 3. Load your program's symbols and code into the Pi's RAM.
+load
+
+# 4. Set the Program Counter to the start of our code.
+set $pc = 0x80000

debug/pi5/raspberrypi5.cfg

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+#
+# Copyright (c) 2025 Devansh Lodha <[email protected]>
+
+transport select swd
+adapter speed 4000
+reset_config srst_push_pull srst_only
+set _CHIPNAME bcm2712
+set _DAP_TAPID 0x4ba00477
+set _CHIPCORES 4
+swd newdap $_CHIPNAME cpu -expected-id $_DAP_TAPID
+dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu
+set _DBGBASE {0x80010000 0x80110000 0x80210000 0x80310000}
+set _CTIBASE {0x80020000 0x80120000 0x80220000 0x80320000}
+for { set _core 0 } { $_core < $_CHIPCORES } { incr _core } {
+    set _CTINAME $_CHIPNAME.cti$_core
+    set _TARGETNAME $_CHIPNAME.cpu$_core
+    cti create $_CTINAME -dap $_CHIPNAME.dap -ap-num 0 -baseaddr [lindex $_CTIBASE $_core]
+    target create $_TARGETNAME aarch64 -dap $_CHIPNAME.dap -coreid $_core -dbgbase [lindex $_DBGBASE $_core] -cti $_CTINAME
+    $_TARGETNAME configure -event gdb-attach { halt }
+}
+targets $_CHIPNAME.cpu0
+init
+$_CHIPNAME.cpu0 configure -event reset-init { halt }