# xilinx/plnx-aie-examples architecture

> Architecture diagram of the GitHub repository xilinx/plnx-aie-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xilinx/plnx-aie-examples
- Repository: https://github.com/xilinx/plnx-aie-examples

## Overview

##### Project type and purpose
- This is an embedded hardware–software co-design example repository for Xilinx/AMD devices. It demonstrates how to build and run an AIE-accelerated GeMM (General Matrix Multiply) application on a programmable SoC platform using Vitis and PetaLinux.
- Key purpose: illustrate end-to-end flow from AIE graph compilation and PL bitstream generation to PS application deployment (baremetal or Linux) and runtime data movement via GMIO.

##### File structure
- Top level
- designs/xgemm-gmio – the full AIE-GeMM design
- platforms – platform creation Tcl and Makefile for board support
- scripts/build_*.sh, settings.sh – build-flow bootstrap
- designs/xgemm-gmio subfolders
- aie/ – AI Engine dataflow graph code and kernels
- hw/ – PL system configuration (system.cfg) and Makefile to assemble xclbin
- ps/ – PS application for baremetal and Linux (linker scripts, Makefiles, xrt.ini)
- sw/ – helper scripts or host-side software (if any)

##### Extract architectural insights from README
- AIE graph defined in xgemm.h/xgemm.cpp, built with kernels in aie/kernels.
- system.cfg bridges PL (AXI, GMIO) and AIE routers.
- Two PS OS targets: Linux (using XRT, PetaLinux BSP) and baremetal.
- Build steps generate base platform, compile AIE, create PL bitstream, build PetaLinux, cross-compile PS, and package boot images.

