# lawrencehunter/sentinelboot architecture

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

- Interactive diagram: https://gitdiagram.com/lawrencehunter/sentinelboot
- Repository: https://github.com/lawrencehunter/sentinelboot

## Overview

##### Project Type and Purpose
- This is an embedded secure bootloader for RISC-V, written in Rust.
- Purpose: verify a kernel’s hash with public-key cryptography, then hand off control to the kernel.
- Supports multiple platforms (QEMU, HiFive Unmatched, VisionFive) and optional RISC-V vector cryptography.

##### File Structure
Top‐level crates:
- bsp/ – board support packages (qemu, unmatched, visionfive)
- console/ – console abstraction
- driver/ – UART drivers (DW8250, virt16550, unmatched)
- global_allocator/ – optional allocator implementation
- mmio/ – memory-mapped I/O abstractions
- riscv64/ – low-level RISC-V startup (assembly boot, trap handlers)
- synchronisation/ – synchronization primitives
- src/ – core bootloader logic (main.rs, verification.rs, runtime checks, panic handler)
- tftp/ – provisioning scripts and assets (kernel images, dtbs, rootfs, QEMU binary)
Build‐time glue:
- Cargo.toml (workspace), build.rs, Makefile, Dockerfile, gen_helper.py

##### README for Technical Stack
- Languages/Tools: Rust, Cargo, Docker, QEMU, U-Boot, Make, Python (helper scripts), tftpd, isc-dhcpd
- Execution flow: U-Boot → SentinelBoot → TFTP fetch → signature verification → kernel jump
- Configurable via Makefile variables (BSP, DEBUG, etc.)

##### Main Components and Relationships
– Docker container / host environment
– Makefile invokes Cargo across all workspace crates
– build.rs and gen_helper.py for code generation (e.g., embedding public key)
→ Produces a `sentinel_boot` ELF/binary

B. Deployment & External Services (bottom)
– TFTP Server (serving sentinel_boot, Image_signed, dtb, rootfs.cpio)
– DHCP Server (assigns IP to QEMU or board)
– U-Boot on the target (loads sentinel_boot via TFTP)

C. Target Execution (right side)
1. U-Boot Stage
- Sets up networking via DHCP/TFTP, fetches sentinel_boot into RAM
- Executes `go <addr>` handing control to SentinelBoot
2. SentinelBoot Runtime
- riscv64 crate: early boot (assembly) → switch to Rust
- global_allocator (optional) sets up heap
- mmio + driver crates: initialize UART console
- console crate: abstract print/logging interface
- synchronisation crate: locks/mutexes if needed
- verification.rs: load kernel image via TFTP, verify signature
- run_time_checks.rs: optional safety assertions
- panic_wait.rs: wait loop on panic
- jump to kernel

D. Hardware Abstraction Layers
– BSP crate chosen by MAKE variable (qemu, unmatched, visionfive) compiles board-specific drivers and memory maps
– driver crate: platform-independent UART drivers selected by BSP

##### Architectural Patterns and Principles
- Layered modular design via Cargo workspace crates
- Clear separation: hardware abstraction (BSP & drivers) vs. core logic (src/)
- Safety-first: Rust’s ownership for memory safety, reduced unsafe blocks in riscv64 assembly only where needed
- Extensibility: add new BSPs or drivers by dropping in new folders/crates

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        DF["Dockerfile"]:::build
        MF["Makefile"]:::build
        CT["Cargo.toml"]:::build
        BR["build.rs"]:::build
        GH["gen_helper.py"]:::build
        BIN["sentinel_boot ELF/binary"]:::build
    end

    DF --> MF
    MF --> CT
    MF --> BR
    MF --> GH
    MF --> BIN

    %% Runtime Crates
    subgraph "Runtime Crates"
        direction TB
        BSP["bsp/"]:::runtime
        DR["driver/src/lib.rs"]:::runtime
        CON["console/src/lib.rs"]:::runtime
        GA["global_allocator/src/lib.rs"]:::runtime
        MM["mmio/src/lib.rs"]:::runtime
        RV["riscv64/src/lib.rs"]:::runtime
        SY["synchronisation/src/lib.rs"]:::runtime
        CORE["src/main.rs\nsrc/verification.rs\nsrc/run_time_checks.rs\nsrc/panic_wait.rs"]:::runtime
    end

    BIN --> BSP
    BIN --> DR
    BIN --> CON
    BIN --> GA
    BIN --> MM
    BIN --> RV
    BIN --> SY
    BIN --> CORE

    %% External Services & Deployment
    subgraph "External Services" 
        direction TB
        TFTP["TFTP Server"]:::external
        DHCP["DHCP Server"]:::external
        UBOOT["U-Boot"]:::external
    end

    BIN -->|deploy via TFTP| TFTP
    TFTP -->|served to target| UBOOT
    DHCP --> UBOOT

    %% Target Execution
    UBOOT -->|go <addr>| CORE

    CORE -->|TFTP fetch kernel| TFTP

    %% Hardware Targets
    subgraph "Hardware Targets"
        direction TB
        QEMU["QEMU"]:::hardware
        UNMATCHED["HiFive Unmatched"]:::hardware
        VISION["VisionFive"]:::hardware
    end

    UBOOT --> QEMU
    UBOOT --> UNMATCHED
    UBOOT --> VISION

    %% Click Events
    click DF "https://github.com/lawrencehunter/sentinelboot/tree/main/Dockerfile"
    click MF "https://github.com/lawrencehunter/sentinelboot/tree/main/Makefile"
    click CT "https://github.com/lawrencehunter/sentinelboot/blob/main/Cargo.toml"
    click BR "https://github.com/lawrencehunter/sentinelboot/blob/main/build.rs"
    click GH "https://github.com/lawrencehunter/sentinelboot/blob/main/gen_helper.py"
    click BSP "https://github.com/lawrencehunter/sentinelboot/tree/main/bsp/"
    click DR "https://github.com/lawrencehunter/sentinelboot/blob/main/driver/src/lib.rs"
    click CON "https://github.com/lawrencehunter/sentinelboot/blob/main/console/src/lib.rs"
    click GA "https://github.com/lawrencehunter/sentinelboot/blob/main/global_allocator/src/lib.rs"
    click MM "https://github.com/lawrencehunter/sentinelboot/blob/main/mmio/src/lib.rs"
    click RV "https://github.com/lawrencehunter/sentinelboot/blob/main/riscv64/src/lib.rs"
    click SY "https://github.com/lawrencehunter/sentinelboot/blob/main/synchronisation/src/lib.rs"
    click CORE "https://github.com/lawrencehunter/sentinelboot/blob/main/src/main.rs"
    classDef build fill:#cce5ff,stroke:#66b0ff,stroke-width:1px
    classDef runtime fill:#d4edda,stroke:#2e7d32,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#ffb822,stroke-width:1px
    classDef hardware fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
