# riscv-software-src/opensbi architecture

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

- Interactive diagram: https://gitdiagram.com/riscv-software-src/opensbi
- Repository: https://github.com/riscv-software-src/opensbi

## Overview

##### Project Type and Purpose
- OpenSBI is a low-level firmware project providing a reference implementation of the RISC-V Supervisor Binary Interface (SBI).
- It builds a platform-independent core library (libsbi.a), integrates it with platform-specific code to produce libplatsbi.a, and then links these into firmware images that run in M-mode on RISC-V hardware.

##### High-Level Architectural Overview
- Host Environment: Contains the toolchain (GCC/Clang), build tools (Make, Kconfiglib, device-tree-compiler, Python), and scripts.
- Build System: Top-level Makefile orchestrates compilation of:
- Core library (libsbi) under lib/sbi and include/sbi
- Utilities libraries (lib/utils and include/sbi_utils)
- Platform libraries (libplatsbi) under platform/* directories
- Firmware examples under firmware/ and payloads/
- Artifacts:
- libsbi.a (platform-independent static library)
- libplatsbi.a (platform-specific static library)
- Firmware images (ELF and binary) for each supported platform
- Runtime Environment:
- M-mode firmware (OpenSBI) on hardware
- S-mode software (bootloader, hypervisor, OS) invoking SBI calls
- Hardware platform (CPU harts, interrupt controller, timers, console, mailbox, etc.)

##### Main Components
A. Host Layer
- Cross-compile Toolchain (riscv*-gcc / Clang)
- Build Scripts & Makefile + Kconfig configuration
- Device-Tree Compiler (dtc)
- Python scripts & shell helpers (scripts/)
B. Build Artifacts Layer
- Core Library: libsbi.a (built from lib/sbi, include/sbi)
- Utility Libraries: lib/utils/*.a + headers in include/sbi_utils
- Platform Library: libplatsbi.a (built from platform/<name>)
- Firmware Examples: fw_base, fw_dynamic, fw_jump, fw_payload
C. Runtime Layer
- OpenSBI Firmware (M-mode)
- SBI API Interface exposed to S-mode
- Platform Drivers (console, IPI, timer, mailbox, interrupt controller, etc.)
- Hardware Blocks (CPU harts, PLIC, CLINT, UART, GPIO, DTB)
- S-mode Software (Bootloader / U-Boot / Linux / Hypervisor)

##### Relationships and Data Flow
- Linkage: libsbi + libutils → libplatsbi → firmware image
- Runtime Call Flow (S-mode → SBI trap → M-mode firmware → platform drivers → hardware)
- Device-Tree passes hardware description to OpenSBI at boot

##### Architectural Patterns and Design Principles
- Layered static-library composition (core vs utilities vs platform)
- Kconfig-driven compile-time customization
- Clear OS-firmware boundary using SBI trap interface
- Use of modular platform drivers selected via device tree and FDT helper APIs
- Separation of responsibilities: build vs interface vs platform specifics

##### Technologies and Frameworks
- GNU Make and Kconfiglib for configuration/build orchestration
- GCC/Clang cross-toolchain for RISC-V PIE firmware
- Device Tree Compiler (libfdt) for dynamic hardware discovery
- Doxygen for source documentation
- Shell/Python scripts under scripts/ for auxiliary tasks

##### Detailed Elements to Capture
- Kconfig layer feeding into Makefile targets
- Device-Tree (FDT) feeding into platform driver initialization
- Assembly stubs vs C implementations in libsbi/libutils
- Separate firmware payload types (test payload, Linux payload)
- Installation layout under build/ and install/ directories

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Layer
    subgraph "Host Layer"
        direction TB
        Toolchain["Cross-compile Toolchain"]:::host
        Makefile["Makefile"]:::host
        Kconfig["Kconfig"]:::host
        Scripts["Build Scripts & Helpers (scripts/)"]:::host
        DTC["Device-Tree Compiler"]:::host
    end

    %% Build Artifacts Layer
    subgraph "Build Artifacts Layer"
        direction TB
        LibSBI["libsbi.a"]:::lib
        LibUtils["Utility Libs (libutils)"]:::lib
        LibPlatSBI["libplatsbi.a"]:::lib
        subgraph "Firmware Examples"
            direction TB
            FWBase["fw_base"]:::artifact
            FWDyn["fw_dynamic"]:::artifact
            FWJump["fw_jump"]:::artifact
            FWPayload["fw_payload"]:::artifact
            PayloadTests["payload tests"]:::artifact
        end
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        direction TB
        OpenSBI["OpenSBI Firmware (M-mode)"]:::runtime
        SBIAPI["SBI API Interface"]:::runtime
        subgraph "Platform Drivers"
            direction TB
            FDTDrv["FDT Drivers"]:::driver
            GPIODrv["GPIO Drivers"]:::driver
            IPIDrv["IPI Drivers"]:::driver
            IRQDrv["IRQ Chip Drivers"]:::driver
            TimerDrv["Timer Drivers"]:::driver
            SerDrv["Serial Drivers"]:::driver
            MailboxDrv["Mailbox"]:::driver
            RegmapDrv["Regmap"]:::driver
            MPXYDrv["MPXY"]:::driver
            SysDrv["System Helpers"]:::driver
            ResetDrv["Reset & Suspend"]:::driver
        end
        Hardware["Hardware Blocks"]:::hardware
        SMode["S-mode Software"]:::runtime
    end

    %% Build Flow
    Toolchain -->|compile| LibSBI
    Makefile -->|configures| Toolchain
    Kconfig -->|feeds| Makefile
    Scripts -->|invoke| Makefile
    DTC -->|generates DTB| LibPlatSBI

    LibSBI -->|link| LibPlatSBI
    LibUtils -->|link| LibPlatSBI
    LibPlatSBI -->|link| FWBase
    LibPlatSBI -->|link| FWDyn
    LibPlatSBI -->|link| FWJump
    LibPlatSBI -->|link| FWPayload
    LibPlatSBI -->|link| PayloadTests

    %% Runtime Flow
    SMode -->|SBI trap| SBIAPI
    SBIAPI -->|calls| OpenSBI
    OpenSBI -->|initializes| FDTDrv
    OpenSBI -->|uses| GPIODrv
    OpenSBI -->|uses| IPIDrv
    OpenSBI -->|uses| IRQDrv
    OpenSBI -->|uses| TimerDrv
    OpenSBI -->|uses| SerDrv
    OpenSBI -->|uses| MailboxDrv
    OpenSBI -->|uses| RegmapDrv
    OpenSBI -->|uses| MPXYDrv
    OpenSBI -->|uses| SysDrv
    OpenSBI -->|handles| ResetDrv
    OpenSBI -->|controls| Hardware
    FDTDrv -->|describes| Hardware

    %% Click Events - Host Layer
    click Makefile "https://github.com/riscv-software-src/opensbi/tree/master//Makefile"
    click Kconfig "https://github.com/riscv-software-src/opensbi/tree/master//Kconfig"
    click Scripts "https://github.com/riscv-software-src/opensbi/tree/master//scripts/"
    click DTC "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/libfdt/"
    click FDTDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/fdt/"

    %% Click Events - Core & Utils
    click LibSBI "https://github.com/riscv-software-src/opensbi/tree/master//lib/sbi/"
    click LibSBI "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi/"
    click LibUtils "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/"
    click LibUtils "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/"

    %% Click Events - Platform Libraries
    click LibPlatSBI "https://github.com/riscv-software-src/opensbi/tree/master//platform/"

    %% Click Events - Firmware Examples
    click FWBase "https://github.com/riscv-software-src/opensbi/blob/master//firmware/fw_base.S"
    click FWDyn "https://github.com/riscv-software-src/opensbi/blob/master//firmware/fw_dynamic.S"
    click FWJump "https://github.com/riscv-software-src/opensbi/blob/master//firmware/fw_jump.S"
    click FWPayload "https://github.com/riscv-software-src/opensbi/blob/master//firmware/fw_payload.S"
    click PayloadTests "https://github.com/riscv-software-src/opensbi/tree/master//firmware/payloads/"

    %% Click Events - SBI API Interface
    click SBIAPI "https://github.com/riscv-software-src/opensbi/blob/master//include/sbi/sbi_trap.h"
    click SBIAPI "https://github.com/riscv-software-src/opensbi/blob/master//include/sbi/sbi_ecall.h"
    click OpenSBI "https://github.com/riscv-software-src/opensbi/blob/master//lib/sbi/sbi_trap.c"
    click OpenSBI "https://github.com/riscv-software-src/opensbi/blob/master//lib/sbi/sbi_ecall.c"

    %% Click Events - Platform Drivers
    click GPIODrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/gpio/"
    click GPIODrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/gpio/"
    click IPIDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/ipi/"
    click IPIDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/ipi/"
    click IRQDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/irqchip/"
    click IRQDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/irqchip/"
    click TimerDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/timer/"
    click TimerDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/timer/"
    click SerDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/serial/"
    click SerDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/serial/"
    click MailboxDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/mailbox/"
    click MailboxDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/mailbox/"
    click RegmapDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/regmap/"
    click RegmapDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/regmap/"
    click MPXYDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/mpxy/"
    click MPXYDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/mpxy/"
    click SysDrv "https://github.com/riscv-software-src/opensbi/tree/master//include/sbi_utils/sys/"
    click SysDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/sys/"
    click ResetDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/reset/"
    click ResetDrv "https://github.com/riscv-software-src/opensbi/tree/master//lib/utils/suspend/"

    %% Click Events - Documentation
    click DocsConfig "https://github.com/riscv-software-src/opensbi/blob/master/docs/doxygen.cfg"
    click DocsPlatform "https://github.com/riscv-software-src/opensbi/tree/master/docs/platform/"
    click DocsFirmware "https://github.com/riscv-software-src/opensbi/tree/master/docs/firmware/"
    click DocsBuild "https://github.com/riscv-software-src/opensbi/blob/master/docs/opensbi_config.md"

    %% Styles
    classDef host fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px
    classDef artifact fill:#98FB98,stroke:#000,stroke-width:1px
    classDef runtime fill:#FFA500,stroke:#000,stroke-width:1px
    classDef driver fill:#FFEFD5,stroke:#000,stroke-width:1px
    classDef hardware fill:#D3D3D3,stroke:#000,stroke-width:1px
```
