# rust-embedded/rust-raspberrypi-os-tutorials architecture

> Architecture diagram of the GitHub repository rust-embedded/rust-raspberrypi-os-tutorials, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rust-embedded/rust-raspberrypi-os-tutorials
- Repository: https://github.com/rust-embedded/rust-raspberrypi-os-tutorials

## Overview

This project is an educational repository providing a step‐by‐step series of tutorials for developing a monolithic operating system kernel in Rust on the Raspberry Pi (both RPi3 and RPi4). The project is divided into multiple “tutorial” directories (named with numeric prefixes such as “01_wait_forever”, “02_runtime_init”, etc.), each of which builds on the previous one by gradually adding system functionality—from the early boot code and runtime initialization to device drivers, exception handling, virtual memory, and debugging support.

##### Main Components
- Boot & CPU Initialization:
– Highlight the boot code (found in the _arch directories; e.g., boot.s, boot.rs) and early CPU initialization routines.
– Show the execution flow starting from the bootloader to the kernel’s main entry point.
- Board Support Package (BSP):
– Emphasize the BSP layers, especially for the Raspberry Pi. These appear across multiple tutorials (“bsp/raspberrypi.rs” and folders under bsp) and encapsulate board-specific initialization, memory layout (sometimes via linker scripts like kernel.ld), device configuration, and peripheral mapping.
- Kernel Core & Runtime:
– Include core kernel modules (for example, panic handlers, synchronization primitives, prints, and common CPU routines).
– Show how these runtime components evolve across the tutorials.
- Device Drivers:
– Identify components like the GPIO and UART drivers (e.g., directories like “05_drivers_gpio_uart”, “X1_JTAG_boot”), that manage hardware I/O.
– Represent the interactions between these drivers and the underlying hardware.
- Memory Management & Virtual Memory:
– Outline modules for virtual memory mapping and MMU configuration (evident in directories such as “10_virtual_mem_part1_identity_mapping”, “14_virtual_mem_part2_mmio_remap”, etc.).
– Include key modules like “mmu.rs”, “translation_table.rs”, and supporting memory allocation modules.
- Exception & Interrupt Handling:
– Include exception handling components (directories “09_privilege_level”, “11_exceptions_part1_groundwork”, “13_exceptions_part2_peripheral_IRQs”, etc.).
– Represent the flow for synchronous and asynchronous exception requests, device interrupts, and how these are routed within the kernel.
- Debugging & Testing Tools:
– Show toolchains and support libraries (e.g., “17_kernel_symbols”, “18_backtrace”, “utils”, “devtool”).
– These support integration testing, symbol extraction, and debugging (using Docker, QEMU, OpenOCD, and GDB).
- Build & Support Infrastructure:
– Represent the build scripts (build.rs in each tutorial), configuration files (like Cargo.toml, rust-toolchain.toml), and Docker-related files (docker folder).
– Include external utilities such as “Minipush” for UART loading and common scripts (in “common”) that support testing.

##### Relationships and Interactions
- Data Flow:
– Begin with the hardware layer (the physical Raspberry Pi board) and show how the boot ROM triggers the bootloader (via assembly code in _arch).
- Architectural Layers:
- Component Interactions:
– Indicate dependency flows: Bootloader initializes hardware, passes control to the core kernel, which in turn calls out to device drivers, which interface with peripherals via the BSP.

##### Architectural Patterns and Design Principles
- Modularity:
- Portability:
– Mark the abstraction provided by the BSP for Raspberry Pi, which isolates platform-specific details from core OS services.
- Safety & Performance:
– Indicate where Rust’s unique features are leveraged to provide memory safety and concurrency (modules like synchronization, safe globals, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware/Platform"
        A["Raspberry Pi Hardware"]:::hardware
    end

    subgraph "Boot/CPU Init"
        B["Boot Code & CPU Init"]:::boot
    end

    subgraph "Board Support Package"
        C["Board Support Package"]:::bsp
    end

    subgraph "Kernel Core & Runtime"
        D["Kernel Core & Runtime"]:::kernel
    end

    subgraph "Device Drivers"
        E["GPIO & UART Drivers"]:::drivers
    end

    subgraph "Memory / Virtual Memory Management"
        F["Memory Management & Virtual Memory"]:::memory
    end

    subgraph "Exception Handling"
        G["Exception & Interrupt Handling"]:::exceptions
    end

    subgraph "Debugging & Testing Tools"
        H["Debugging & Testing Tools"]:::debug
    end

    subgraph "Build & Support Infrastructure"
        I["Build & Support Infrastructure"]:::build
    end

    A -->|"boot_sequence"| B
    B -->|"initialize"| C
    C -->|"pass_control"| D
    D -->|"invoke_drivers"| E
    D -->|"setup_memory"| F
    D -->|"handle_exceptions"| G
    C -->|"route_interrupts"| G
    I -->|"build_kernel"| D
    H -->|"debug_kernel"| D
    E -->|"access_peripherals"| C

    click B "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/01_wait_forever/src/_arch/aarch64/cpu/boot.rs"
    click C "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/01_wait_forever/src/bsp/raspberrypi.rs"
    click C "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/01_wait_forever/src/bsp/raspberrypi/kernel.ld"
    click D "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/01_wait_forever/src/main.rs"
    click E "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs"
    click E "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs"
    click E "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/06_uart_chainloader/src/bsp/raspberrypi/driver.rs"
    click F "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/10_virtual_mem_part1_identity_mapping/src/_arch/aarch64/memory/mmu.rs"
    click F "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/10_virtual_mem_part1_identity_mapping/src/_arch/aarch64/memory/translation_table.rs"
    click G "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/09_privilege_level/src/_arch/aarch64/exception/asynchronous.rs"
    click G "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/13_exceptions_part2_peripheral_IRQs/kernel/src/_arch/aarch64/exception/asynchronous.rs"
    click H "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/tree/master/17_kernel_symbols/"
    click H "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/18_backtrace/kernel/src/_arch/aarch64/backtrace.rs"
    click H "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/utils/devtool/devtool.rb"
    click I "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/01_wait_forever/build.rs"
    click I "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/Cargo.toml"
    click I "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/rust-toolchain.toml"
    click I "https://github.com/rust-embedded/rust-raspberrypi-os-tutorials/blob/master/docker/README.md"

    classDef hardware fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef boot fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef bsp fill:#fef9c3,stroke:#333,stroke-width:2px;
    classDef kernel fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef drivers fill:#ffe5b4,stroke:#333,stroke-width:2px;
    classDef memory fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef exceptions fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef debug fill:#f2d7d5,stroke:#333,stroke-width:2px;
    classDef build fill:#d6eaf8,stroke:#333,stroke-width:2px;
```
