# eki-project/finn-plus architecture

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

- Interactive diagram: https://gitdiagram.com/eki-project/finn-plus
- Repository: https://github.com/eki-project/finn-plus

## Overview

##### Project Type and Purpose
- This is an open-source, pipeline-driven “dataflow compiler” (FINN+) for building customized FPGA accelerators targeting quantized neural networks.
- It offers a Python-based CLI/API (“finn”), a layered transformation pipeline (ONNX → QONNX → fpgadataflow), a builder backend that emits HLS/C++/RTL, and hardware libraries (finn-rtllib) for Vivado/Vitis flows.

##### High-Level Component Breakdown
a. User Interface Layer
- CLI/Config: `finn` command, YAML build_config files, `installDependencies.sh`
- Python API: `src/finn/interface/run_finn.py`, utils for dependency & test management
b. Transformation Pipeline
- ONNX → QONNX passes: `src/finn/transformation/qonnx`
- Streaming-dataflow transformations: `src/finn/transformation/fpgadataflow`
- Streamline optimizations: `src/finn/transformation/streamline`
c. Builder / Code Generation
- Build orchestration: `src/finn/builder/build_dataflow.py`, `build_dataflow_steps.py`
- Custom step plugins: `src/finn/builder/custom_step_library`
- Dataflow export: C++ simulation, HLS IP packaging, Vivado/Vitis project generation
d. Hardware & Simulation Libraries
- Hardware IP templates & RTL: `finn-rtllib/axi`, `fifo`, `dwc`, `memstream`, `mvu`, etc.
- HLS C++ kernels & templates: `custom_hls/`
- XSI-based simulator engine: `finn_xsi/finn_xsi`
e. Analysis & Benchmarking
- Performance/QoR estimation: `src/finn/analysis/fpgadataflow`
- Throughput tests & simulation exec: `src/finn/core`
- Benchmark harnesses: `src/finn/benchmarking`
f. External Dependencies & Tools
- Xilinx tools: Vivado, Vitis HLS, Vitis SDK
- Python libraries: ONNX, Brevitas, PyYAML, numpy, etc.
- CI/Testing: GitHub Actions, GitLab CI, pytest in `tests/`

##### Relationships and Data Flow
- User invokes `finn build` (CLI) → Interface module reads YAML config
- Transformation pipeline modules apply successive graph rewrites to ONNX model
- Builder modules generate HLS/C++/RTL IP, script files, and Vivado/Vitis projects
- Hardware library IPs from finn-rtllib are instantiated into the design
- Xilinx tools synthesize & implement bitstream
- Python core and XSI engine run simulations; analysis modules collect performance data
- Benchmark scripts orchestrate on-hardware or simulated performance measurements

