# openhwgroup/cva6-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/openhwgroup/cva6-sdk
- Repository: https://github.com/openhwgroup/cva6-sdk

## Overview

##### Project Type and Purpose
- Type: Embedded toolchain & SDK for the OpenHW CVA6 RISC-V core
- Purpose:
– Provide all host-side tools (Spike ISA simulator, FESVR, riscv-tests), firmware (OpenSBI, U-Boot), patches (Linux, Agilex, Altera SD card), and a root filesystem (Buildroot + Busybox)
– Enable building FPGA boot images (Genesys II, Agilex7) and simulation images (Spike + OpenSBI + Linux)

##### File Structure
Top-level components:
- Submodules: opensbi, riscv-isa-sim, riscv-tests, u-boot
- Patches: linux_patch/, agilex_patch/, altera-sd-card/
- Build orchestrator: Makefile, configs/, container/Dockerfile
- Buildroot + rootfs: buildroot/, rootfs/
- Utility: cachetest/, vitetris (example apps)

##### README for Insights
- Build targets: images, vmlinux, uImage.bin, fw_payload.bin, isa-sim, spike_payload, flash-sdcard
- Supported platforms: fpga/ariane (Genesys II), fpga/cva6-altera (Agilex7)
- Docker container to standardize host environment

##### Main Components & Their Relationships
a. Host Environment
– Native host (Ubuntu/Fedora) or Docker container
– Build orchestrator (Makefile + configs + patches)
– Submodules (cloned via git submodule)
– Buildroot toolchain (cross-compiler, binutils, libraries)

b. Build System Flow
1. Apply patches (linux_patch/, agilex_patch/)
2. Build subcomponents:
- OpenSBI → firmware (SBI)
- U-Boot → bootloader
- Linux kernel → vmlinux, uImage
- Buildroot → rootfs/initramfs, host tools (in install$(XLEN)/bin)
- Spike → ISA simulator
- riscv-tests, riscv-fesvr → tests & sim tether
3. Link & package images: fw_payload.bin (OpenSBI+U-Boot), uImage.bin (kernel), rootfs, partition table
4. Output to install$(XLEN)/ and/or flash to SD card

c. Target Execution Environments
- FPGA board (Genesys II, Agilex7) via boot from SD card
- Spike simulator (uses riscv-fesvr to handle syscalls)

