# eevaain/tiny-tpu architecture

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

- Interactive diagram: https://gitdiagram.com/eevaain/tiny-tpu
- Repository: https://github.com/eevaain/tiny-tpu

## Overview

##### Project type and purpose
- This is a hardware-design project written in SystemVerilog that implements a minimal Tensor Processing Unit (TPU) featuring a weight-stationary systolic array.
- Purpose: to perform efficient matrix multiplications via a 2×2 grid of Processing Elements (PEs), orchestrated by a Control Unit, with on-chip Unified Buffer and Weight Memory for data storage and a DMA interface for external I/O.

##### File structure
- Top-level files:
- Makefile, .gitignore, README.md (project metadata)
- .gtkw files under root (GTKWave configurations for inspecting various modules)
- img/ (architecture and PE illustrations)
- src/ (all RTL modules):
- control_unit.sv
- tpu.sv (top-level TPU wrapper)
- tt_um_tpu.sv (probably a test-top or unified-module wrapper)
- dma.sv (external memory interface)
- unified_buffer.sv
- weight_memory.sv
- input_setup.sv
- mmu.sv (Matrix Multiply Unit wrapper that instantiates PEs and accumulators)
- processing_element.sv
- accumulator.sv
- test/ (unit tests and dump scripts):
- dump_*.sv (Verilog dump benches per module)
- test_*.py (pytest harness)

##### README for additional insights
- The README defines the high-level architecture:
1. Control Unit
2. Unified Buffer
3. Weight Memory
4. Input Activation Setup
5. Matrix Multiply Unit (2×2 PEs + 2 accumulators)
6. Interface (DMA)
- Data-flow steps and instruction set (LOAD_ADDR, LOAD_WEIGHTS, LOAD_INPUT, COMPUTE, STORE_RESULTS, NOP) are described.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    External["External Host / Off-chip Memory"]:::external

    %% I/O Layer
    subgraph "I/O Interface"
        DMA["DMA Interface\n(dma.sv)"]:::io
    end

    %% Storage Layer
    subgraph "On-Chip Storage"
        UB["Unified Buffer\n(unified_buffer.sv)"]:::storage
        WM["Weight Memory\n(weight_memory.sv)"]:::storage
    end

    %% Input Setup
    subgraph "Input Activation"
        IS["Input Activation Setup\n(input_setup.sv)"]:::storage
    end

    %% Compute Layer
    subgraph "Matrix Multiply Unit\n(mmu.sv)" 
        direction TB
        subgraph "2×2 PE Array"
            direction LR
            PE00["PE (0,0)\n(processing_element.sv)"]:::compute
            PE01["PE (0,1)\n(processing_element.sv)"]:::compute
            PE10["PE (1,0)\n(processing_element.sv)"]:::compute
            PE11["PE (1,1)\n(processing_element.sv)"]:::compute
        end
        subgraph "Accumulators"
            ACC0["Accumulator\n(accumulator.sv)"]:::compute
            ACC1["Accumulator\n(accumulator.sv)"]:::compute
        end
    end

    %% Control Layer
    subgraph "Control Unit\n(control_unit.sv)" 
        ControlMem["Instruction Memory"]:::control
    end

    %% Top-Level Wrappers
    subgraph "Top-Level Wrappers"
        TPU["TPU Wrapper\n(tpu.sv)"]:::control
        UMTPU["Unified/Test Top\n(tt_um_tpu.sv)"]:::control
    end

    %% Connections
    External -->|read/write requests| DMA
    DMA -->|load inputs / store results| UB
    DMA -->|load weights| WM

    ControlMem -->|op-codes & control| DMA
    ControlMem -->|op-codes & control| UB
    ControlMem -->|op-codes & control| WM
    ControlMem -->|op-codes & control| IS
    ControlMem -->|op-codes & control| PE00
    ControlMem -->|op-codes & control| PE01
    ControlMem -->|op-codes & control| PE10
    ControlMem -->|op-codes & control| PE11

    UB -->|activations| IS
    IS -->|activations| PE00
    IS -->|activations| PE10

    WM -->|weights| PE00
    WM -->|weights| PE01

    PE00 -->|partial sums| PE01
    PE10 -->|partial sums| PE11
    PE01 -->|column sum| ACC0
    PE11 -->|column sum| ACC1

    ACC0 -->|results| UB
    ACC1 -->|results| UB

    TPU --> ControlMem
    TPU --> DMA
    TPU --> UB
    TPU --> WM
    TPU --> IS
    TPU --> PE00
    UMTPU --> TPU

    %% Click events
    click ControlMem "https://github.com/eevaain/tiny-tpu/blob/main/src/control_unit.sv"
    click UB "https://github.com/eevaain/tiny-tpu/blob/main/src/unified_buffer.sv"
    click WM "https://github.com/eevaain/tiny-tpu/blob/main/src/weight_memory.sv"
    click IS "https://github.com/eevaain/tiny-tpu/blob/main/src/input_setup.sv"
    click MMU "https://github.com/eevaain/tiny-tpu/blob/main/src/mmu.sv"
    click PE00 "https://github.com/eevaain/tiny-tpu/blob/main/src/processing_element.sv"
    click PE01 "https://github.com/eevaain/tiny-tpu/blob/main/src/processing_element.sv"
    click PE10 "https://github.com/eevaain/tiny-tpu/blob/main/src/processing_element.sv"
    click PE11 "https://github.com/eevaain/tiny-tpu/blob/main/src/processing_element.sv"
    click ACC0 "https://github.com/eevaain/tiny-tpu/blob/main/src/accumulator.sv"
    click ACC1 "https://github.com/eevaain/tiny-tpu/blob/main/src/accumulator.sv"
    click DMA "https://github.com/eevaain/tiny-tpu/blob/main/src/dma.sv"
    click TPU "https://github.com/eevaain/tiny-tpu/blob/main/src/tpu.sv"
    click UMTPU "https://github.com/eevaain/tiny-tpu/blob/main/src/tt_um_tpu.sv"

    %% Styles
    classDef storage fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef compute fill:#d4edda,stroke:#333,stroke-width:1px
    classDef control fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef io fill:#e2d6f3,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
```
