# arc-research-lab/aim architecture

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

- Interactive diagram: https://gitdiagram.com/arc-research-lab/aim
- Repository: https://github.com/arc-research-lab/aim

## Overview

##### Project Type and Purpose
- This is an FPGA-centric heterogeneous computing research framework (“AIM”) for accelerating arbitrary-precision integer multiplication on AMD Versal ACAP.
- It comprises:
- A code‐generation/template engine (in “templete/”) that emits host, AIE graph, and PL kernel code based on user configs.
- Several reference applications under “application/” (IntegerMultiplication, RSA, Mandelbrot) demonstrating the generated accelerator.
- Build scripts (Makefile, build.sh), configuration files (.cfg), and Python tools (AIM.py, checkfreq.py, gen_array.py) to automate generation, synthesis, and frequency‐tuning.

##### File-Structure Analysis
- Top‐level:
- .github/workflows – CI for traffic plotting
- application/… – three sample apps, each with:
– src/: AIE kernels (aie_aim_*), graph (aie_graph.cpp/h), PL kernel, host.cpp
– tools/: frequency checker, array generator, Jinja templates
– system.cfg, Makefile, utils.mk
- templete/: the master template project with identical structure to application/, plus AIM.conf, AIM.py, build.sh
- assets/, images/: documentation assets
- Architectural pattern:
- Host (ARM CPU in SoC) ↔ AIE array (vector compute engines) ↔ PL fabric (fine-grain carry‐prop)
- Code generation (Jinja templates) for parameterized bitwidths and resource constraints
- Build pipeline uses Vitis/Vitis HLS toolchain and PetaLinux SDK

