# xilinx/finn architecture

> Architecture diagram of the GitHub repository xilinx/finn, 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/xilinx/finn
- Repository: https://github.com/xilinx/finn

## Overview

##### Project type and purpose
- FINN is an open-source compiler framework for generating FPGA dataflow accelerators from quantized neural networks (ONNX / Brevitas).
- It spans multiple abstraction levels: Python front-end, model transformations (QONNX → FINN IR), HLS code generation, Vivado/Vitis build, and optional runtime simulation or deployment on PYNQ/Zynq devices.

##### File structure
- Top-level directories & files:
- src/finn: core Python packages (analysis, builder, custom_op, transformation, util, qnn-data)
- custom_hls & finn-rtllib: custom C++ HLS sources and Verilog/Project IP library for generated accelerators
- docker & run-docker.sh: containerized execution environment & CI pipelines
- notebooks & tutorials: Jupyter-based examples illustrating usage and end-to-end FPGA flow
- docs: Sphinx documentation and READTHEDOCS config
- tests: unit and integration tests covering all functional layers
- Key patterns:
- Modular Python packages for transformation passes (QONNX → FPGA-DFG)
- Builder pattern orchestrating HLS code generation & IP stitching
- Layer-by-layer custom operator backends (HLS and RTL)
- External toolchain integration (Vitis HLS, Vivado) via configuration scripts

##### README for additional insights
- Emphasis on Docker‐only execution, Jupyter tutorials, and the “FINN stack” spanning ONNX import, dataflow IR, HLS, hardware IP libraries, and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Docker["Docker Container"]:::tool
    subgraph "User Interface Layer"
        CLI["CLI & Python API"]:::python
        Jupyter["Jupyter Notebooks"]:::python
    end
    ONNX["ONNX / Brevitas Import"]:::python
    QONNX["QONNX Passes"]:::ir
    DFG["FINN Dataflow IR Passes"]:::ir
    Builder["Dataflow Builder"]:::python
    subgraph "HLS Backend & Templates"
        HLSImp["HLS Operators"]:::hls
        Templates["Templates.py"]:::hls
    end
    subgraph "RTL Backend & IP Stitching"
        RTLImp["RTL Operators"]:::rtl
        CustomHLS["custom_hls"]:::rtl
        RTLLib["finn-rtllib"]:::rtl
    end
    Vitis["Vitis HLS Synthesis"]:::tool
    Vivado["Vivado Project & Bitstream"]:::tool
    Zynq["PYNQ/Zynq Project Generation"]:::tool
    FPGA["FPGA Target"]:::hw
    subgraph "Simulation & Runtime"
        RTLSim["Python RTL Simulation"]:::sim
        Throughput["Throughput/Test Executors"]:::sim
        PYNQDrv["PYNQ Driver"]:::sim
    end
    ONNXExt["ONNX & Brevitas"]:::ext
    PyTorch["PyTorch"]:::ext

    Docker --> CLI
    Docker --> Jupyter
    CLI --> ONNX
    Jupyter --> ONNX
    ONNX --> QONNX
    QONNX --> DFG
    DFG --> Builder
    Builder --> HLSImp
    Builder --> RTLImp
    HLSImp --> Vitis
    RTLImp --> Vitis
    Vitis --> Vivado
    Vivado --> Zynq
    Zynq --> FPGA
    DFG --> RTLSim
    DFG --> Throughput
    DFG --> PYNQDrv
    ONNXExt -.-> ONNX
    ONNXExt -.-> QONNX
    PyTorch -.-> ONNX

    click CLI "https://github.com/xilinx/finn/blob/main/setup.py"
    click Jupyter "https://github.com/xilinx/finn/tree/main/notebooks/"
    click ONNX "https://github.com/xilinx/finn/blob/main/src/finn/core/onnx_exec.py"
    click QONNX "https://github.com/xilinx/finn/tree/main/src/finn/transformation/qonnx/"
    click DFG "https://github.com/xilinx/finn/tree/main/src/finn/transformation/fpgadataflow/"
    click Builder "https://github.com/xilinx/finn/tree/main/src/finn/builder/"
    click HLSImp "https://github.com/xilinx/finn/tree/main/src/finn/custom_op/fpgadataflow/hls/"
    click Templates "https://github.com/xilinx/finn/blob/main/src/finn/custom_op/fpgadataflow/templates.py"
    click RTLImp "https://github.com/xilinx/finn/tree/main/src/finn/custom_op/fpgadataflow/rtl/"
    click CustomHLS "https://github.com/xilinx/finn/tree/main/custom_hls/"
    click RTLLib "https://github.com/xilinx/finn/tree/main/finn-rtllib/"
    click Vitis "https://github.com/xilinx/finn/blob/main/src/finn/transformation/fpgadataflow/vitis_build.py"
    click Vitis "https://github.com/xilinx/finn/blob/main/src/finn/util/hls.py"
    click Vivado "https://github.com/xilinx/finn/blob/main/src/finn/util/vivado.py"
    click Zynq "https://github.com/xilinx/finn/blob/main/src/finn/transformation/fpgadataflow/make_zynq_proj.py"
    click RTLSim "https://github.com/xilinx/finn/blob/main/src/finn/core/rtlsim_exec.py"
    click RTLSim "https://github.com/xilinx/finn/blob/main/src/finn/util/pyverilator.py"
    click Throughput "https://github.com/xilinx/finn/blob/main/src/finn/core/throughput_test.py"
    click PYNQDrv "https://github.com/xilinx/finn/blob/main/src/finn/transformation/fpgadataflow/make_pynq_driver.py"
    click PYNQDrv "https://github.com/xilinx/finn/blob/main/src/finn/qnn-data/templates/driver/driver_base.py"
    click Docker "https://github.com/xilinx/finn/blob/main/docker/Dockerfile.finn"
    click Docker "https://github.com/xilinx/finn/blob/main/run-docker.sh"

    classDef python fill:#D6EAF8,stroke:#5499C7;
    classDef ir fill:#D5F5E3,stroke:#27AE60;
    classDef hls fill:#FCF3CF,stroke:#F1C40F;
    classDef rtl fill:#FADBD8,stroke:#E74C3C;
    classDef tool fill:#EAECEE,stroke:#ABB2B9;
    classDef sim fill:#F5EEF8,stroke:#8E44AD;
    classDef hw fill:#EBDEF0,stroke:#9B59B6;
    classDef ext fill:#F2F3F4,stroke:#BDC3C7;
```
