feat(bsp): Raspberry Pi 5 Support (PoC on Tutorial 19)

[devansh-lodha]

Description

This PR introduces support for the Raspberry Pi 5 (BCM2712). Unlike previous generations, the Pi 5 utilizes a disaggregated architecture (Cortex-A76 SoC connected via PCIe to the RP1 Southbridge), mandating a strict hierarchical driver initialization order.

I am aware (per feedback on my previous draft) that a major rebuild of the tutorial series is in progress.
I am submitting this PR primarily to establish the hardware support logic for the BCM2712/RP1.

Regardless of how the future tutorial structure looks, the hardware constraints (PCIe BAR mapping, MSI-X/MIP routing, edge-triggering) remain constant. This PR proves that this logic works and fits cleanly into a modular driver architecture. I hope this can serve as the "Reference Implementation" for Pi 5 support in the new version, or be merged now to unblock Pi 5 users in the interim.

To validate this architecture without introducing churn across all 20 tutorials, this is implemented as a Vertical Slice on Tutorial 19 (Kernel Heap). This tutorial was selected because it exercises the complete kernel stack (MMU, Dynamic Allocation, Interrupts), providing the strongest proof of correctness.

1. Architectural Implementation

I have adhered strictly to the repository's existing structure, avoiding the creation of a separate raspberrypi5 BSP folder in favor of #[cfg(feature = "bsp_rpi5")] gates.

• Boot Orchestration (driver.rs): Implemented a specialized boot sequence for Pi 5:

  1. PCIe Root Complex: Initialized first to enable the SCB (System Core Bus) access.
  2. Inbound Window (BAR2): Maps the PCIe address 0xFFFF_F000 to the CPU Physical Address 0x10_0013_0000 (MIP Doorbell). This allows the RP1 to trigger MSI-X interrupts.
  3. RP1 Southbridge: Discovered via ECAM; Bus Mastering enabled.
  4. Peripheral Drivers: UART and GPIO (located inside RP1) are initialized only after the bridge is active.

• Interrupt Subsystem:

  • Controller: Implemented BCM2712InterruptController which wraps the standard GICv2 driver. It handles the BCM2712-specific MIP (Machine Interrupt Peripheral) configuration required to route PCIe MSI-X traffic to GIC SPIs.
  • Edge Triggering: Extended GICv2 driver to support Edge-triggered interrupts (required for RP1 logic), whereas Pi 4 uses Level triggers.

2. Workflow & Tooling

The Pi 5 introduces the dedicated Raspberry Pi Debug Probe, necessitating a move away from the legacy UART-based chainloader workflow to a professional SWD (JTAG) workflow.

• Configuration: Added debug/pi5/ containing OpenOCD (CMSIS-DAP) and GDB initialization scripts.
• Halt Stub (X2_pi5_jtag_halt_stub): Added a standalone project (analogous to X1) that builds a minimal wfe loop binary.
• Makefile Targets:
  • make jtagboot BSP=rpi5: Builds the Halt Stub and instructs the user to copy it to the SD card.
  • make openocd BSP=rpi5: Connects via Debug Probe.
  • make gdb BSP=rpi5: Loads the kernel ELF directly into RAM via DMA and begins execution.

Pre-commit steps

• Tested on QEMU and real HW Rasperry Pi.
  • RPi 5 (HW): Verified Boot, UART Output, Heap Allocation, and IRQ echoing.
  • RPi 3 (HW/Regression): Verified make test pass.
  • RPi 4 (Regression): Verified compilation via clippy.
• Ran ./contributor_setup.sh followed by ./devtool ready_for_publish
  • Note: I ran the standard suite to ensure zero regressions on existing boards. I did not modify devtool to include rpi5 in the global loop, as this PR only targets Tutorial 19.
  • Verification: Manually ran BSP=rpi5 make clippy and cargo fmt inside 19_kernel_heap.

Questions for Maintainers

1. Documentation Strategy: This PR currently contains the code infrastructure. How would you prefer I handle the READMEs? Should I introduce a conditional section in 19_kernel_heap/README.md explaining the Pi 5 hardware differences, or does this merit a separate document?
2. Merge Strategy: If this architectural approach (Vertical Slice) is accepted, I am prepared to backport the Makefile and BSP primitives to Tutorials 01-18 in follow-up PRs. I did not port Tutorial 20 since it looks like the original author left it open for further modifications and hence I've considered up-to Tutorial 19 as "complete" as per the original author.

[BartMassey]

@devansh-lodha Thanks so much for this! It looks like a huge pile of work, done well.

I'm not sure what the best overall merge strategy is. For now, I'd honestly suggest you hold until we have a stable version of https://github.com/FlamingosProject/flamingos-preview that we believe in; probably a couple weeks. PM me somewhere and we will invite you to our weekly meeting where we're working on that if you like 😀 .

The Raspberry Pi Debug Probe solution looks great; thanks for working that out. It looks like it should work with Pi 4 as well?

Let us think a bit about the way forward. I really don't want you to have to backport your thing here, and then you or we do it again in a few weeks.

Documentation-wise, we are keeping the non-patch portion of the READMEs. I would suggest you wait on documenting until backporting, and then stick the relevant in stuff in the README where it is introduced.

[devansh-lodha]

Understood. I will hold off on backporting and documentation updates to avoid redundant work given the transition to Flamingos. I am happy to coordinate on the new architecture and will definitely reach out to discuss more!

Regarding Debug Probe on Pi 4:
Yes, the Debug Probe should work with the Pi 4, but the physical interface differs since Pi 5 has a dedicated JST-SH connector exposing UART and SWD directly and Pi 4 would require manually wiring GPIO headers (GPIO 22-27) configured in ALT4 mode to the Debug Probe's D-port. I do not currently have physical Pi 4 to validate this though.

Regarding CI Failures:
The current CI failures are infrastructure-related (failure to install cargo-binutils on the nightly runner), not code regressions! I have manually verified the builds and tests succeeds for all targets (rpi3, rpi4, rpi5) locally.

Thank you!
Devansh