##### Architectural Patterns & Design Principles
- Layered/pipeline architecture: clear separation of interface, transformation, builder, and backend
- Plugin pattern: custom steps and custom_op libraries for extensibility
- Modular hardware library: reusable RTL/HLS blocks in finn-rtllib
- CI/test harness: comprehensive test suite ensures correctness at each layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        CLI["CLI / Config (installDependencies.sh)"]:::python
        API["Python CLI/API (run_finn.py)"]:::python
        Utils["Interface Utils\n(interface_utils.py,\nmanage_deps.py,\nmanage_tests.py)"]:::python
    end

    %% Transformation Pipeline
    subgraph "Transformation Pipeline"
        direction TB
        QONNX["ONNX → QONNX\n(src/finn/transformation/qonnx/)"]:::python
        FPGA["Streaming-dataflow\n(src/finn/transformation/fpgadataflow/)"]:::python
        SL["Streamline Opt.\n(src/finn/transformation/streamline/)"]:::python
    end

    %% Builder / Code Generation
    subgraph "Builder / Code Generation"
        direction TB
        Orchestrator["Build Orchestration\n(build_dataflow.py,\nbuild_dataflow_steps.py)"]:::python
        Config["Builder Config\n(build_dataflow_config.py)"]:::python
        Plugins["Custom Step Plugins\n(custom_step_library/)"]:::python
        Export["Dataflow Export\nHLS/C++/RTL emission"]:::python
    end

    %% Hardware & Simulation Libraries
    subgraph "Hardware & Simulation Libraries"
        direction TB
        HWLib["Hardware IP Library\n(finn-rtllib/)"]:::hardware
        HLSK["HLS C++ Kernels\n(custom_hls/)"]:::hardware
        XSI["XSI Simulator Engine\n(finn_xsi/finn_xsi/)"]:::hardware
    end

    %% Analysis & Benchmarking
    subgraph "Analysis & Benchmarking"
        direction TB
        Analysis["Perf/QoR Analysis\n(src/finn/analysis/fpgadataflow/)"]:::python
        CoreSim["Simulation & Throughput\n(src/finn/core/)"]:::python
        Bench["Benchmark Harnesses\n(src/finn/benchmarking/)"]:::python
    end

    %% External Dependencies & CI/Test
    subgraph "External & CI/Test"
        direction TB
        PYDeps["Python Libs\n(ONNX, Brevitas,\nPyYAML, numpy)"]:::external
        Xilinx["Xilinx Tools\n(Vivado, Vitis HLS,\nVitis SDK)"]:::external
        CI["CI Configs & Tests\n(.github/workflows/, .gitlab-ci.yml,\ntests/)"]:::ci
    end

    %% Data Flow Connections
    CLI -->|invokes| API
    API -->|reads YAML| Utils
    API -->|loads model| QONNX
    QONNX --> FPGA
    FPGA --> SL
    SL --> Orchestrator
    Orchestrator --> Config
    Orchestrator --> Plugins
    Orchestrator --> Export

    %% Builder branches
    Export -->|generate HLS IP| HLSK
    Export -->|assemble RTL IP| HWLib
    HLSK --> XSI
    HWLib --> Xilinx
    XSI --> CoreSim
    Xilinx --> Bench

    %% Analysis connections
    CoreSim --> Analysis
    Bench --> Analysis

    %% External dependencies
    PYDeps -.-> API
    PYDeps -.-> QONNX
    Xilinx -.-> HWLib
    Xilinx -.-> Export
    CI -.-> Utils
    CI -.-> QONNX
    CI -.-> Orchestrator
    CI -.-> Analysis

    %% Click Events
    click CLI "https://github.com/eki-project/finn-plus/blob/main/installDependencies.sh"
    click API "https://github.com/eki-project/finn-plus/blob/main/src/finn/interface/run_finn.py"
    click Utils "https://github.com/eki-project/finn-plus/blob/main/src/finn/interface/interface_utils.py"
    click Utils "https://github.com/eki-project/finn-plus/blob/main/src/finn/interface/manage_deps.py"
    click Utils "https://github.com/eki-project/finn-plus/blob/main/src/finn/interface/manage_tests.py"
    click QONNX "https://github.com/eki-project/finn-plus/tree/main/src/finn/transformation/qonnx/"
    click FPGA "https://github.com/eki-project/finn-plus/tree/main/src/finn/transformation/fpgadataflow/"
    click SL "https://github.com/eki-project/finn-plus/tree/main/src/finn/transformation/streamline/"
    click Orchestrator "https://github.com/eki-project/finn-plus/blob/main/src/finn/builder/build_dataflow.py"
    click Orchestrator "https://github.com/eki-project/finn-plus/blob/main/src/finn/builder/build_dataflow_steps.py"
    click Config "https://github.com/eki-project/finn-plus/blob/main/src/finn/builder/build_dataflow_config.py"
    click Plugins "https://github.com/eki-project/finn-plus/tree/main/src/finn/builder/custom_step_library/"
    click HWLib "https://github.com/eki-project/finn-plus/tree/main/finn-rtllib/"
    click HLSK "https://github.com/eki-project/finn-plus/tree/main/custom_hls/"
    click XSI "https://github.com/eki-project/finn-plus/tree/main/finn_xsi/finn_xsi/"
    click Analysis "https://github.com/eki-project/finn-plus/tree/main/src/finn/analysis/fpgadataflow/"
    click CoreSim "https://github.com/eki-project/finn-plus/tree/main/src/finn/core/"
    click Bench "https://github.com/eki-project/finn-plus/tree/main/src/finn/benchmarking/"
    click CI "https://github.com/eki-project/finn-plus/tree/main/tests/"
    click CI "https://github.com/eki-project/finn-plus/tree/main/.github/workflows/"
    click CI "https://github.com/eki-project/finn-plus/blob/main/.gitlab-ci.yml"

    %% Styles
    classDef python fill:#D0E1F9,stroke:#0366D6,color:#0366D6,stroke-width:1px
    classDef hardware fill:#D7F9D0,stroke:#2E7D32,color:#2E7D32,stroke-width:1px
    classDef external fill:#FFF4C1,stroke:#FF8F00,color:#FF8F00,stroke-width:1px
    classDef ci fill:#E0E0E0,stroke:#757575,color:#424242,stroke-width:1px
```