##### Essential elements
- Clear labels: “Host Tools”, “PS (ARM+A53)”, “PL (FPGA)”, “AIE Array”, “DDR Memory”
- Rectangles in blue for hardware blocks (PL, AIE, DDR)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Environment
    subgraph "Build Environment"
        direction TB
        HOST["Host PC (Vitis & PetaLinux Tools)"]:::software
        SETTINGS["Global Settings (settings.sh)"]:::scripts
        BUILD_VCK["build_vck190_2023.1.sh"]:::scripts
        BUILD_VEK["build_vek280_es1_2023_1.sh"]:::scripts
        HOST -->|uses| SETTINGS
        SETTINGS --> BUILD_VCK
        SETTINGS --> BUILD_VEK
    end

    %% Platform Creation
    subgraph "Platform Creation"
        direction TB
        PLAT_TCL["platform_create.tcl"]:::scripts
        PLAT_MK["Makefile"]:::scripts
        BUILD_VCK --> PLAT_TCL
        PLAT_TCL --> PLAT_MK
    end

    %% Top-Level Integration
    subgraph "Top-Level Design"
        direction TB
        TL_MK["Makefile"]:::scripts
        TL_README["README.md"]:::scripts
        BUILD_VCK --> TL_MK
        TL_README
    end

    %% AIE Build Flow
    subgraph "AIE Build"
        direction TB
        AIE_MK["Makefile"]:::scripts
        TL_MK --> AIE_MK
        AIE_MK --> XGEMM_H
        AIE_MK --> XGEMM_CPP
        AIE_MK --> KCONFIG
        AIE_MK --> ONE_IN
        AIE_MK --> ONE_IN_AIE
        AIE_MK --> TWO_IN
        AIE_MK --> TWO_IN_AIE
        AIE_MK --> ONE_OUT
        AIE_MK --> ONE_OUT_AIE
    end

    XGEMM_H["xgemm.h"]:::software
    XGEMM_CPP["xgemm.cpp"]:::software
    KCONFIG["config.h"]:::software
    ONE_IN["one_input.cc"]:::software
    ONE_IN_AIE["one_input_aie.cc"]:::software
    TWO_IN["two_inputs.cc"]:::software
    TWO_IN_AIE["two_inputs_aie.cc"]:::software
    ONE_OUT["one_output.cc"]:::software
    ONE_OUT_AIE["one_output_aie.cc"]:::software

    %% PL System Configuration
    subgraph "PL System Configuration"
        direction TB
        SYSTEM_CFG["system.cfg"]:::hardware
        HW_MK["Makefile"]:::scripts
        TL_MK --> HW_MK
        HW_MK --> SYSTEM_CFG
    end

    %% PS Domain
    subgraph "PS Domain"
        direction TB
        subgraph "Baremetal OS"
            PS_BM_MK["Makefile"]:::scripts
            PS_BM_LD["lscript.ld"]:::scripts
        end
        subgraph "Linux OS"
            PS_LIN_MK["Makefile"]:::scripts
            PS_XRT["xrt.ini"]:::scripts
        end
        TL_MK --> PS_BM_MK
        TL_MK --> PS_LIN_MK
    end

    %% SW Helpers and Images
    subgraph "Software Helpers"
        direction TB
        SW_MK["Makefile"]:::scripts
        IMAGES["Reference Block Diagrams"]:::memory
        TL_MK --> SW_MK
        TL_MK --> IMAGES
    end

    %% PL Domain
    subgraph "PL Domain"
        direction TB
        subgraph "AIE Array" 
            direction TB
            AIE["AI Engine Array"]:::hardware
        end
        GMIO["GMIO Interface"]:::hardware
        AXI_INT["AXI Interconnect"]:::hardware
        DDR["Off-chip DDR Memory"]:::memory
        HW_MK --> GMIO
        SYSTEM_CFG --> GMIO
        SYSTEM_CFG --> AXI_INT
        AXI_INT --> DDR
    end

    %% Runtime and Configuration Flows
    HOST -->|builds| TL_MK
    TL_MK -->|generates .xclbin| PLAT_MK
    PS_LIN_MK -->|uses XRT| GMIO
    PS_BM_MK -->|streams data| GMIO
    GMIO -->|data flow| AIE
    AIE -->|AXI master| DDR
    DDR -->|reads/writes| PS_LIN_MK

    %% Click Events
    click XGEMM_H "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/xgemm.h"
    click XGEMM_CPP "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/xgemm.cpp"
    click KCONFIG "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/config.h"
    click ONE_IN "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/one_input.cc"
    click ONE_IN_AIE "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/one_input_aie.cc"
    click TWO_IN "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/two_inputs.cc"
    click TWO_IN_AIE "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/two_inputs_aie.cc"
    click ONE_OUT "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/one_output.cc"
    click ONE_OUT_AIE "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/aie/kernels/one_output_aie.cc"
    click AIE_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/aie/Makefile"
    click SYSTEM_CFG "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/hw/system.cfg"
    click HW_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/hw/Makefile"
    click PS_BM_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/ps/baremetal/Makefile"
    click PS_BM_LD "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/ps/baremetal/lscript.ld"
    click PS_LIN_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/ps/linux/Makefile"
    click PS_XRT "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/ps/linux/xrt.ini"
    click SW_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/sw/Makefile"
    click IMAGES "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/images/"
    click TL_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/designs/xgemm-gmio/Makefile"
    click TL_README "https://github.com/xilinx/plnx-aie-examples/blob/main/designs/xgemm-gmio/README.md"
    click PLAT_TCL "https://github.com/xilinx/plnx-aie-examples/blob/main/platforms/platform_create.tcl"
    click PLAT_MK "https://github.com/xilinx/plnx-aie-examples/tree/main/platforms/Makefile"
    click BUILD_VCK "https://github.com/xilinx/plnx-aie-examples/blob/main/build_vck190_2023.1.sh"
    click BUILD_VEK "https://github.com/xilinx/plnx-aie-examples/blob/main/build_vek280_es1_2023_1.sh"
    click SETTINGS "https://github.com/xilinx/plnx-aie-examples/blob/main/settings.sh"

    %% Styles
    classDef hardware fill:#ddeeff,stroke:#0088cc;
    classDef software fill:#ddffdd,stroke:#00aa00;
    classDef memory fill:#ffeedd,stroke:#cc6600,stroke-dasharray: 5 5;
    classDef scripts fill:#fffbcc,stroke:#ccbb00;
```
