feat(10): Enable MMU support for Raspberry Pi 5

Enables virtual memory for the Raspberry Pi 5 target by implementing the required BSP-specific memory layout.

This resolves a silent hang on boot that occurs immediately after the MMU is enabled. The root cause was a Translation Fault when the kernel tried to access peripheral drivers in high memory (0x1f...). The initial 4 GiB virtual address space was too small, so no page table entries were being generated for the RP1's MMIO region.

This fix includes:
1.  In 'memory.rs', the virtual address space is expanded to 128 GiB, the smallest power-of-two that encompasses the RP1's MMIO addresses.
2.  A new 'memory/mmu.rs' file is added to define the 'KernelVirtualLayout'. This layout correctly identity-maps the RP1 peripheral range as Device memory and ports the tutorial's educational UART remapping feature.
3.  The 'kernel.ld' linker script is updated to align the code section to a 64 KiB page boundary and export the symbols required by the MMU layout code.

Author: devansh-lodha

10_virtual_mem_part1_identity_mapping/src/bsp/raspberrypi5/kernel.ld

@@ -0,0 +1,88 @@
+/* SPDX-License-Identifier: MIT OR Apache-2.0
+ *
+ * Copyright (c) 2018-2025 Andre Richter <[email protected]>
+ */
+
+PAGE_SIZE = 64K;
+PAGE_MASK = PAGE_SIZE - 1;
+
+__rpi_phys_dram_start_addr = 0;
+
+/* The physical address at which the the kernel binary will be loaded by the Raspberry's firmware */
+__rpi_phys_binary_load_addr = 0x80000;
+
+
+ENTRY(__rpi_phys_binary_load_addr)
+
+/* Flags:
+ *     4 == R
+ *     5 == RX
+ *     6 == RW
+ *
+ * Segments are marked PT_LOAD below so that the ELF file provides virtual and physical addresses.
+ * It doesn't mean all of them need actually be loaded.
+ */
+PHDRS
+{
+    segment_boot_core_stack PT_LOAD FLAGS(6);
+    segment_code            PT_LOAD FLAGS(5);
+    segment_data            PT_LOAD FLAGS(6);
+}
+
+SECTIONS
+{
+    . =  __rpi_phys_dram_start_addr;
+
+    /***********************************************************************************************
+    * Boot Core Stack
+    ***********************************************************************************************/
+    .boot_core_stack (NOLOAD) :
+    {
+                                             /*   ^             */
+                                             /*   | stack       */
+        . += __rpi_phys_binary_load_addr;    /*   | growth      */
+                                             /*   | direction   */
+        __boot_core_stack_end_exclusive = .; /*   |             */
+    } :segment_boot_core_stack
+
+    ASSERT((. & PAGE_MASK) == 0, "End of boot core stack is not page aligned")
+
+    /***********************************************************************************************
+    * Code + RO Data + Global Offset Table
+    ***********************************************************************************************/
+    __code_start = .;
+    .text :
+    {
+        KEEP(*(.text._start))
+        *(.text._start_arguments) /* Constants (or statics in Rust speak) read by _start(). */
+        *(.text._start_rust)      /* The Rust entry point */
+        *(.text*)                 /* Everything else */
+    } :segment_code
+
+    .rodata : ALIGN(8) { *(.rodata*) } :segment_code
+
+    . = ALIGN(PAGE_SIZE);
+    __code_end_exclusive = .;
+
+    /***********************************************************************************************
+    * Data + BSS
+    ***********************************************************************************************/
+    .data : { *(.data*) } :segment_data
+
+    /* Section is zeroed in pairs of u64. Align start and end to 16 bytes */
+    .bss (NOLOAD) : ALIGN(16)
+    {
+        __bss_start = .;
+        *(.bss*);
+        . = ALIGN(16);
+        __bss_end_exclusive = .;
+    } :segment_data
+
+    /***********************************************************************************************
+    * Misc
+    ***********************************************************************************************/
+    .got : { *(.got*) }
+    ASSERT(SIZEOF(.got) == 0, "Relocation support not expected")
+
+    /DISCARD/ : { *(.comment*) }
+}

