# tusharkatole/ml-accelerator architecture

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

- Interactive diagram: https://gitdiagram.com/tusharkatole/ml-accelerator
- Repository: https://github.com/tusharkatole/ml-accelerator

## Overview

##### Project type and purpose
- This is a hardware accelerator (FPGA/ASIC) implementation and verification of a Non-Maximum Suppression (NMS) algorithm for object detection.
- It’s written in Verilog (`nms_top`, `calculate_iou` modules, variants with/without pipelining) and exercised by a Verilog testbench. A Python “Pre-Treatment Unit” extracts YOLO detections and a Python NMS script illustrate the algorithmic reference.

##### Main components
a. Host/Pre-Treatment (Python)
- Exports a `.coe` file to initialize on-chip Block RAM
b. Block RAM (`blk_mem_gen_0`)
- Synchronous read with 2-cycle output delay tracked by `delayed_addr_1/2`
c. nms_top (top-level Verilog)
- Addr Generator & BRAM interface
- Control FSM: LOAD_BOXES → SORT_INIT → SORT_BOXES/SORT_SWAP → INIT_NMS → COMPARE_BOXES → CALCULATE_IOU → UPDATE_VALID → FINISH
- Bubble-sort unit for ordering by score
- Valid/suppressed bitmaps
d. calculate_iou (submodule)
- Q8.8 fixed-point IoU computation
- Variants: combinational, 4-stage pipeline, 7-stage pipeline, approximate (A-IoU2 eliminates mult/div)
- Inputs: x1,y1,w1,h1, x2,y2,w2,h2 + start/reset/clk; Outputs: iou, done/valid
e. Testbench (Verilog)
- Drives clk/reset, waits for FSM = FINISH, monitors `suppressed` vector

##### Component interactions and data flows
- IoU result returns → FSM compares with `IOU_THRESHOLD` → sets `suppressed_reg[compare_box]` and clears `valid[compare_box]`.
- At FINISH, `suppressed_reg` holds final NMS mask output.

##### Key architectural patterns
- Central monolithic FSM orchestrating memory-load, sorting, comparison, suppression.
- Streaming hardware pipeline for IoU to maintain throughput (configurable pipeline depth).
- Dual-port Block RAM (read-only here) pre-initialized via `.coe`.
- Parameterized design: NUM_BOXES, IOU_THRESHOLD, DATA_WIDTH, ADDR_WIDTH, pipe stages.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Host
    Host["Host CPU / JTAG\n(Python Pre-Treatment)"]:::external
    Host -->|"BRAM init (.coe)"| BRAM

    %% BRAM
    BRAM(("blk_mem_gen_0\n2-cycle BRAM delay")):::memory
    BRAM -->|"data_out"| AddrGen

    %% nms_top block
    subgraph "nms_top (Top-Level Verilog)"
        direction TB

        AddrGen["Addr Gen & BRAM Interface"]:::control
        AddrGen -->|"addr"| BRAM
        AddrGen -->|"delayed_addr_1/2"| Delay

        Delay["Delay Registers\n(2-cycle)"]:::memory
        Delay -->|"boxes[][] & scores[]"| BoxRF

        BoxRF["Box Register File\n(boxes[NUM_BOXES][5], scores[])"]:::data
        BoxRF -->|"sorted data"| BubbleSort

        BubbleSort["Bubble Sort Unit\n(score-based swap)"]:::data
        BubbleSort -->|"sorted boxes"| FSM

        FSM["FSM Controller\nLOAD_BOXES → SORT_INIT → SORT_BOXES/SORT_SWAP → INIT_NMS → COMPARE_BOXES → CALCULATE_IOU → UPDATE_VALID → FINISH"]:::control
        FSM -->|"start/reset/clk"| IOUPipeline
        IOUPipeline -->|"done/valid"| FSM

        IOUPipeline["IOU Calculator Pipeline\n(7-stage pipelined Q8.8)"]:::data

        FSM -->|"valid bits"| ValidReg
        ValidReg["Valid/Suppression Registers\n(valid[], suppressed_reg[])"]:::data
        ValidReg -->|"suppressed[NUM_BOXES]"| Output
    end

    Output["Output Port\nsuppressed[NUM_BOXES]"]:::data

    %% Styles
    classDef control fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef data fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef memory fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
```
