# rustsbi/bouffalo-hal architecture

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

- Interactive diagram: https://gitdiagram.com/rustsbi/bouffalo-hal
- Repository: https://github.com/rustsbi/bouffalo-hal

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Examples_Peripherals["Peripherals Demos"]:::examples
        Examples_Multicore["Multicore Demo"]:::examples
        Examples_Runtime["RT Examples"]:::examples
    end

    %% Library Layer
    subgraph "Library Layer"
        direction TB
        subgraph "bouffalo-hal" 
            direction TB
            HAL_Cargo["Cargo.toml"]:::lib
            HAL_Lib["lib.rs"]:::lib
            HAL_GPIO["GPIO Module"]:::lib
            HAL_DMA["DMA Module"]:::lib
            HAL_PWM["PWM Module"]:::lib
            HAL_I2C["I2C Module"]:::lib
            HAL_SPI["SPI Module"]:::lib
            HAL_UART["UART Module"]:::lib
            HAL_SDIO["SDIO Module"]:::lib
            HAL_TIMER["Timer Module"]:::lib
            HAL_CLOCKS["Clocks Module"]:::lib
            HAL_SEC["Security Module"]:::lib
        end
        subgraph "bouffalo-rt"
            direction TB
            RT_Cargo["Cargo.toml"]:::lib
            RT_Build["build.rs"]:::lib
            RT_Lib["lib.rs"]:::lib
            RT_Macros["Macros"]:::lib
            RT_Arch["Arch Support"]:::lib
            RT_SOC["SoC Definitions"]:::lib
        end
    end

    %% Tooling Layer
    subgraph "Tooling Layer"
        direction TB
        BLRI_Cargo["Cargo.toml"]:::cli
        BLRI_Main["main.rs"]:::cli
        BLRI_Lib["lib.rs"]:::cli
        BLRI_ISP["isp.rs"]:::cli
        BLRI_CI_Script["elf2bin.sh"]:::cli
        CI_Workflow["Cargo CI Workflow"]:::ci
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Ext_CortexM["cortex-m crate"]:::ext
        Ext_EmbeddedHAL["embedded-hal traits"]:::ext
        Ext_Objcopy["rust-objcopy tool"]:::ext
        Ext_LLD["lld linker"]:::ext
    end

    %% Docs
    Docs["docs/ & README.md"]:::ext

    %% Relationships
    Examples_Peripherals -->|"depends on"| HAL_Lib
    Examples_Peripherals -->|"depends on"| RT_Lib
    Examples_Multicore -->|"depends on"| HAL_Lib
    Examples_Multicore -->|"depends on"| RT_Lib
    Examples_Runtime -->|"built-in examples"| RT_Lib

    HAL_Lib -->|"wraps registers in"| RT_SOC
    HAL_GPIO -->|"uses definitions from"| RT_SOC
    HAL_DMA -->|"uses definitions from"| RT_SOC

    BLRI_Main -->|"uses"| RT_SOC
    BLRI_Main -->|"reads ELF from"| Examples_Peripherals
    BLRI_Main -->|"outputs BIN"| BLRI_CI_Script

    CI_Workflow -->|"builds & tests"| HAL_Cargo
    CI_Workflow -->|"builds & tests"| RT_Cargo
    CI_Workflow -->|"builds & tests"| BLRI_Cargo
    CI_Workflow -->|"runs"| BLRI_CI_Script

    RT_Build -->|"generates"| RT_SOC
    RT_Macros -->|"expands to entry"| RT_Lib

    Examples_Peripherals -->|"implements"| Ext_EmbeddedHAL
    HAL_Lib -->|"implements"| Ext_EmbeddedHAL
    RT_Lib -->|"relies on"| Ext_CortexM

    %% Click events for component mapping
    click HAL_Cargo "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/Cargo.toml"
    click HAL_Lib "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/lib.rs"
    click HAL_GPIO "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/gpio/"
    click HAL_DMA "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/dma/"
    click HAL_PWM "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/pwm/"
    click HAL_I2C "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/i2c.rs"
    click HAL_SPI "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/spi.rs"
    click HAL_SPI "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/spi/"
    click HAL_UART "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/uart.rs"
    click HAL_UART "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/uart/"
    click HAL_SDIO "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/sdio.rs"
    click HAL_SDIO "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/sdio/"
    click HAL_TIMER "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/timer.rs"
    click HAL_CLOCKS "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-hal/src/clocks.rs"
    click HAL_SEC "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-hal/src/sec/"
    click RT_Cargo "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-rt/Cargo.toml"
    click RT_Build "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-rt/build.rs"
    click RT_Lib "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-rt/src/lib.rs"
    click RT_Macros "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-rt/macros/src/lib.rs"
    click RT_Arch "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-rt/src/arch/rvi.rs"
    click RT_SOC "https://github.com/rustsbi/bouffalo-hal/blob/main/bouffalo-rt/src/soc/bl616.rs"
    click BLRI_Cargo "https://github.com/rustsbi/bouffalo-hal/blob/main/blri/Cargo.toml"
    click BLRI_Main "https://github.com/rustsbi/bouffalo-hal/blob/main/blri/src/main.rs"
    click BLRI_Lib "https://github.com/rustsbi/bouffalo-hal/blob/main/blri/src/lib.rs"
    click BLRI_ISP "https://github.com/rustsbi/bouffalo-hal/blob/main/blri/src/isp.rs"
    click BLRI_CI_Script "https://github.com/rustsbi/bouffalo-hal/blob/main/blri/ci/test_elf2bin.sh"
    click CI_Workflow "https://github.com/rustsbi/bouffalo-hal/blob/main/.github/workflows/Cargo.yml"
    click Docs "https://github.com/rustsbi/bouffalo-hal/tree/main/docs/"
    click Examples_Peripherals "https://github.com/rustsbi/bouffalo-hal/tree/main/examples/peripherals/"
    click Examples_Multicore "https://github.com/rustsbi/bouffalo-hal/tree/main/examples/multicore/multicore-demo/"
    click Examples_Runtime "https://github.com/rustsbi/bouffalo-hal/tree/main/bouffalo-rt/examples/blinky-bl616/"

    %% Styles
    classDef lib fill:#B3D4FC,stroke:#0366d6,color:#000;
    classDef cli fill:#C6F6D5,stroke:#2F855A,color:#000;
    classDef examples fill:#FEEBC8,stroke:#DD6B20,color:#000;
    classDef ext fill:#E2E8F0,stroke:#4A5568,color:#000;
    classDef ci fill:#FDE68A,stroke:#B7791F,color:#000;
```
