# ibm/accdnn architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/accdnn
- Repository: https://github.com/ibm/accdnn

## Overview

Based on our careful review of the file tree and the README, the project is a domain‐specific compiler/automation tool that converts a Caffe-trained deep neural network into an FPGA-ready RTL design. In academic research, it is sometimes called “DNNBuilder,” and it ultimately generates a hardware accelerator (using Verilog, TCL, and related scripts) that implements the network with optimal FPGA resource usage. The project supports several demos (e.g., cifar10, ZF, alexnet, VGG16, YOLO) and includes both simulation and synthesis workflows.

##### Main Components
- Input & Parsing Module:
- Represents the components (e.g., “codegen.py”, “chip_define.py”, “model.py”) that parse the input Caffe network (prototxt and caffemodel files) to extract and estimate network topology and per-layer workload.
- Configuration files in the “conf” directory that drive decisions on hardware mapping (hardware.conf, operator.conf, optim.conf).
- Optimization & Configuration:
- Auto-optimization routines (through the optim_*.conf files and auto optimization process mentioned in the README) that set key parameters (CPF, KPF, batch size, DMA delay) for FPGA resource balancing.
- RTL/Verilog Generation Module:
- Code generation process – each network layer, based on the provided Caffe model, results in customized Verilog modules.
- This includes the instantiation of IP cores and on-chip memory generation (weights in the “coe” directory when running a build, plus scripts to generate IP cores like “ips.tcl” in the build output).
- The “lib/verilog” and “lib/ip” folders contain actual hardware descriptions that are used as building blocks.
- Synthesis & Deployment:
- Interaction with external FPGA design tools such as Xilinx Vivado, as well as the integration with Power-AI-Engine (optional) for POWER FPGA acceleration.
- How the tool’s execution leads to building the final bitstream.
- Simulation Environment:
- Simulation/testing aspect (folders “sim/”, “sim/tb”, “sim/wave”) which includes test benches and verification scripts.
- Tools for simulation data generation (e.g., tools/sim_data_gen.py) and comparison (tools/compare.py) verify correctness.
- Supporting Tools and Libraries:
- “layers” modules (for neural network layer definitions) and “tools” and “util” directories which provide helper scripts for activation plotting, comparing, mathematical utilities, etc.
- The “web” directory also provides support utilities (like packaging) for deployment if needed.

##### Relationships and Data Flow
- Caffe model files (prototxt, caffemodel) are ingested along with associated optim/config files.
- Next, “Parsing & Profiling” stage:
- The Python scripts (codegen.py, chip_define.py) parse the Caffe files.
- The parsed information then flows into the optimization module where necessary parameters (such as CPF/KPF, quantization constraints, batch size) are determined.
- “RTL Generation” stage:
- Automatic instantiation of layer-specific Verilog modules using the pre-built library (lib/ip, lib/verilog) occurs here.
- The outputs (Verilog source files, weight files, timing constraints) form the basis of the IP core.
- “Simulation & Verification” stage:
- “Synthesis & Deployment” stage:
- Finally, once verified, the output flows into FPGA synthesis tools (Vivado) to produce the bitstream.
- Optionally, integration with external acceleration platforms (Power-AI-Engine) can be depicted.

##### Architectural Patterns & Design Principles
- Modular Design:
- Notice the separation between front-end processing (model parsing, configuration management) and back-end code generation (Verilog, TCL IP scripts).
- Automated Mapping:
- The approach of automatically determining the parallelism (through CPF/KPF settings) can be highlighted.
- Layered Architecture:
- Separation of concerns among different functional layers – from network analysis, through RTL generation, to simulation and synthesis.
- Simulation & Verification Loop:
- Importance of simulation (with dedicated test benches) to verify the hardware before deployment.