10_virtual_mem_part1_identity_mapping/src/bsp/raspberrypi5/memory.rs

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2025 Andre Richter <[email protected]>
+// Copyright (c) 2025 Devansh Lodha <[email protected]>
+
+//! BSP Memory Management for the Raspberry Pi 5.
+//!
+//! The physical memory layout.
+//!
+//! The Raspberry's firmware copies the kernel binary to 0x8_0000. The preceding region will be used
+//! as the boot core's stack.
+
+pub mod mmu;
+
+use core::cell::UnsafeCell;
+
+//--------------------------------------------------------------------------------------------------
+// Private Definitions
+//--------------------------------------------------------------------------------------------------
+
+// Symbols from the linker script.
+extern "Rust" {
+    static __code_start: UnsafeCell<()>;
+    static __code_end_exclusive: UnsafeCell<()>;
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// The board's physical memory map.
+#[rustfmt::skip]
+pub(super) mod map {
+    /// The inclusive end address of the memory map.
+    ///
+    /// End address + 1 must be a power of two.
+    ///
+    /// We define the address space to be 128 GiB. This is the smallest power of two that
+    /// encapsulates the RP1's MMIO addresses.
+    pub const END_INCLUSIVE: usize = (128 * 1024 * 1024 * 1024) - 1;
+    pub const RP1_PCI_ECAM_BASE: usize = 0x1f00000000;
+
+    /// Physical devices.
+    pub mod mmio {
+        use super::*;
+
+        // See `RP1 Peripherals` datasheet, table 5 and 22.
+        pub const START:            usize = RP1_PCI_ECAM_BASE;
+        pub const GPIO_START:       usize = START + 0xd0000;
+        pub const PADS_BANK0_START: usize = START + 0xf0000;
+        pub const PL011_UART_START: usize = START + 0x30000;
+
+        // Define an end for the MMIO region. The highest peripheral address in the datasheet
+        // is around 0x1f00400000, so we'll use a slightly larger, rounded value.
+        pub const END_INCLUSIVE:    usize = 0x1f0fffffff;
+    }
+}
+
+//--------------------------------------------------------------------------------------------------
+// Private Code
+//--------------------------------------------------------------------------------------------------
+
+/// Start page address of the code segment.
+///
+/// # Safety
+///
+/// - Value is provided by the linker script and must be trusted as-is.
+#[inline(always)]
+fn code_start() -> usize {
+    unsafe { __code_start.get() as usize }
+}
+
+/// Exclusive end page address of the code segment.
+/// # Safety
+///
+/// - Value is provided by the linker script and must be trusted as-is.
+#[inline(always)]
+fn code_end_exclusive() -> usize {
+    unsafe { __code_end_exclusive.get() as usize }
+}

10_virtual_mem_part1_identity_mapping/src/bsp/raspberrypi5/memory/mmu.rs

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2025 Andre Richter <[email protected]>
+// Copyright (c) 2025 Devansh Lodha <[email protected]>
+
+//! BSP Memory Management Unit for the Raspberry Pi 5.
+
+use super::map as memory_map;
+use crate::memory::mmu::*;
+use core::ops::RangeInclusive;
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// The kernel's address space defined by this BSP.
+pub type KernelAddrSpace = AddressSpace<{ memory_map::END_INCLUSIVE + 1 }>;
+
+const NUM_MEM_RANGES: usize = 3;
+
+/// The virtual memory layout.
+///
+/// The layout must contain only special ranges, aka anything that is _not_ normal cacheable DRAM.
+/// It is agnostic of the paging granularity that the architecture's MMU will use.
+pub static LAYOUT: KernelVirtualLayout<NUM_MEM_RANGES> = KernelVirtualLayout::new(
+    memory_map::END_INCLUSIVE,
+    [
+        TranslationDescriptor {
+            name: "Kernel code and RO data",
+            virtual_range: code_range_inclusive,
+            physical_range_translation: Translation::Identity,
+            attribute_fields: AttributeFields {
+                mem_attributes: MemAttributes::CacheableDRAM,
+                acc_perms: AccessPermissions::ReadOnly,
+                execute_never: false,
+            },
+        },
+        TranslationDescriptor {
+            name: "Remapped Device MMIO (UART)",
+            virtual_range: remapped_mmio_range_inclusive,
+            // The chosen virtual address for the remapped UART is 0x1FFF_1000.
+            // The virtual range starts at 0x1FFF_0000.
+            // Therefore, the offset that the physical memory block must be based at is:
+            //      PL011_UART_START - 0x1000
+            physical_range_translation: Translation::Offset(
+                memory_map::mmio::PL011_UART_START - 0x1000,
+            ),
+            attribute_fields: AttributeFields {
+                mem_attributes: MemAttributes::Device,
+                acc_perms: AccessPermissions::ReadWrite,
+                execute_never: true,
+            },
+        },
+        TranslationDescriptor {
+            name: "Device MMIO",
+            virtual_range: mmio_range_inclusive,
+            physical_range_translation: Translation::Identity,
+            attribute_fields: AttributeFields {
+                mem_attributes: MemAttributes::Device,
+                acc_perms: AccessPermissions::ReadWrite,
+                execute_never: true,
+            },
+        },
+    ],
+);
+
+//--------------------------------------------------------------------------------------------------
+// Private Code
+//--------------------------------------------------------------------------------------------------
+
+fn code_range_inclusive() -> RangeInclusive<usize> {
+    // Notice the subtraction to turn the exclusive end into an inclusive end.
+    #[allow(clippy::range_minus_one)]
+    RangeInclusive::new(super::code_start(), super::code_end_exclusive() - 1)
+}
+
+fn remapped_mmio_range_inclusive() -> RangeInclusive<usize> {
+    // The last 64 KiB slot in the first 512 MiB. Chosen for educational purposes
+    // to match the original tutorial's concept.
+    RangeInclusive::new(0x1FFF_0000, 0x1FFF_FFFF)
+}
+
+fn mmio_range_inclusive() -> RangeInclusive<usize> {
+    RangeInclusive::new(memory_map::mmio::START, memory_map::mmio::END_INCLUSIVE)
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// Return a reference to the virtual memory layout.
+pub fn virt_mem_layout() -> &'static KernelVirtualLayout<NUM_MEM_RANGES> {
+    &LAYOUT
+}