# ucb-bar/riscv-mini architecture

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

- Interactive diagram: https://gitdiagram.com/ucb-bar/riscv-mini
- Repository: https://github.com/ucb-bar/riscv-mini

## Overview

##### Project type and purpose
- This is a hardware‐design project (“riscv-mini”), implemented in Chisel (Scala DSL) that generates a simple 3‐stage RISC-V CPU with instruction and data caches.
- It is intended as an educational / intermediate example (RV32I + machine‐level ISA) before moving on to a full rocket-chip implementation.

##### File structure
- Top level:
- build.sbt, Makefile, build‐scripts (.sh) → build & generate FIRRTL/Verilog & run simulations
- .github/workflows → CI for building, testing, installing toolchains
- src/main/scala → Chisel sources, organized by packages:
- mini: Config, Core, Datapath, Control, ALU, CSR, Cache, Tile, Main
- junctions: bus interface definitions (e.g., NASTI)
- src/main/cc → C++ test harness for Verilator (top.cc, mm.cc/.h)
- custom‐bmark → template for user benchmarks (C/assembly + Makefile)
- src/test/scala → unit and integration tests (ChiselTest/SBT)
- tests/*.hex → RISC-V test binaries for simulation

##### README for additional insights
- Build flow: `make` → generates FIRRTL & Verilog (generated-src), `make verilator` → builds `VTile`, `make run-tests` → runs Verilator sims on .hex files
- SBT tests drive Chisel testers for unit/integration tests.
- External dependency: RISC-V toolchain for custom benchmarks.

##### Main components and their interactions
a. Frontend (Chisel)
- Chisel source files → compiled by sbt → FIRRTL IR → Verilog
b. Backend (Simulation & Verification)
- Verilator + C++ harness (src/main/cc) → `VTile` simulation binary
- Test input: .hex instruction/data files → loaded into simulated memory
- Waveform dump (VCD) & execution trace logs
c. CPU Tile (Verilog module)
- Pipeline stages: Fetch, Decode, Execute
- Submodules: RegFile, ALU, ImmGen, Control, CSR, Cache (I$, D$)
- Bus interface: handles memory requests via NASTI-like protocol
d. Memory model / testbench
- Simple memory model in mm.cc reading hex files into arrays
- Interfaces to I$ and D$ ports of the Tile
e. Test & CI
- sbt-driven unit/integration tests → ChiselTest
- GitHub workflows orchestrate builds, simulations, and toolchain installs

##### Architectural patterns & design principles
- 3-stage pipeline (Fetch/Decode/Execute) with clear separation of datapath vs. control
- Module hierarchy reflecting hardware blocks (Tile → Core + Caches → submodules)
- Use of bundle interfaces (junctions.Nasti) for memory access
- Separation between hardware generator (Chisel) and simulation harness (Verilator + C++)
- Extensibility: custom‐bmark directory for user programs

##### Final advice
- Be comprehensive: capture both the hardware generator path and the simulation/test path.
- Drill into the Tile’s internal structure—separate datapath vs. control vs. memory subsystems.
- Interactions with external files (.hex) and outputs (dump.vcd, logs).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Generation Flow
    subgraph "Build & Generation Flow"
        direction TB
        MAKEFILE["Makefile"]:::software
        BUILDSBT["build.sbt"]:::software
        PROJECTDIR["project/"]:::software
        INSTALLVERI[".install_verilator.sh"]:::software
        BUILDTOOLS["build-riscv-tools.sh"]:::software
    end

    %% Continuous Integration
    subgraph "Continuous Integration"
        direction TB
        CI1[".github/workflows/ci.yml"]:::software
        CI2[".github/workflows/install-circt/action.yml"]:::software
        CI3[".github/workflows/setup-oss-cad-suite/action.yml"]:::software
    end

    %% Documentation & Diagrams
    subgraph "Documentation & Diagrams"
        direction TB
        README["README.md"]:::software
        DIAGRAM["diagram.pdf/png"]:::software
    end

    %% Chisel Hardware Generator (Frontend)
    subgraph "Chisel Hardware Generator"
        direction TB
        subgraph "src/main/scala/mini"
            direction TB
            CONFIG["Config.scala"]:::hardware
            MAIN["Main.scala"]:::hardware
            TILESC{"Tile.scala"}:::hardware
            CORESC["Core.scala"]:::hardware
            DATAPATHSC["Datapath.scala"]:::hardware
            CONTROLSC["Control.scala"]:::hardware
            ALUSC["Alu.scala"]:::hardware
            IMMGENSC["ImmGen.scala"]:::hardware
            BRCONDSC["BrCond.scala"]:::hardware
            CSRSC["CSR.scala"]:::hardware
            CACHESC["Cache.scala"]:::hardware
            REGFILESC["RegFile.scala"]:::hardware
            INSTRSC["Instructions.scala"]:::hardware
        end
        NASTISRC["src/main/scala/junctions/nasti.scala"]:::hardware
    end

    %% Hardware Hierarchy
    subgraph "Hardware Hierarchy (Tile)"
        direction TB
        TILE["Tile (Verilog)"]:::hardware
        subgraph "Core & Submodules"
            direction TB
            CORE["Core"]:::hardware
            subgraph "Datapath"
                direction TB
                REGFILE["RegFile"]:::storage
                ALU["ALU"]:::hardware
                IMMGEN["ImmGen"]:::hardware
            end
            CONTROL["Control & CSR"]:::hardware
        end
        subgraph "Caches"
            direction TB
            ICACHE["I$"]:::storage
            DCACHE["D$"]:::storage
        end
    end

    %% Verilator Simulation Harness (Backend)
    subgraph "Verilator + C++ Simulation Harness"
        direction TB
        TOPCC["top.cc"]:::software
        MMCC["mm.cc/mm.h"]:::software
    end

    %% Custom Benchmark Templates
    subgraph "Custom Benchmark Templates"
        direction TB
        BMARK_MK["custom-bmark/Makefile"]:::software
        BMARK_C["custom-bmark/main.c"]:::software
        BMARK_S["custom-bmark/add.S"]:::software
    end

    %% Unit & Integration Tests
    subgraph "Unit & Integration Tests"
        direction TB
        subgraph "src/test/scala/mini"
            direction TB
            ALUTEST["ALUTests.scala"]:::software
            BRCONDTEST["BrCondTests.scala"]:::software
            CSRTEST["CSRTests.scala"]:::software
            CACHETEST["CacheTests.scala"]:::software
            CORETEST["CoreTests.scala"]:::software
            DATAPATHTEST["DatapathTests.scala"]:::software
            IMMGENTEST["ImmGenTests.scala"]:::software
            INTEGTEST["IntegrationTest.scala"]:::software
            OPCODE["Opcode.scala"]:::software
            TESTCONFIG["TestConfig.scala"]:::software
            TESTUTILS["TestUtils.scala"]:::software
            TILETESTER["TileTester.scala"]:::software
        end
    end

    %% RISC-V Test Binaries
    TESTBIN["tests/*.hex"]:::external

    %% Simulation Outputs
    VCD["dump.vcd & logs"]:::external

    %% Build & Simulation Flow Connections
    MAKEFILE -->|invoke SBT| BUILDSBT
    BUILDSBT -->|"compiles Chisel"| CONFIG
    CONFIG -->|generates FIRRTL| FIRRTL["FIRRTL IR"]:::software
    FIRRTL -->|emits Verilog| TILE
    TILE -->|used by| TOPCC
    TOPCC -->|links| MMCC
    MMCC -->|loads| TESTBIN
    TESTBIN -->|feeds| ICACHE
    TESTBIN -->|feeds| DCACHE
    TOPCC -->|runs simulation| VCD

    %% CI & Documentation
    CI1 -->|triggers| MAKEFILE
    README -->|documents| MAKEFILE
    DIAGRAM -->|explains| TILE

    %% Classes
    classDef software fill:#cce5ff,stroke:#3399ff,color:#000
    classDef hardware fill:#d5f5d5,stroke:#28a745,color:#000
    classDef storage fill:#fcf3cf,stroke:#f1c40f,color:#000
    classDef external fill:#f0f0f0,stroke:#888,dasharray: 5 5,color:#000

    %% Click Events
    click MAKEFILE "https://github.com/ucb-bar/riscv-mini/tree/main/Makefile"
    click BUILDSBT "https://github.com/ucb-bar/riscv-mini/blob/main/build.sbt"
    click PROJECTDIR "https://github.com/ucb-bar/riscv-mini/tree/main/project/"
    click INSTALLVERI "https://github.com/ucb-bar/riscv-mini/blob/main/.install_verilator.sh"
    click BUILDTOOLS "https://github.com/ucb-bar/riscv-mini/blob/main/build-riscv-tools.sh"
    click CI1 "https://github.com/ucb-bar/riscv-mini/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/ucb-bar/riscv-mini/blob/main/.github/workflows/install-circt/action.yml"
    click CI3 "https://github.com/ucb-bar/riscv-mini/blob/main/.github/workflows/setup-oss-cad-suite/action.yml"
    click README "https://github.com/ucb-bar/riscv-mini/blob/main/README.md"
    click DIAGRAM "https://github.com/ucb-bar/riscv-mini/blob/main/diagram.pdf"
    click CONFIG "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Config.scala"
    click MAIN "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Main.scala"
    click TILESC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Tile.scala"
    click CORESC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Core.scala"
    click DATAPATHSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Datapath.scala"
    click CONTROLSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Control.scala"
    click ALUSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Alu.scala"
    click IMMGENSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/ImmGen.scala"
    click BRCONDSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/BrCond.scala"
    click CSRSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/CSR.scala"
    click CACHESC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Cache.scala"
    click REGFILESC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/RegFile.scala"
    click INSTRSC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/mini/Instructions.scala"
    click NASTISRC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/scala/junctions/nasti.scala"
    click TOPCC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/cc/top.cc"
    click MMCC "https://github.com/ucb-bar/riscv-mini/blob/main/src/main/cc/mm.cc"
    click BMARK_MK "https://github.com/ucb-bar/riscv-mini/tree/main/custom-bmark/Makefile"
    click BMARK_C "https://github.com/ucb-bar/riscv-mini/blob/main/custom-bmark/main.c"
    click BMARK_S "https://github.com/ucb-bar/riscv-mini/blob/main/custom-bmark/add.S"
    click ALUTEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/ALUTests.scala"
    click BRCONDTEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/BrCondTests.scala"
    click CSRTEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/CSRTests.scala"
    click CACHETEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/CacheTests.scala"
    click CORETEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/CoreTests.scala"
    click DATAPATHTEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/DatapathTests.scala"
    click IMMGENTEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/ImmGenTests.scala"
    click INTEGTEST "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/IntegrationTest.scala"
    click OPCODE "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/Opcode.scala"
    click TESTCONFIG "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/TestConfig.scala"
    click TESTUTILS "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/TestUtils.scala"
    click TILETESTER "https://github.com/ucb-bar/riscv-mini/blob/main/src/test/scala/mini/TileTester.scala"
```
