# markcxli/fpga_dpu architecture

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

- Interactive diagram: https://gitdiagram.com/markcxli/fpga_dpu
- Repository: https://github.com/markcxli/fpga_dpu

## Overview

##### Project Type and Purpose
- This is a hardware-software co-design project that accelerates a state-of-the-art multiple-object-detection model (YOLOv2) on both GPU and FPGA. The host side runs the Darknet framework (C/C++ + CUDA) for inference, and a custom DPU (Deep Learning Processor Unit) on a Xilinx FPGA (via DNNDK) to measure performance and power/efficiency trade-offs.

##### File-Structure Analysis
- Top-level directories:
- YOLO/src       – Core Darknet code (C files, CUDA kernels, headers)
- YOLO/cfg       – Model configuration files (network definitions, dataset specs)
- YOLO/data      – Class names, label mappings, helper scripts for data prep
- YOLO/examples  – Example inference programs in C and Python
- YOLO/python    – Python wrappers (darknet.py) and utilities
- YOLO/scripts   – Shell/Python scripts for dataset downloading and label generation
- YOLO/include   – Public header (darknet.h)
- YOLO/libdarknet.a, YOLO/obj – Compiled library and object files

- Key build and deployment files: Makefile for host compilation; DNNDK APIs integrated in refactored code; Vivado-generated bitstream not in tree but implied by README flow.

##### README Insights
- Describes the Xilinx DPU IP and the DNNDK development flow: Vivado → bitstream → DPU driver → host application.

a. Main Components to Represent
- Host Application Layer
- Darknet Inference Engine (darknet.c, parser, network modules)
- Model Definitions (cfg/*.cfg, *.weights)
- DNNDK API Wrapper (refactored C using dnn_native_load, dpu_run)
- GPU Inference Path
- CUDA Kernels (src/*_kernels.cu)
- NVIDIA GPU + Device Memory
- FPGA Inference Path
- DPU IP on FPGA (PL logic: scheduler, compute array, global memory)
- Vivado-generated bitstream loaded into FPGA fabric
- DNNDK Driver in PS (processing system)
- PCIe / AXI interconnect + DDR memory
- Data Flow and Measurements
- Input Image Source (camera / file system)
- Performance Monitor (roofline, bandwidth calculator)

b. Relationships & Interactions
- Host App loads model + image → invokes either CUDA kernels or DNNDK calls
- GPU branch: host ↔ CUDA runtime ↔ GPU device memory ↔ CUDA kernels
- FPGA branch: host ↔ DPU driver ↔ PCIe/AXI ↔ DPU hardware ↔ DDR memory
- Results flow back to host, then to visualization or logging scripts

c. Architectural Patterns & Principles
- Accelerator Offload Pattern (host delegates heavy convolution workloads to GPU/FPGA)
- Modular Layered Design (parser, network, layers, utils separated in source)
- Hardware-Software Co-Design (C code + DNNDK API interfacing PL logic)

d. Key Technologies/Frameworks
- Darknet (C/C++ object-detection engine)
- CUDA (NVIDIA GPU kernels)
- Xilinx DPU IP (Vivado, bitstream)
- DNNDK (dnn_native_load, dpu_run, device driver)
- Python for scripting & prototyping (darknet.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input and Data Prep
    IMG["Input Image Source"]:::io
    subgraph "Data Preparation & Scripts"
        SCRIPTS["Data Prep Scripts"]:::io
        DATA["Dataset & Labels"]:::io
    end
    IMG -->|feeds| HostApp

    %% Host Application Layer
    subgraph "Host Application Layer"
        DE["Darknet Inference Engine"]:::software
        MD["Model Definitions"]:::software
        API["DNNDK API Wrapper"]:::software
        HDR["Public Header"]:::software
        LIB["Compiled Library & Objects"]:::software
        PY["Python Wrappers & Utilities"]:::software
        EX["Example Programs"]:::software
    end
    HostApp["Host Application"]:::software
    SCRIPTS --> HostApp
    DATA --> HostApp
    HostApp --> DE
    HostApp --> MD
    HostApp --> API
    HostApp --> HDR
    HostApp --> LIB
    HostApp --> PY
    HostApp --> EX

    %% GPU Inference Path
    subgraph "GPU Inference Path"
        CU_RT["CUDA Runtime"]:::software
        CU_K["CUDA Kernels"]:::software
        GPU_MEM["GPU Device Memory"]:::memory
        NVIDIA_GPU["NVIDIA GPU"]:::hardware
    end
    DE -->|uses| CU_RT
    CU_RT -->|launches| CU_K
    CU_K -->|loads data| GPU_MEM
    GPU_MEM --> NVIDIA_GPU
    NVIDIA_GPU -->|results| DE

    %% FPGA Inference Path
    subgraph "FPGA Inference Path"
        DNN_DRV["DNNDK Driver"]:::software
        PCIe["PCIe / AXI Interconnect"]:::hardware
        subgraph "DPU IP on FPGA"
            BS["Vivado Bitstream"]:::hardware
            DPU_SCH["DPU Scheduler"]:::hardware
            DPU_COMP["DPU Compute Array"]:::hardware
            DPU_MEM["DPU Global Memory"]:::memory
        end
        DDR["DDR Memory"]:::memory
    end
    API -->|calls| DNN_DRV
    DNN_DRV --> PCIe
    PCIe --> BS
    BS --> DPU_SCH
    DPU_SCH --> DPU_COMP
    DPU_COMP --> DPU_MEM
    DPU_MEM --> DDR
    DDR -->|results| API

    %% Performance Monitors
    subgraph "Performance Monitoring"
        PM_GPU["GPU Perf Monitor"]:::software
        PM_FPGA["FPGA Perf Monitor"]:::software
    end
    CU_K --> PM_GPU
    DPU_COMP --> PM_FPGA
    PM_GPU --> HostApp
    PM_FPGA --> HostApp

    %% Click Events
    click DE "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/src/"
    click MD "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/cfg/"
    click CU_RT "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/src/"
    click CU_K "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/src/"
    click API "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/src/"
    click HDR "https://github.com/markcxli/fpga_dpu/blob/master/YOLO/include/darknet.h"
    click LIB "https://github.com/markcxli/fpga_dpu/blob/master/YOLO/libdarknet.a"
    click PY "https://github.com/markcxli/fpga_dpu/blob/master/YOLO/python/darknet.py"
    click EX "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/examples/"
    click SCRIPTS "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/scripts/"
    click DATA "https://github.com/markcxli/fpga_dpu/tree/master/YOLO/data/"

    %% Styles
    classDef software fill:#e3f2fd,stroke:#64b5f6;
    classDef hardware fill:#e8f5e9,stroke:#66bb6a;
    classDef memory fill:#fff8e1,stroke:#ffb74d,stroke-dasharray: 5 5;
    classDef io fill:#f3e5f5,stroke:#ab47bc;
```