##### Architectural Patterns & Design Principles
- Modular, submodule-based: each tool lives in its own directory/submodule
- Makefile-driven monorepo orchestration
- Layered boot architecture: Hardware → OpenSBI → U-Boot → Linux → Userspace
- Cross-compile buildroot host tools vs. target rootfs separation

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Host Environment"
        HostOS["Native OS"]:::host
        Docker["Docker Container"]:::host
        Dependencies["Dependencies\n(autotools, gcc, etc.)"]:::host
        MetaGit[".gitmodules"]:::host
        MetaReadme["README.md"]:::host
        MetaIgnore[".gitignore"]:::host
    end

    subgraph "Build Orchestration"
        Makefile["Makefile"]:::build
        Configs["configs/"]:::build
        PatchLinux["linux_patch/"]:::build
        PatchAgilex["agilex_patch/"]:::build
        PatchSD["altera-sd-card/"]:::build
        Sub_OpenSBI["opensbi/"]:::build
        Sub_Spike["riscv-isa-sim/"]:::build
        Sub_Tests["riscv-tests/"]:::build
        Sub_UBoot["u-boot/"]:::build
        Buildroot["buildroot/"]:::build
        Rootfs["rootfs/"]:::build
        Cachetest["cachetest/cachetest.c"]:::build
        Vitetris["vitetris/"]:::build
    end

    subgraph "Outputs"
        HostTools["install$(XLEN)/bin"]:::image
        SpikePayload["spike_fw_payload.elf"]:::image
        Vmlinux["vmlinux"]:::image
        UImage["uImage.bin"]:::image
        FWPayload["fw_payload.bin"]:::image
        SDImage["SD card GPT image"]:::image
    end

    subgraph "Targets"
        subgraph "FPGA Board" 
            FPGA["Genesys II / Agilex7"]:::target-hw
            SBI_on_Target["OpenSBI → U-Boot"]:::target-hw
            Linux_on_Target["Linux → rootfs"]:::target-hw
        end
        subgraph "Spike Simulator"
            SpikeSim["Spike Simulator"]:::target-sim
            FESVR["riscv-fesvr"]:::target-sim
        end
    end

    %% Flows
    HostOS -->|"orchestrate"| Makefile
    Docker -->|"orchestrate"| Makefile
    Dependencies -->|"orchestrate"| Makefile

    Makefile -->|"apply patches"| PatchLinux
    Makefile -->|"apply patches"| PatchAgilex
    Makefile -->|"apply patches"| PatchSD

    Makefile -->|"build"| Sub_OpenSBI
    Makefile -->|"build"| Sub_UBoot
    Makefile -->|"build"| Sub_Spike
    Makefile -->|"build"| Sub_Tests
    Makefile -->|"build"| Buildroot

    Sub_OpenSBI -->|"package"| FWPayload
    Sub_UBoot -->|"package"| FWPayload
    Buildroot -->|"package"| HostTools
    Sub_Spike -->|"package"| SpikePayload
    Sub_Tests -->|"package"| SpikePayload
    Buildroot -->|"package"| SDImage
    Vmlinux -->|"produce"| UImage

    FWPayload -->|"flash"| SDImage
    SDImage -->|"boot"| FPGA
    FPGA -->|"load"| SBI_on_Target
    SBI_on_Target -->|"handoff"| Linux_on_Target

    SpikePayload -->|"simulate"| SpikeSim
    SpikeSim -->|"syscall via"| FESVR

    %% Click events
    click Docker "https://github.com/openhwgroup/cva6-sdk/tree/master/container/Dockerfile"
    click MetaGit "https://github.com/openhwgroup/cva6-sdk/blob/master/.gitmodules"
    click MetaReadme "https://github.com/openhwgroup/cva6-sdk/blob/master/README.md"
    click MetaIgnore "https://github.com/openhwgroup/cva6-sdk/blob/master/.gitignore"
    click Makefile "https://github.com/openhwgroup/cva6-sdk/tree/master/Makefile"
    click Configs "https://github.com/openhwgroup/cva6-sdk/tree/master/configs/"
    click PatchLinux "https://github.com/openhwgroup/cva6-sdk/tree/master/linux_patch/"
    click PatchAgilex "https://github.com/openhwgroup/cva6-sdk/tree/master/agilex_patch/"
    click PatchSD "https://github.com/openhwgroup/cva6-sdk/tree/master/altera-sd-card/"
    click Sub_OpenSBI "https://github.com/openhwgroup/cva6-sdk/tree/master/opensbi/"
    click Sub_Spike "https://github.com/openhwgroup/cva6-sdk/tree/master/riscv-isa-sim/"
    click Sub_Tests "https://github.com/openhwgroup/cva6-sdk/tree/master/riscv-tests/"
    click Sub_UBoot "https://github.com/openhwgroup/cva6-sdk/tree/master/u-boot/"
    click Buildroot "https://github.com/openhwgroup/cva6-sdk/tree/master/buildroot/"
    click Rootfs "https://github.com/openhwgroup/cva6-sdk/tree/master/rootfs/"
    click Cachetest "https://github.com/openhwgroup/cva6-sdk/blob/master/cachetest/cachetest.c"
    click Vitetris "https://github.com/openhwgroup/cva6-sdk/tree/master/vitetris/"

    %% Styles
    classDef host fill:#AED6F1,stroke:#1F618D
    classDef build fill:#85C1E9,stroke:#1B4F72
    classDef image fill:#A3E4D7,stroke:#117A65
    classDef target-hw fill:#F5CBA7,stroke:#B9770E
    classDef target-sim fill:#D7BDE2,stroke:#6C3483
```
