feat(bsp): WIP - Initial port to Raspberry Pi 5

[devansh-lodha]

Description

This Draft Pull Request introduces initial, work-in-progress support for the Raspberry Pi 5 to the tutorial series. The goal is to eventually provide full compatibility for the Pi 5, allowing a new generation of hardware to be used for these excellent tutorials.

This initial submission ports the codebase from Tutorial 9 to Tutorial 12, establishing the foundational Board Support Package (BSP) and the necessary development infrastructure.

Current Status & Key Changes:

1. Working Kernel up to Tutorial 11: The kernel successfully boots and runs on Raspberry Pi 5 hardware. Key features are confirmed working:

   • Privilege level transition from EL2 to EL1.
   • Full MMU setup with an identity map.
   • Working UART console via the new RP1 I/O controller.
   • Basic exception handling for synchronous exceptions (demonstrated with page faults).

2. New Raspberry Pi 5 BSP:

   • A new bsp_rpi5 feature and corresponding bsp/raspberrypi5 module have been created.
   • Includes a new GPIO driver (bsp/device_driver/rp1_gpio.rs) that correctly handles the Pi 5's two-step PADS and IO_BANK configuration.
   • Memory maps have been updated to reflect the RP1 peripheral addresses behind the PCIe bus.

3. JTAG Debugging Workflow:

   • The port is based on a professional JTAG/GDB debugging workflow, which is more powerful for low-level development than the tutorial's original chainloader (minipush).
   • To support this, I have added two top-level directories that follow the repository's existing structure:
     • X2_pi5_jtag_halt_stub: A self-contained project to build the halt_stub.img needed on the SD card for JTAG debugging. This is analogous to the X1_JTAG_boot project.
     • debug/pi5: Contains the openocd and gdb configuration files specific to the Raspberry Pi 5 and the official Debug Probe.
   • The Makefile for the Pi 5 target is adapted to use this new infrastructure.
   • So essentially, the SD Card will only have the halt_stub.img renamed to kernel8.img along with all the firmware files. Currently putting only enable_jtag_gpio=1 and pciex4_reset=0 in the config.txt works for me.
   • This allows for a quick workflow where you only need to power cycle the Pi5 and load the new image without having to flash the SD card.

4. Handling of Tutorial 12 (Integrated Testing):

   • Due to the current lack of a QEMU machine type for the Raspberry Pi 5, the automated tests cannot be run in emulation.
   • However, the full structural refactoring of Tutorial 12 (workspace, lib.rs, custom test frameworks) has been implemented.
   • For the BSP=rpi5 target, the Makefile has been configured to use cargo test --no-run. This compiles all tests to ensure they are valid and the infrastructure is correct, but skips the execution step. But these can be executed manually by loading onto the hardware via gdb.
   • This approach ensures structural alignment with the main repository while acknowledging the current tooling limitations. Verification for the Pi 5 is performed manually on hardware via GDB.

Purpose of this Draft PR:

This PR is opened early to seek feedback and start a discussion with the maintainers. The code is functional, but I know that documentation and other aspects are not yet complete. My main goal is to ensure my approach aligns with the project's standards before I proceed further.

I am particularly looking for feedback on:

1. Overall Structure: Is the new bsp/raspberrypi5 structure and the top-level debug/ and X2_... directories an acceptable way to integrate Pi 5 support?
2. Testing Strategy: Is the "compile but don't run" approach for Pi 5 tests a reasonable solution given the QEMU limitations?
3. Documentation: What is the preferred way to add Pi 5-specific notes to the tutorial READMEs? Should I add conditional sections, or separate documents?
4. Future Work (Interrupts): I am now porting Tutorial 13. This will introduce significant new drivers for the BCM2712's GICv2 and the RP1's PCIe MSI-X interrupt chain (MIP). Given the complexity, would you prefer I continue on this single PR, or would a dedicated pi5-port feature branch within the main repository be more appropriate for ongoing collaboration?

Thank you for your time and for this fantastic learning resource. I look forward to your guidance.

Best regards, Devansh Lodha ([email protected])

Pre-commit steps

• [x] Tested on real HW (Raspberry Pi 5). QEMU testing is not applicable for the Pi 5 target.
• [ ] Ran ./contributor_setup.sh followed by ./devtool ready_for_publish
  • Note: I will run the full devtool suite to clean up formatting and licensing once the core structural feedback is received, to avoid unnecessary churn in early commits.

[jonathanpallant]

I wanted to note that drivers for the arm-gic and other bits of Arm IP already exist at: https://github.com/ArmFirmwareCrates. You may still want your own copies in this tree in the end, but no sense in starting completely from scratch.

[BartMassey]

Thanks much for submitting this! It looks like a lot of great work.

Unfortunately, you have caught us at a really bad time — a friend and I are working on completely rebuilding this tutorial to work well in a modern environment (with the blessing of the original author).

For now, we're really happy to try to figure out how to merge this once it's ready — just be aware that things may change substantially in the future, involving some potential rework.

[devansh-lodha]

Thanks much for submitting this! It looks like a lot of great work.

Unfortunately, you have caught us at a really bad time — a friend and I are working on completely rebuilding this tutorial to work well in a modern environment (with the blessing of the original author).

For now, we're really happy to try to figure out how to merge this once it's ready — just be aware that things may change substantially in the future, involving some potential rework.

Thanks so much for the quick and transparent response! It's great to hear the tutorials are getting a modernization refresh.

I'm learning a ton by working through these!

With that in mind, I'd be very happy to pivot and help with the new version if there's any way I can contribute.

I can absolutely continue porting the existing tutorials. This would create a complete, working Pi 5 reference on the current codebase, which might still be valuable as a standalone resource or to help inform the new port.

Looking forward to seeing the new tutorials when they're ready!