How rustsbi/bouffalo-hal works
Project type and purpose
• This is an embedded‐systems software ecosystem written in Rust. It consists of three Cargo workspace crates:
• bouffalo-hal: A Hardware Abstraction Layer (HAL) exposing safe Rust APIs for Bouffalo peripherals.
• bouffalo-rt: A runtime library providing startup code, the #[entry] macro, low-level initialization, and SOC-specific glue.
• blri: A command-line utility to verify, patch, and flash firmware images onto Bouffalo chips.
• In addition, there are extensive examples/ demonstrating peripheral usage, and GitHub Actions CI for automatic testing.
File structure
• Top-level directories
• blri/ – the firmware‐image utility CLI
• bouffalo-hal/ – Rust crate with src/ subdivided by peripheral (gpio, dma, uart, etc.)
• bouffalo-rt/ – runtime crate with macros, SOC definitions, startup code, and examples under its examples/
• examples/ – high-level demos combining bouffalo-rt + bouffalo-hal
• docs/ – documentation assets, GIFs illustrating demos
• Each crate has its own Cargo.toml, tests, and build scripts where appropriate (e.g., build.rs in bouffalo-rt).
• CI workflows in .github/workflows/Cargo.yml orchestrate building and testing all components.
READMEs for additional insights
• README.md outlines the three core components and their roles.
• Describes supported peripherals, example gallery, and integration points with the embedded-Rust ecosystem (e.g., embedded-hal traits).
Main components and their relationships
a. Components
1) bouffalo-hal library
– Modules per peripheral (GPIO, UART, SPI, I2C, PWM, DMA, timers, etc.)
– Safe wrappers over register mappings
2) bouffalo-rt runtime
– #[entry] macro expansion → user main symbol
– SOC peripherals and vector table initialization
3) blri utility
– Reads ELF → verifies image headers → generates flashable BIN
– Optionally patches header fields
4) Examples & Demos
– MCU application code linking bouffalo-hal + bouffalo-rt
– Use embedded-hal traits to talk to hardware
5) External dependencies
– cortex-m or RISC-V crates for core support
– embedded-hal traits
– Build tools (rust-objcopy, lld linker scripts)
b. Interactions
• Examples link against bouffalo-rt + bouffalo-hal.
• bouffalo-hal provides peripheral drivers that call into register definitions in bouffalo-rt SOC modules.
• blri consumes the compiled ELF from examples/other firmware projects, validates headers defined by bouffalo-rt, and outputs flash image.
• CI triggers build → runs tests in each crate → runs blri scripts (elf2bin.sh) against test ELF binaries.
c. Architectural patterns & design principles
• Modular crate structure following Rust’s workspace conventions
• Separation of concerns: HAL (drivers) vs. RT (startup) vs. CLI (tooling)
• Zero-cost abstractions: leveraging Rust’s type system (typestates in GPIO)
• Extensibility via embedded-hal trait implementations allowing swapping in alternative HALs.
d. Technologies, frameworks, libraries
• Rust (stable ≥1.85)
• Cargo workspaces, build.rs scripts for code generation
• GitHub Actions for CI
• RISC-V / architecture-specific crates for register definitions
• Shell scripts in blri/ci for ELF→BIN conversion
Detail
• Peripheral module in bouffalo-hal as part of that component.
• Build.rs macro expansion in bouffalo-rt generating SOC peripheral defs.
• Example dependencies on specific HAL modules (e.g., PWM demo uses bouffalo-hal/src/pwm).
• Don’t overcomplicate—represent each Cargo crate as a discrete component with its public API boundary, then show internal modules to the level that matters for your audience.