# openhwgroup/cva6 architecture

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

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

## Overview

##### Project Type and Purpose
- This is a hardware micro-architecture project: a 6-stage, single-issue, in-order RISC-V CPU core (CVA6) and its integration into an APU (CORE-V-APU) for simulation, FPGA emulation, and ASIC synthesis. It contains:
- RTL (SystemVerilog) for the core (core/) and APU wrapper (corev_apu/)
- CI and build scripts (ci/, .github/, Makefile)
- Configuration generators (config/)
- Verification environment (verif/) with UVM, testbenches, directed tests, regressions
- Documentation (docs/) and performance model (perf-model/)

##### Key Architectural Elements from File Structure & README
- core/: pipeline modules organized by function (frontend, decoder, issue, execute, LSU, commit, cache_subsystem, MMU, PTW, branch predictor, CSR file)
- common/: shared utilities and SRAM wrappers
- corev_apu/: APU testbench wrapper, bus interfaces (AXI, APB), peripherals (bootrom, UART, CLINT, PLIC), FPGA scripts
- verif/: UVM testbench, simulation harness (Verilator, VCS, Spike), directed & random tests, regressions
- pd/synth/: ASIC synthesis flow scripts (DC, timing)
- perf-model/: Python performance model of the core

##### Main Components
A. CVA6 Core
- Pipeline stages (IF, ID, EX, MEM, WB/commit)
- Frontend: fetch, branch predictor (BTB, BHT), instruction queue, compressed decoder
- ID/Decode: decoder, register file
- EX: ALU, multiplier, FPU wrapper, AMO unit
- MEM: LSU, DCache controller (write-through/ write-back variant), MMU (TLB + PTW)
- Commit: scoreboard, CSR unit, performance counters
- Interfaces:
– AXI interface (axi_shim.sv) to cache_subsystem → system bus
– RVFI interface for trace output
– External debug DTM/JTAG module

B. APU & System Integration (corev_apu/)
- AXI interconnect: connects CVA6 core’s AXI ports to DDR controller, bootrom, peripherals
- APB bridge: PLIC (interrupt controller), CLINT (timer & software interrupts), UART, GPIO
- Boot ROM and device-tree loader
- FPGA wrapper scripts (Vivado, Quartus)

C. Verification & Simulation Environment (verif/)
- Testbench harness (Verilator + C++ DPI, UVM agents) instantiating corev_apu/testharness.sv
- Spike ISS comparator, python orchestration (cva6.py)
- Directed & random test suites (riscv-dv, riscv-compliance, riscv-tests)
- Waveform controls, regression scripts

D. ASIC Flow (pd/synth/)
- Synthesis Tcl scripts (cva6_synth.tcl)
- Gate-level netlist analysis

E. Performance Model (perf-model/)

