# ucb-bar/gemmini architecture

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

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

## Overview

##### Project Type and Purpose
- Gemmini is a hardware‐accelerator generator and full‐stack DNN evaluation platform built on the Chipyard ecosystem.
- It uses Chisel (Scala DSL) to describe a RoCC accelerator that plugs into a RISC-V Rocket or BOOM core tile, enabling exploration of systolic‐array designs, DMA engines, scratchpads, and custom instructions for DNN workloads.

##### File Structure Analysis
- Top-level directories:
- `.github/` and CI scripts—deployment and testing workflows (Verilator, Spike).
- `modeling/`—static performance modeling (Timeloop integration).
- `scripts/`—build helpers for ONNX and training/inference images.
- `software/`—C libraries, test suites, ONNX-Runtime port, shell wrappers.
- `src/main/scala/gemmini/`—Chisel RTL modules (controllers, mesh, DMA, scratchpad, FIFO queues, TLB).
- `src/test/scala/gemmini/`—unit tests for RTL components.
- Build/config: `build.sbt`, `project/`, Scala style configs.

##### Key Architectural Insights from README
- Gemmini is a decoupled access/execute accelerator with three controllers: ExecuteController (systolic array + transposer), LoadController (DMA in to scratchpad/accumulator), and StoreController (DMA out + optional max-pooling).
- Private memories: Scratchpad (inputType banks) and Accumulator (accType banks + adders/scalers/activations).
- Systolic array organized as MeshWithDelays → Tiles → PEs, supporting weight- or output-stationary dataflows.
- Custom ISA: `mvin`/`mvout`, `config_*`, `matmul.preload`/`compute`, and higher-level CISC loop instructions.
- Connectivity: Gemmini attaches via the Rocket Chip RoCC interface to the TileLink system bus, sharing the L2 cache and memory‐subsystem.

- Labels: use clear, descriptive names (e.g., “ExecuteController”, “Scratchpad Bank”).
- Another for memory elements (SRAM banks, caches).
- A third for interconnect/bus.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Layer
    subgraph "Host CPU and Software"
        direction TB
        CPU["Host CPU<br/>(Rocket/BOOM)"]:::compute
        CLibrary["Gemmini C library"]:::software
        ONNX["ONNX-Runtime port"]:::software
        RoCCTests["RoCC instruction tests"]:::software
        CPU -->|"issues Gemmini ISA"| ExecuteController
        CPU -->|runs| CLibrary
        CPU -->|runs| ONNX
        CPU -->|runs| RoCCTests
    end

    %% Accelerator Layer
    subgraph "Gemmini Accelerator"
        direction TB
        ExecuteController["ExecuteController"]:::compute
        LoadController["LoadController"]:::compute
        StoreController["StoreController"]:::compute
        TLB["Frontend TLB / PTW"]:::memory
        SharedExtMem["TileLink System Bus"]:::bus

        ExecuteController -->|requests A,B loops| LoadController
        ExecuteController -->|sends compute config| StoreController
        LoadController -->|translates addr| TLB
        StoreController -->|translates addr| TLB
        LoadController -->|DMA read→Scratchpad| Scratchpad
        StoreController -->|DMA write→Bus| SharedExtMem
        ExecuteController -->|dispatch matmul| MeshWithDelays
        SharedExtMem -->|connects to| L2Cache
    end

    %% Systolic Array Layer
    subgraph "Systolic Array"
        direction TB
        MeshWithDelays["MeshWithDelays"]:::compute
        Mesh["Mesh"]:::compute
        Tile["Tile"]:::compute
        PE["PE"]:::compute
        Transposer["Transposer"]:::compute

        MeshWithDelays --> Mesh
        Mesh --> Tile
        Tile --> PE
        MeshWithDelays -->|uses| Transposer
    end

    %% Memory Layer
    subgraph "Local Memories"
        direction TB
        Scratchpad["Scratchpad SRAM banks"]:::memory
        AccMem["AccumulatorMem"]:::memory
        AccScale["AccumulatorScale"]:::memory
        Activation["Activation"]:::memory

        AccMem --> AccScale
        AccScale --> Activation
        MeshWithDelays -->|reads/writes C| AccMem
    end

    %% Shared Memory Hierarchy
    L2Cache["L2 Cache"]:::memory
    DRAM["DRAM"]:::memory
    SharedExtMem --> L2Cache
    L2Cache --> DRAM

    %% Simulation and Testing
    subgraph "Simulation & Testing"
        direction TB
        Verilator["Verilator & CI scripts"]:::sim
        Spike["Spike functional tests"]:::sim
        UnitTests["RTL unit tests"]:::sim

        Verilator -->|executes| UnitTests
        Spike -->|executes| RoCCTests
    end

    %% Click Events
    click ExecuteController "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/ExecuteController.scala"
    click LoadController "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/LoadController.scala"
    click StoreController "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/StoreController.scala"
    click MeshWithDelays "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/MeshWithDelays.scala"
    click Mesh "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/Mesh.scala"
    click Tile "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/Tile.scala"
    click PE "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/PE.scala"
    click Transposer "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/Transposer.scala"
    click Scratchpad "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/Scratchpad.scala"
    click AccMem "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/AccumulatorMem.scala"
    click AccScale "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/AccumulatorScale.scala"
    click Activation "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/Activation.scala"
    click DMA "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/DMA.scala"
    click DMATracker "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/DMACommandTracker.scala"
    click TLB "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/FrontendTLB.scala"
    click SharedExtMem "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/SharedExtMem.scala"
    click GemminiISA "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/GemminiISA.scala"
    click CustomCPUConfigs "https://github.com/ucb-bar/gemmini/blob/master/src/main/scala/gemmini/CustomCPUConfigs.scala"
    click CLibrary "https://github.com/ucb-bar/gemmini/tree/master/software/libgemmini"
    click ONNX "https://github.com/ucb-bar/gemmini/tree/master/software/onnxruntime-riscv"
    click RoCCTests "https://github.com/ucb-bar/gemmini/tree/master/software/gemmini-rocc-tests"
    click Verilator "https://github.com/ucb-bar/gemmini/blob/master/.github/scripts/run-tests-rtl.sh"
    click Spike "https://github.com/ucb-bar/gemmini/blob/master/.github/scripts/run-tests-spike.sh"
    click UnitTests "https://github.com/ucb-bar/gemmini/tree/master/src/test/scala/gemmini"
    click Timeloop "https://github.com/ucb-bar/gemmini/tree/master/modeling/timeloop"

    %% Styles
    classDef compute fill:#f9f,stroke:#333,stroke-width:1px
    classDef memory fill:#9ff,stroke:#333,stroke-width:1px
    classDef bus fill:#ff9,stroke:#333,stroke-width:1px
    classDef software fill:#cfc,stroke:#333,stroke-width:1px
    classDef sim fill:#fcc,stroke:#333,stroke-width:1px
```