##### Technologies, Frameworks, and Libraries
- Python is used extensively for parsing, configuration, code generation, and simulation data manipulation (files like util/, tools/, layers/).
- Verilog/SystemVerilog and TCL (for generating Xilinx IP cores) represent the hardware description and integration.
- Integration with Xilinx Vivado is mentioned explicitly, as well as optional IBM POWER FPGA acceleration support.
- Caffe (specifically the quantized version such as ristretto Caffe) is a core dependency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Parsing Stage
    subgraph "Input & Parsing Stage"
        A["Caffe Model & Config Files"]:::input
        B["codegen.py"]:::module
        C["chip_define.py"]:::module
        D["model.py"]:::module
        E["conf/hardware.conf"]:::module
        F["conf/operator.conf"]:::module
        G["conf/optim.conf.example"]:::module
        A --> B
        A --> E
        B --> D
        D --> C
        E --> F
        F --> G
        G --> X["Parsed Model"]:::module
    end

    %% Optimization & Configuration Stage
    subgraph "Optimization & Configuration Stage"
        H["util/optim.py"]:::module
    end

    %% RTL/Verilog Generation Stage
    subgraph "RTL/Verilog Generation Stage"
        I["lib/verilog"]:::lib
        J["lib/ip"]:::lib
    end

    %% Simulation & Verification Stage
    subgraph "Simulation & Verification Stage"
        K["sim/tb"]:::sim
        L["sim/wave"]:::sim
        M["tools/sim_data_gen.py"]:::sim
        N["tools/compare.py"]:::sim
    end

    %% Synthesis & Deployment Stage
    subgraph "Synthesis & Deployment Stage"
        O["bin/compile.sh"]:::synth
        P["bin/dnn2fpga.sh"]:::synth
        Q["bin/dnn2soc.sh"]:::synth
        R["bin/pie.sh"]:::synth
        S["Xilinx Vivado"]:::synth
        T["Power-AI-Engine"]:::synth
    end

    %% Supporting Tools & Libraries
    subgraph "Supporting Tools & Libraries"
        U["layers"]:::support
        V["tools"]:::support
        W["util"]:::support
        X_support["web"]:::support
    end

    %% Main Flow Connections
    X --> H
    H --> I
    H --> J
    I --> Y["RTL Design"]:::lib
    J --> Y
    Y --> K
    Y --> L
    K --> M
    L --> N
    N --> Z["Verified Design"]:::sim
    Z --> O
    O --> P
    P --> Q
    Q --> R
    R --> S
    S --> T
    Z -- "verification_feedback" --> Y

    %% Supporting Tools Influence (dashed connections)
    B --- U
    C --- U
    M --- V
    H --- W
    X --- X_support

    %% Click Events
    click B "https://github.com/ibm/accdnn/blob/master/codegen.py"
    click C "https://github.com/ibm/accdnn/blob/master/chip_define.py"
    click D "https://github.com/ibm/accdnn/blob/master/model.py"
    click E "https://github.com/ibm/accdnn/blob/master/conf/hardware.conf"
    click F "https://github.com/ibm/accdnn/blob/master/conf/operator.conf"
    click G "https://github.com/ibm/accdnn/blob/master/conf/optim.conf.example"
    click H "https://github.com/ibm/accdnn/blob/master/util/optim.py"
    click I "https://github.com/ibm/accdnn/tree/master/lib/verilog"
    click J "https://github.com/ibm/accdnn/tree/master/lib/ip"
    click K "https://github.com/ibm/accdnn/tree/master/sim/tb"
    click L "https://github.com/ibm/accdnn/tree/master/sim/wave"
    click M "https://github.com/ibm/accdnn/blob/master/tools/sim_data_gen.py"
    click N "https://github.com/ibm/accdnn/blob/master/tools/compare.py"
    click O "https://github.com/ibm/accdnn/blob/master/bin/compile.sh"
    click P "https://github.com/ibm/accdnn/blob/master/bin/dnn2fpga.sh"
    click Q "https://github.com/ibm/accdnn/blob/master/bin/dnn2soc.sh"
    click R "https://github.com/ibm/accdnn/blob/master/bin/pie.sh"
    click U "https://github.com/ibm/accdnn/tree/master/layers"
    click V "https://github.com/ibm/accdnn/tree/master/tools"
    click W "https://github.com/ibm/accdnn/tree/master/util"
    click X_support "https://github.com/ibm/accdnn/tree/master/web"

    %% Styles
    classDef input fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef module fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef lib fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef sim fill:#A3E4D7,stroke:#117864,stroke-width:2px;
    classDef synth fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef support fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
```