##### Relationships & Data Flows
- Instruction fetch flows from ICache → frontend → decoder → issue
- Data load/store flows through DCache → AXI interconnect → DDR
- MMU TLB lookups for both I/D side, PTW requests on miss
- CSR & debug register accesses via AXI/APB to CLINT/PLIC or JTAG DTM
- UVM agents drive/monitor AXI, RVFI, CSR interfaces
- Spike ISS and python scripts compare trace to RTL output

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CVA6 Core
    subgraph "CVA6 Core"
        direction TB
        subgraph "Pipeline Stages"
            direction TB
            IF["IF Stage<br/>(frontend.sv)"]:::pipeline
            ID["ID Stage<br/>(id_stage.sv)"]:::pipeline
            EX["EX Stage<br/>(ex_stage.sv)"]:::pipeline
            MEM_STAGE["MEM Stage<br/>(load_store_unit.sv)"]:::pipeline
            WB["Commit Stage<br/>(commit_stage.sv)"]:::pipeline
        end
        IF -->|fetch| ID -->|decode| EX -->|execute| MEM_STAGE -->|commit| WB

        subgraph "Memory Subsystem"
            direction TB
            ICache["ICache"]:::memory
            DCache["DCache<br/>(core/cache_subsystem/)"]:::memory
            MMU["MMU/TLB<br/>(cva6_mmu.sv)"]:::memory
        end
        MEM_STAGE -->|load/store| DCache
        DCache -->|AXI transactions| AXI

        subgraph "Interfaces & Buses"
            direction TB
            AXI["AXI Shim<br/>(axi_shim.sv)"]:::bus
            APB["APB Bridge"]:::bus
        end
        WB -->|RVFI trace| RVFI
        DCache --> AXI
        AXI --> APB

        subgraph "Peripherals"
            direction TB
            BootROM["Boot ROM<br/>(bootrom.sv)"]:::peripheral
            CLINT["CLINT<br/>(clint.sv)"]:::peripheral
            PLIC["PLIC<br/>(rv_plic/)"]:::peripheral
            UART["UART"]:::peripheral
        end
        APB --> BootROM
        APB --> CLINT
        APB --> PLIC
        APB --> UART
    end

    subgraph "APU & SoC Integration"
        direction TB
        SoC["SoC Wrapper<br/>(ariane.sv)"]:::bus
    end
    AXI --> SoC

    subgraph "Verification & Simulation"
        direction TB
        TB["Testbench Harness<br/>(ariane_testharness.sv)"]:::verification
        UVM["UVM Env & Agents<br/>(verif/env/uvme/)"]:::verification
        Spike["Spike Comparator"]:::external
        Python["Python Orchestration<br/>(cva6.py)"]:::external
    end
    SoC --> TB
    TB --> UVM
    WB --> RVFI["RVFI Trace<br/>(cva6_rvfi.sv)"]:::external
    RVFI --> UVM
    UVM --> Spike
    UVM --> Python

    subgraph "ASIC Flow"
        direction TB
        Synth["Synth Scripts<br/>(pd/synth/cva6_synth.tcl)"]:::external
        GateAnal["Gate Analysis"]:::external
    end
    SoC --> Synth

    subgraph "Performance Model"
        direction TB
        Perf["Perf Model<br/>(model.py)"]:::external
    end
    SoC --> Perf

    subgraph "External Tools"
        direction TB
        VerilatorCloud["Verilator"]:::external
        VCSCloud["VCS"]:::external
        Quartus["Quartus"]:::external
        Vivado["Vivado"]:::external
    end
    TB --> VerilatorCloud
    TB --> VCSCloud
    SoC --> Quartus
    SoC --> Vivado

    %% Click Events
    click IF "https://github.com/openhwgroup/cva6/blob/master/core/frontend/frontend.sv"
    click ID "https://github.com/openhwgroup/cva6/blob/master/core/id_stage.sv"
    click EX "https://github.com/openhwgroup/cva6/blob/master/core/ex_stage.sv"
    click MEM_STAGE "https://github.com/openhwgroup/cva6/blob/master/core/load_store_unit.sv"
    click WB "https://github.com/openhwgroup/cva6/blob/master/core/commit_stage.sv"
    click DCache "https://github.com/openhwgroup/cva6/tree/master/core/cache_subsystem/"
    click MMU "https://github.com/openhwgroup/cva6/blob/master/core/cva6_mmu/cva6_mmu.sv"
    click AXI "https://github.com/openhwgroup/cva6/blob/master/core/axi_shim.sv"
    click BootROM "https://github.com/openhwgroup/cva6/blob/master/corev_apu/bootrom/bootrom.sv"
    click CLINT "https://github.com/openhwgroup/cva6/blob/master/corev_apu/clint/clint.sv"
    click PLIC "https://github.com/openhwgroup/cva6/tree/master/corev_apu/rv_plic/"
    click SoC "https://github.com/openhwgroup/cva6/blob/master/corev_apu/src/ariane.sv"
    click TB "https://github.com/openhwgroup/cva6/blob/master/corev_apu/tb/ariane_testharness.sv"
    click UVM "https://github.com/openhwgroup/cva6/tree/master/verif/env/uvme/"
    click RVFI "https://github.com/openhwgroup/cva6/blob/master/core/cva6_rvfi.sv"
    click Synth "https://github.com/openhwgroup/cva6/blob/master/pd/synth/cva6_synth.tcl"
    click Perf "https://github.com/openhwgroup/cva6/blob/master/perf-model/model.py"

    %% Styles
    classDef pipeline fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef memory fill:#FFA500,stroke:#333,stroke-width:1px
    classDef bus fill:#90EE90,stroke:#333,stroke-width:1px
    classDef peripheral fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef verification fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCFF,stroke:#333,stroke-width:1px
```
