How lawrencehunter/sentinelboot works
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