Rust Raspberry Pi OS Tutorials

This tutorial introduces hardware timer abstractions and their implementation for the ARM architectural timer in _arch/aarch64.

Key improvements include:

• UART Timestamps: Annotating UART prints with precise timestamps.
• Improved GPIO Accuracy: Replacing cycle-based delays in the GPIO device driver with timer-based delays to increase accuracy.
• Logging: Addition of a warn!() macro for warning-level logs.

This tutorial implements a custom integrated testing framework for a #![no_std] Rust kernel. Because the standard library is unavailable, the native Rust #[test] attribute and cargo test cannot be used directly. Instead, the project utilizes Rust's unstable custom_test_frameworks feature to enable three types of testing:

1. Unit Tests: Small, isolated tests using the #[test_case] attribute.
2. Integration Tests: Self-contained tests located in the $CRATE/tests/ directory.
3. Console I/O Tests: Integration tests that validate kernel behavior by sending strings/characters to the console (via UART) and verifying the responses.

All testing is performed using QEMU rather than real hardware to facilitate automation.

This tutorial focuses on moving the kernel from its current load address (0x8_0000) to the most significant area of the virtual memory space (ideally between 0xffff_0000_0000_0000 and 0xffff_ffff_ffff_ffff).

Instead of computing translation tables dynamically during the boot process, this approach involves:

1. Precomputing the kernel's translation tables immediately after kernel compilation.
2. Patching these tables into the kernel binary ahead of time.

While the current implementation still uses identity-mapping for the kernel binary, this setup provides the infrastructure required to map the kernel to a high virtual address in future steps.

Unlike architectures that use an array of function pointers, AArch64 uses the VBAR_EL1 (Vector Base Address Register) to point to a memory location containing actual code for the 16 handlers.

Requirements for the Vector Table:

• Structure: Handlers are placed back-to-back at specific offsets defined by the architecture.
• Handler Size: Each handler entry in the table has a maximum space of 0x80 (128) bytes. To handle complex logic or context saving, handlers should immediately branch off to other functions.
• Alignment: The Vector Base Address must be aligned to 0x800 (2048) bytes.

In the AArch64 architecture, exceptions are categorized into four distinct types based on how they are triggered:

• Synchronous: Triggered directly by the execution of a specific CPU instruction (e.g., a data abort like a page fault or a system call).
• Interrupt Request (IRQ): Asynchronous exceptions triggered by external hardware devices (e.g., a timer) asserting a physical interrupt line.
• Fast Interrupt Request (FIQ): High-priority asynchronous interrupts designed for super-fast processing. In this tutorial, FIQs are treated as dummy handlers that halt the CPU.
• System Error (SError): Asynchronous exceptions used to signal fatal system errors, such as a transaction timeout on the SoC interconnect. These are implementation-specific to the SoC vendor.

The UART Chainloader is a mechanism to load a kernel binary into RAM via a serial (UART) interface. The process follows these steps:

1. Request: The chainloader sends a specific sequence (the character 0x03 repeated 3 times) to signal it is ready for a payload.
2. Size Transfer: The loader reads 4 bytes from the UART to determine the size of the incoming binary.
3. Payload Transfer: The loader reads the binary byte-by-byte from the UART and writes it to the memory address defined by board_default_load_addr() (typically 0x80000).
4. Execution: Once the transfer is complete, the loader performs a jump to the start of the loaded binary.

This allows for updating or booting kernels without needing an SD card or external storage, provided a serial connection is available.

In this tutorial, the boot.s assembly file is extended to bridge the gap between hardware startup and Rust execution. The initialization sequence follows these steps:

1. Core Setup: For all cores except core 0, specific initialization is performed.
2. DRAM Initialization: The .bss section is zeroed out to prepare DRAM.
3. Stack Configuration: The stack pointer is configured to allow function calls.
4. Rust Handover: The assembly code jumps to _start_rust() (defined in arch/__arch_name__/cpu/boot.rs).
5. Rust Entry: _start_rust() calls kernel_init(), which in this tutorial simply calls panic!() to pause execution.

To see this initialization in action, run the QEMU emulator:

make qemu

The higher-half kernel memory layout follows this structure:

1. Kernel Code/Data: Starts at __kernel_virt_start_addr.
2. MMIO Remap: Follows the kernel sections.
3. Guard Page: An unmapped page to catch overflows.
4. Boot Core Stack: Located at the bottom of the high-address range, growing towards higher addresses (or as defined by the stack pointer setup).

Note: The stack is placed such that it grows from __boot_core_stack_start towards __boot_core_stack_end_exclusive.