##### Key Architectural Insights from README
- AIM divides large‐integer multiply into many 32-bit chunks computed on AIE array; carry propagation offloaded to PL.
- Three phases: code generation (Python + Jinja) → host + AIE + PL synthesis → runtime execution.
- Users specify bitwidth and resource constraints in AIM.conf; template scripts handle timing/frequency adjustments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title
    title["AIM: Arbitrary-Precision Integer Multiplication on Versal ACAP"]

    %% Subgraph: Offline Code Generation
    subgraph "Offline Code Generation" 
        direction TB
        CFG["AIM.conf"]:::toolchain
        PY["AIM.py"]:::toolchain
        TPL_HOST["host.cpp.jinja"]:::toolchain
        TPL_PL["pl_kernel.cpp.jinja"]:::toolchain
        SYS_CFG["system.cfg"]:::toolchain
        SRC_TEMPLATE["Template Skeleton (src/)"]:::toolchain
        GEN_CODE["Generated Source"]:::codegen
        CFG -->|reads config| PY
        PY -->|renders templates| TPL_HOST
        PY --> TPL_PL
        PY --> SYS_CFG
        TPL_HOST --> GEN_CODE
        TPL_PL --> GEN_CODE
        SRC_TEMPLATE --> GEN_CODE
    end

    %% Subgraph: Build System
    subgraph "Build System" 
        direction TB
        VITIS["Vitis 2021.1"]:::toolchain
        HLS["Vitis HLS"]:::toolchain
        PETALINUX["PetaLinux SDK"]:::toolchain
        GEN_CODE --> VITIS
        GEN_CODE --> HLS
        GEN_CODE --> PETALINUX
    end

    %% Subgraph: Reference Applications
    subgraph "Reference Applications" 
        direction TB
        %% IntegerMultiplication
        subgraph "IntegerMultiplication" 
            direction TB
            IM_HOST["host.cpp"]:::frontend
            IM_AIE_GRAPH["aie_graph.cpp/h"]:::acc
            IM_AIE_K["AIE kernels"]:::acc
            IM_PL["pl_kernel.cpp"]:::pl
            IM_CFG["system.cfg"]:::toolchain
            IM_BUILD["Makefile/utils.mk"]:::toolchain
            IM_TOOLS["checkfreq.py & gen_array.py"]:::toolchain
            IM_HOST --> IM_AIE_GRAPH
            IM_AIE_GRAPH --> IM_AIE_K
            IM_AIE_K --> IM_PL
            IM_BUILD --> IM_HOST
        end
        %% RSA
        subgraph "RSA" 
            direction TB
            RSA_HOST["host.cpp"]:::frontend
            RSA_AIE_GRAPH["aie_graph.cpp/h"]:::acc
            RSA_AIE_K["AIE kernels"]:::acc
            RSA_PL["pl_kernel.cpp"]:::pl
            RSA_CFG["system.cfg"]:::toolchain
            RSA_BUILD["Makefile/utils.mk"]:::toolchain
            RSA_TOOLS["checkfreq.py & gen_array.py"]:::toolchain
            RSA_HOST --> RSA_AIE_GRAPH
            RSA_AIE_GRAPH --> RSA_AIE_K
            RSA_AIE_K --> RSA_PL
            RSA_BUILD --> RSA_HOST
        end
        %% Mandelbrot
        subgraph "Mandelbrot" 
            direction TB
            MB_HOST["host.cpp"]:::frontend
            MB_AIE_GRAPH["aie_graph.cpp/h"]:::acc
            MB_AIE_K["aie_aim.cc"]:::acc
            MB_PL["pl_kernel.cpp"]:::pl
            MB_CFG["system.cfg"]:::toolchain
            MB_BUILD["Makefile/utils.mk"]:::toolchain
            MB_TOOLS["checkfreq.py & gen_array.py"]:::toolchain
            MB_HOST --> MB_AIE_GRAPH
            MB_AIE_GRAPH --> MB_AIE_K
            MB_AIE_K --> MB_PL
            MB_BUILD --> MB_HOST
        end
    end

    %% Subgraph: Runtime Execution
    subgraph "Runtime Execution" 
        direction TB
        HOST["Host Processor\n(ARM CPU)"]:::frontend
        DDR["Shared DDR Memory"]:::mem
        AIE["AIE Array"]:::acc
        PL["PL Fabric"]:::pl
        HOST -->|"OpenCL API / AXI-DMA"| DDR
        DDR -->|"Input operands"| AIE
        AIE -->|"Partial products"| PL
        PL -->|"Results"| DDR
        DDR -->|"Final product"| HOST
    end

    %% Frequency Tuning Loop
    subgraph "Frequency Tuning Loop"
        direction TB
        CF["checkfreq.py"]:::toolchain
        BS["build.sh"]:::toolchain
        CF --> BS
        BS --> PETALINUX
        PETALINUX --> CF
    end

    %% CI and Docs
    subgraph "CI & Documentation"
        direction TB
        CI[".github/workflows\nGithubTrafficPlot.yml"]:::toolchain
        ASSETS["assets/ & images/"]:::mem
    end

    %% Connections
    GEN_CODE -->|feeds| IntegerMultiplication
    GEN_CODE -->|feeds| RSA
    GEN_CODE -->|feeds| Mandelbrot
    VITIS --> RuntimeExecution
    HLS --> RuntimeExecution
    PETALINUX --> RuntimeExecution
    CI --> GEN_CODE

    %% Click Events
    click CFG "https://github.com/arc-research-lab/aim/blob/main/templete/tools/AIM.conf"
    click PY "https://github.com/arc-research-lab/aim/blob/main/templete/tools/AIM.py"
    click TPL_HOST "https://github.com/arc-research-lab/aim/blob/main/templete/tools/host.cpp.jinja"
    click TPL_PL "https://github.com/arc-research-lab/aim/blob/main/templete/tools/pl_kernel.cpp.jinja"
    click SYS_CFG "https://github.com/arc-research-lab/aim/blob/main/templete/system.cfg"
    click SRC_TEMPLATE "https://github.com/arc-research-lab/aim/tree/main/templete/src/"
    click IM_HOST "https://github.com/arc-research-lab/aim/blob/main/application/IntegerMultiplication/src/host.cpp"
    click IM_AIE_GRAPH "https://github.com/arc-research-lab/aim/blob/main/application/IntegerMultiplication/src/aie_graph.cpp"
    click IM_AIE_K "https://github.com/arc-research-lab/aim/blob/main/application/IntegerMultiplication/src/aie_aim_bottom.cc"
    click IM_PL "https://github.com/arc-research-lab/aim/blob/main/application/IntegerMultiplication/src/pl_kernel.cpp"
    click IM_CFG "https://github.com/arc-research-lab/aim/blob/main/application/IntegerMultiplication/system.cfg"
    click IM_BUILD "https://github.com/arc-research-lab/aim/tree/main/application/IntegerMultiplication/Makefile"
    click IM_TOOLS "https://github.com/arc-research-lab/aim/blob/main/application/IntegerMultiplication/tools/checkfreq.py"
    click RSA_HOST "https://github.com/arc-research-lab/aim/blob/main/application/RSA/src/host.cpp"
    click RSA_AIE_GRAPH "https://github.com/arc-research-lab/aim/blob/main/application/RSA/src/aie_graph.cpp"
    click RSA_AIE_K "https://github.com/arc-research-lab/aim/blob/main/application/RSA/src/aie_aim_bottom.cc"
    click RSA_PL "https://github.com/arc-research-lab/aim/blob/main/application/RSA/src/pl_kernel.cpp"
    click RSA_CFG "https://github.com/arc-research-lab/aim/blob/main/application/RSA/system.cfg"
    click RSA_BUILD "https://github.com/arc-research-lab/aim/tree/main/application/RSA/Makefile"
    click RSA_TOOLS "https://github.com/arc-research-lab/aim/blob/main/application/RSA/tools/checkfreq.py"
    click MB_HOST "https://github.com/arc-research-lab/aim/blob/main/application/Mandelbrot/src/host.cpp"
    click MB_AIE_GRAPH "https://github.com/arc-research-lab/aim/blob/main/application/Mandelbrot/src/aie_graph.cpp"
    click MB_AIE_K "https://github.com/arc-research-lab/aim/blob/main/application/Mandelbrot/src/aie_aim.cc"
    click MB_PL "https://github.com/arc-research-lab/aim/blob/main/application/Mandelbrot/src/pl_kernel.cpp"
    click MB_CFG "https://github.com/arc-research-lab/aim/blob/main/application/Mandelbrot/system.cfg"
    click MB_BUILD "https://github.com/arc-research-lab/aim/tree/main/application/Mandelbrot/Makefile"
    click MB_TOOLS "https://github.com/arc-research-lab/aim/blob/main/application/Mandelbrot/tools/checkfreq.py"
    click CI "https://github.com/arc-research-lab/aim/blob/main/.github/workflows/GithubTrafficPlot.yml"
    click ASSETS "https://github.com/arc-research-lab/aim/tree/main/assets/"

    %% Styles
    classDef frontend fill:#C8FAD1,stroke:#333,stroke-width:1px
    classDef acc fill:#DFF7C4,stroke:#333,stroke-width:1px
    classDef pl fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef mem fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef toolchain fill:#BFDFFF,stroke:#333,stroke-width:1px
    classDef codegen fill:#D0E6FF,stroke:#333,stroke-width:1px
    class title fill:#FFF,stroke:none,font-weight:bold,font-size:16px
```
