From 6a1d3fa5a2b0b0929274c0a2105ce2edbe2bb54f Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Wed, 20 May 2026 15:54:48 -0700
Subject: [PATCH 1/7] feat(vitis/aie): Vitis Unified AIE archetype + helpers +
 Sphinx docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an end-to-end Vitis Unified AIE build archetype mirroring the
existing `system_vitis_unified_hls.mk` conventions, so downstream
firmware repos can drop locally-vendored AIE makefiles.

* `system_vitis_unified_aie.mk` — proj/build/x86sim/package/program/
  gui/interactive/test/clean targets driven by the Vitis 2025.1+
  Unified Python API. Self-contained: `make package` writes the
  dynamic PDI to `$(PROJ_DIR)/ip/$(PROJECT)_aie_dynamic.pdi`.
  - Caller contract: exactly one of AIE_PLATFORM (xpfm) or AIE_PART
    (Versal device ID); AIE_SOURCES (whitespace-separated file/dir
    paths, directories imported flat and non-recursive);
    AIE_TOP_LEVEL_FILE basename; AIE_XSA_INPUT (package only) and
    AIE_DTBO/AIE_BOARD_IP (program only) at recipe time.
  - aie_config.cfg location hardcoded at `$(PROJ_DIR)/aie_config.cfg`
    matching the unified HLS hls_config.cfg convention.
  - TOP_DIR defaults to `$(PWD)/../..` for the standard
    firmware/<category>/<name>/Makefile layout.

* vitis/aie/ helpers:
  - create_proj.py — Vitis Python API workspace + AIE component
    creation, idempotent.
  - build.py — hw target by default, --x86sim for the simulator.
  - package.sh — `v++ --package` primary, bootgen fallback when
    USE_BOOTGEN_FALLBACK=1.
  - program.sh — generic Versal/PetaLinux deploy (scp PDI+DTBO,
    reboot, verify fpga_manager state). Refuses *_static.pdi as a
    runtime overlay. Project-specific helpers override via
    AIE_PROGRAM_SCRIPT honoring the -p/-d/-i flag contract.

* Sphinx docs:
  - docs/how-to/vitis_aie.rst — walkthrough, prerequisites, project
    layout, steps, deploy-step customisation, troubleshooting.
  - docs/reference/makefile_reference.rst — Vitis AIE targets table
    and per-variable reference for every AIE_* knob.

* system_vitis_unified_hls.mk: add one-line comment clarifying that
  VIVADO_VERSION feeds BUILD_STRING in system_shared.mk; same shape
  as the comment in the new AIE Makefile fragment.

Hardware-validated against Simple-VEK280-Example AIE-loopback:
byte-identical *_aie_dynamic.pdi, end-to-end make build / package /
program cycle with /sys/class/fpga_manager/fpga0/state == operating
post-deploy.
---
 docs/how-to/index.rst                 |   1 +
 docs/how-to/vitis_aie.rst             | 384 ++++++++++++++++++++++++++
 docs/reference/makefile_reference.rst | 215 +++++++++++++-
 system_vitis_unified_aie.mk           | 226 +++++++++++++++
 system_vitis_unified_hls.mk           |   1 +
 vitis/aie/build.py                    |  39 +++
 vitis/aie/create_proj.py              | 117 ++++++++
 vitis/aie/package.sh                  |  93 +++++++
 vitis/aie/program.sh                  | 207 ++++++++++++++
 9 files changed, 1279 insertions(+), 4 deletions(-)
 create mode 100644 docs/how-to/vitis_aie.rst
 create mode 100644 system_vitis_unified_aie.mk
 create mode 100644 vitis/aie/build.py
 create mode 100644 vitis/aie/create_proj.py
 create mode 100644 vitis/aie/package.sh
 create mode 100644 vitis/aie/program.sh

diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
index 8833eb6..dd315b8 100644
--- a/docs/how-to/index.rst
+++ b/docs/how-to/index.rst
@@ -11,6 +11,7 @@ setting up a project for the first time, see
 
    vivado_build
    vitis_hls
+   vitis_aie
    ghdl_simulation
    cadence_genus
    synopsys_dc
diff --git a/docs/how-to/vitis_aie.rst b/docs/how-to/vitis_aie.rst
new file mode 100644
index 0000000..6d8348b
--- /dev/null
+++ b/docs/how-to/vitis_aie.rst
@@ -0,0 +1,384 @@
+How to Build a Vitis AI Engine (AIE) Graph
+============================================
+
+**Goal:** Compile an AI Engine graph from C++ sources, package the resulting
+``libadf.a`` against a Vivado-built ``.xsa`` into a dynamic PDI, and (optionally)
+deploy the PDI + matching device-tree overlay to a Versal/PetaLinux board.
+
+.. note::
+
+   This backend (``system_vitis_unified_aie.mk``) requires the **Vitis 2025.1 or
+   newer** unified toolchain. It is driven by the Vitis Python API
+   (``vitis -s <script>.py``) — mirroring :doc:`vitis_hls`'s unified backend so
+   the same workspace can be opened batch-style for CI and GUI-style for
+   debugging.
+
+Prerequisites
+-------------
+
+- ``vitis`` binary on PATH (Vitis 2025.1+ unified toolchain)
+- ``XILINX_VITIS`` environment variable exported (the Makefile asserts on this
+  at parse time)
+- A Vivado-built ``.xsa`` from the companion target (required by ``make package``
+  only — not by ``make proj`` / ``make build``)
+- An ``aie_config.cfg`` at ``$(PROJ_DIR)/aie_config.cfg`` (same convention as
+  the unified HLS flow's ``hls_config.cfg``)
+- Makefile includes ``system_vitis_unified_aie.mk``
+
+Project Layout
+--------------
+
+ruckus's standard convention is to keep the Vivado target and the AIE
+component in **separate** project directories (mirroring how Vitis HLS targets
+are split out from Vivado targets). A typical tree:
+
+.. code-block:: none
+
+   firmware/
+     submodules/ruckus/
+     shared/
+       <AieProject>/
+         Makefile               <- includes system_vitis_unified_aie.mk
+         aie_config.cfg         <- [aie] pl-freq=…, Xpreproc=…
+         aie/
+           graph.cpp
+           graph.h
+           kernels/
+             *.cc *.h
+     targets/
+       <VivadoTarget>/
+         Makefile               <- includes system_vivado.mk; produces the .xsa
+
+The AIE project is fully self-contained: ``make package`` writes the final
+dynamic PDI to ``$(PROJ_DIR)/ip/`` (matching the HLS convention of writing
+deliverables into ``ip/``) so the Vivado target does not need to know where
+the AIE archetype lives on disk.
+
+Makefile include line:
+
+.. code-block:: makefile
+
+   include $(TOP_DIR)/submodules/ruckus/system_vitis_unified_aie.mk
+
+A minimal consumer ``Makefile`` looks like:
+
+.. code-block:: makefile
+
+   target: build
+
+   export AIE_SOURCES = \
+       $(abspath $(CURDIR)/aie) \
+       $(abspath $(CURDIR)/aie/kernels)
+
+   export AIE_TOP_LEVEL_FILE = graph.cpp
+
+   # Wildcard picks up the xpfm the active Vitis release ships
+   # (xilinx_vek280_base_202510_1 in 2025.1, _202520_1 in 2025.2, …)
+   export AIE_PLATFORM := $(firstword $(wildcard \
+       $(XILINX_VITIS)/base_platforms/xilinx_vek280_base_*/xilinx_vek280_base_*.xpfm))
+
+   AIE_BOARD_IP ?= root@10.0.0.191
+
+   include ../../submodules/ruckus/system_vitis_unified_aie.mk
+
+Steps
+-----
+
+1. Create the workspace and AIE component:
+
+   .. code-block:: bash
+
+      make proj
+
+   Idempotent — re-running is a cheap no-op if the component already exists,
+   so ``make build`` and ``make gui`` declare ``proj`` as a prereq freely.
+
+2. Build the graph for hardware:
+
+   .. code-block:: bash
+
+      make build
+
+   Emits ``libadf.a`` under ``$(OUT_DIR)/$(PROJECT)/build/hw/``.
+
+3. Or run the x86 simulator instead of the AIE compiler:
+
+   .. code-block:: bash
+
+      make x86sim
+
+4. Wrap ``libadf.a`` + the Vivado ``.xsa`` into a dynamic PDI:
+
+   .. code-block:: bash
+
+      make AIE_XSA_INPUT=<absolute-path-to>.xsa package
+
+   ``AIE_XSA_INPUT`` is supplied on the command line because the Vivado-side
+   ``IMAGENAME`` embeds ``BUILD_TIME``, so the ``.xsa`` filename produced by
+   an earlier Vivado run is not predictable from inside the AIE archetype.
+
+   The package step's output is ``$(AIE_PDI)`` —
+   ``$(PROJ_DIR)/ip/$(PROJECT)_aie_dynamic.pdi`` by default.
+
+5. Deploy the PDI + matching DTBO to a Versal/PetaLinux board:
+
+   .. code-block:: bash
+
+      make AIE_DTBO=<absolute-path-to>.dtbo \
+           AIE_BOARD_IP=root@<board-ip> \
+           program
+
+   The default deploy helper (``$(RUCKUS_DIR)/vitis/aie/program.sh``) scp's
+   the PDI and DTBO to ``/boot/{pl.pdi,pl.dtbo}``, reboots the board, waits
+   for ssh liveness, then verifies ``/sys/class/fpga_manager/fpga0/state``
+   reports ``operating``.
+
+6. Open the same workspace interactively in the Vitis IDE:
+
+   .. code-block:: bash
+
+      make gui
+
+   Or drop into a Python REPL with the ``vitis`` module pre-loaded:
+
+   .. code-block:: bash
+
+      make interactive
+
+**Output:** dynamic PDI at ``$(PROJ_DIR)/ip/$(PROJECT)_aie_dynamic.pdi``.
+
+Available Targets
+-----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 78
+
+   * - Target
+     - Action
+   * - ``make proj``
+     - Create the workspace + AIE component (``vitis -s create_proj.py``).
+       No-op if the component already exists.
+   * - ``make build``
+     - Build for the ``hw`` target (``vitis -s build.py``). Emits
+       ``libadf.a`` under ``$(OUT_DIR)/$(PROJECT)/build/hw/``.
+   * - ``make x86sim``
+     - Build for the x86 simulator (``vitis -s build.py --x86sim``).
+   * - ``make package``
+     - Wrap ``libadf.a`` + ``$(AIE_XSA_INPUT)`` into the dynamic PDI
+       (``bash package.sh``). Uses ``v++ --package`` (primary) or
+       ``bootgen`` (fallback when ``USE_BOOTGEN_FALLBACK=1``).
+   * - ``make program``
+     - Invoke ``$(AIE_PROGRAM_SCRIPT)`` to deploy ``$(AIE_PDI)`` and
+       ``$(AIE_DTBO)`` to ``$(AIE_BOARD_IP)``.
+   * - ``make gui``
+     - Open the same workspace in the Vitis Unified IDE
+       (``vitis -w $(OUT_DIR)``).
+   * - ``make interactive``
+     - Drop into a Python REPL with the ``vitis`` module loaded
+       (``vitis -i``).
+   * - ``make test``
+     - Print all AIE-related environment variables — useful for
+       diagnosing Makefile variable resolution.
+   * - ``make clean``
+     - Delete the build directory (``rm -rf $(OUT_DIR)``).
+
+Caller Contract
+---------------
+
+The consuming target's AIE Makefile must define these **before** including
+``system_vitis_unified_aie.mk``:
+
+**Exactly one of:**
+
+- :envvar:`AIE_PLATFORM` — absolute path to the platform ``.xpfm``. Use this
+  for dev boards with an AMD-shipped xpfm
+  (e.g. ``$(XILINX_VITIS)/base_platforms/xilinx_vek280_base_*/...xpfm``).
+- :envvar:`AIE_PART` — Versal device ID. Use this for custom AIE boards
+  without a shipped xpfm (e.g. ``xcve2802-vsvh1760-2MP-e-S``). The PL clock
+  hint comes from the cfg's ``pl-freq=`` line instead of the xpfm.
+
+Plus:
+
+- :envvar:`AIE_SOURCES` — whitespace-separated list of source paths. Each
+  entry is either:
+
+  - a **file** path → imports just that file, **or**
+  - a **directory** path → imports every ``.cpp`` / ``.cc`` / ``.h`` /
+    ``.hpp`` file in that directory (**non-recursive** — subdirectories are
+    not walked).
+
+  All imports land **flat** at the component root. This mirrors the trust
+  model of HLS's ``hls_config.cfg`` (``syn.file=`` / ``tb.file=``) — the
+  application owns the source list; ruckus does no Python-side recursive
+  globbing.
+
+  Mix local and shared sources freely:
+
+  .. code-block:: makefile
+
+     SHARED_AIE := $(TOP_DIR)/submodules/aie-common-kernels
+     export AIE_SOURCES = \
+         $(CURDIR)/aie \
+         $(CURDIR)/aie/kernels \
+         $(SHARED_AIE)/util.cc
+
+  The first entry pulls in everything directly under ``aie/``; the second
+  pulls in everything under ``aie/kernels/``; the third names one file from
+  a submodule.
+
+- :envvar:`AIE_TOP_LEVEL_FILE` — top-level graph file **basename** only
+  (e.g. ``graph.cpp``), because all imports land flat at the component root.
+
+And on the command line (recipe-time, not parse-time):
+
+- :envvar:`AIE_XSA_INPUT` — absolute path to the Vivado-built ``.xsa``,
+  required by the ``package`` target.
+- :envvar:`AIE_DTBO` — absolute path to the matching ``.dtbo``, required by
+  the ``program`` target.
+- :envvar:`AIE_BOARD_IP` — ``user@host`` for the ``program`` target.
+  Forwarded to ``$(AIE_PROGRAM_SCRIPT)`` as the ``-i`` flag.
+
+aie_config.cfg
+--------------
+
+The consuming Makefile must also provide an ``aie_config.cfg`` file at
+``$(PROJ_DIR)/aie_config.cfg`` — **next to the Makefile itself**. This
+location is hardcoded (not configurable), mirroring the unified HLS flow's
+``hls_config.cfg`` convention. The cfg's ``[aie]`` section carries
+``pl-freq=`` and any other ``aiecompiler`` options:
+
+.. code-block:: ini
+
+   [aie]
+   pl-freq=250
+   xlopt=1
+   verbose=true
+   # Xpreproc=-DMY_MACRO=value
+
+When ``AIE_PART`` is in use (no xpfm), the ``pl-freq=`` line is the **only**
+hint Vitis has for the PL clock frequency, so it must be set.
+
+Customising the Deploy Step
+---------------------------
+
+``make program`` invokes ``$(AIE_PROGRAM_SCRIPT)``, which defaults to
+``$(RUCKUS_DIR)/vitis/aie/program.sh`` — a generic Versal/PetaLinux deploy
+helper that:
+
+1. Pre-flights the PDI/DTBO paths and ssh reachability
+2. Refuses to upload a ``*_static.pdi`` filename (which belongs in
+   ``BOOT.BIN``, not as a runtime overlay)
+3. ``scp``'s ``$(AIE_PDI)`` → ``$(AIE_BOARD_IP):/boot/pl.pdi`` and
+   ``$(AIE_DTBO)`` → ``$(AIE_BOARD_IP):/boot/pl.dtbo``
+4. Reboots the board (skippable with ``-r``)
+5. Waits for ssh liveness, then verifies
+   ``/sys/class/fpga_manager/fpga0/state == operating``
+
+Projects that need richer verification (application-specific systemd
+checks, ``xsdb`` readout, etc.) override the default by pointing
+:envvar:`AIE_PROGRAM_SCRIPT` at their own helper. The override must accept
+the same flag contract:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 82
+
+   * - Flag
+     - Meaning
+   * - ``-p <path>``
+     - Runtime PDI to upload (required)
+   * - ``-d <path>``
+     - Matching device-tree overlay (required)
+   * - ``-i <user@host>``
+     - Board target (forwarded from ``$(AIE_BOARD_IP)`` when set)
+
+The default helper additionally accepts ``-r`` (dry-run: skip reboot) and
+``-h`` (show help); custom helpers may ignore those if not relevant. The
+helper's exit codes follow the convention 0 = success, 1 = local pre-flight
+failed, 2 = scp/ssh failure, 3 = post-reboot verification failed.
+
+Key Variables
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 22 52
+
+   * - Variable
+     - Default
+     - Description
+   * - ``OUT_DIR``
+     - ``$(PROJ_DIR)/build``
+     - Vitis workspace root. The AIE component lives at
+       ``$(OUT_DIR)/$(PROJECT)/``.
+   * - ``AIE_IP_DIR``
+     - ``$(PROJ_DIR)/ip``
+     - Final deliverable directory (matches the HLS convention).
+   * - ``AIE_PDI``
+     - ``$(AIE_IP_DIR)/$(PROJECT)_aie_dynamic.pdi``
+     - Output dynamic PDI path written by ``make package``.
+   * - ``AIE_PKG_DIR``
+     - ``$(OUT_DIR)/aie_package``
+     - Scratch directory used by the package step.
+   * - ``USE_BOOTGEN_FALLBACK``
+     - ``0``
+     - Set to ``1`` to package via ``bootgen`` instead of ``v++ --package``.
+   * - ``VPP_LOG``
+     - ``$(OUT_DIR)/vpp_package.log``
+     - Log file path for the ``v++ --package`` invocation.
+   * - ``AIE_PROGRAM_SCRIPT``
+     - ``$(RUCKUS_DIR)/vitis/aie/program.sh``
+     - Deploy helper invoked by ``make program``. Override for project-
+       specific verification.
+
+See :doc:`../reference/makefile_reference` for the full AIE variable
+reference.
+
+Troubleshooting
+---------------
+
+**"XILINX_VITIS not set"**
+   The Makefile hard-fails at parse time if the Vitis environment was not
+   sourced. Source the Vitis settings script (or a SLAC-local wrapper like
+   ``setup_env_slac.sh``):
+
+   .. code-block:: bash
+
+      source /path/to/Vitis/settings64.sh
+      vitis --version    # confirm 2025.1 or newer
+
+**"Define either AIE_PLATFORM or AIE_PART"**
+   Set exactly one. ``AIE_PLATFORM`` for dev boards with an AMD-shipped
+   ``.xpfm``; ``AIE_PART`` for custom Versal AIE boards without one.
+
+**"AIE_XSA_INPUT not set"**
+   Only the ``package`` target requires the ``.xsa``. Pass it on the
+   command line — do not bake an ``IMAGENAME``-derived path into the
+   Makefile, because the upstream Vivado ``IMAGENAME`` embeds
+   ``BUILD_TIME`` and is not predictable from this archetype.
+
+**"AIE_DTBO not set"**
+   ``make program`` requires the matching device-tree overlay path.
+   Typically lives next to the Vivado ``.xsa`` under the upstream target's
+   ``images/`` directory.
+
+**"Refusing to upload static PDI as runtime overlay"**
+   The default deploy helper refuses any ``-p`` argument containing
+   ``_static`` in the filename. ``<name>_static.pdi`` is the ``BOOT.BIN``
+   half of a segmented-configuration build (see
+   :doc:`segmented_configuration`); the runtime overlay is
+   ``<name>_aie_dynamic.pdi`` (or ``<name>_dynamic.pdi`` for a
+   non-AIE segmented build). Point ``-p`` at the dynamic half.
+
+**``v++ --package`` fails on packaging**
+   As a fallback path, set ``USE_BOOTGEN_FALLBACK=1`` to package via
+   ``bootgen`` instead. The two paths produce a functionally equivalent
+   dynamic PDI for the AIE-overlay case.
+
+**Subdirectory headers go missing from the component**
+   ``AIE_SOURCES`` directory entries are **non-recursive** and all imports
+   land flat at the component root. If your graph ``#include``\ s a header
+   via a subdirectory path (e.g. ``#include "kernels/foo.h"``), either
+   rewrite the include as a bare basename or add ``aie/kernels`` as a
+   separate ``AIE_SOURCES`` entry so the header lands at the root.
diff --git a/docs/reference/makefile_reference.rst b/docs/reference/makefile_reference.rst
index 497a457..6b29b2d 100644
--- a/docs/reference/makefile_reference.rst
+++ b/docs/reference/makefile_reference.rst
@@ -1,11 +1,13 @@
 Makefile Reference
 ==================
 
-This page documents the targets and environment variables provided by
-``system_vivado.mk``. Include this file from your project's ``Makefile`` to access
-the Vivado build pipeline.
+This page documents the targets and environment variables provided by the
+ruckus backend Makefile fragments — ``system_vivado.mk`` (Vivado) and
+``system_vitis_unified_aie.mk`` (Vitis AIE). Include one of these from your
+project's ``Makefile`` to access the corresponding build pipeline.
 
-For build pipeline context see :doc:`/explanation/build_pipeline`.
+For Vivado build pipeline context see :doc:`/explanation/build_pipeline`. For
+the AIE workflow walkthrough see :doc:`/how-to/vitis_aie`.
 
 .. contents::
    :local:
@@ -379,3 +381,208 @@ Vitis / SDK Variables
    Legacy alias for :envvar:`VITIS_SRC_PATH`. Used with Vivado 2019.1 and older.
 
    :default: unset
+
+Vitis AIE Targets
+-----------------
+
+These targets are provided by ``system_vitis_unified_aie.mk`` (Vitis 2025.1+
+unified toolchain). For the end-to-end workflow see :doc:`/how-to/vitis_aie`.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 78
+
+   * - Target
+     - Description
+   * - ``proj``
+     - Idempotently create the Vitis workspace and AIE component
+       (``vitis -s create_proj.py``). No-op if the component already exists.
+   * - ``build``
+     - Build the AIE graph for the ``hw`` target (``vitis -s build.py``).
+       Emits ``libadf.a`` under ``$(OUT_DIR)/$(PROJECT)/build/hw/``.
+   * - ``x86sim``
+     - Build for the x86 simulator (``vitis -s build.py --x86sim``).
+   * - ``package``
+     - Wrap ``libadf.a`` + ``$(AIE_XSA_INPUT)`` into the dynamic PDI
+       (``bash package.sh``). Uses ``v++ --package`` (primary) or ``bootgen``
+       (fallback when ``USE_BOOTGEN_FALLBACK=1``).
+   * - ``program``
+     - Invoke ``$(AIE_PROGRAM_SCRIPT)`` to deploy ``$(AIE_PDI)`` and
+       ``$(AIE_DTBO)`` to the target board.
+   * - ``gui``
+     - Open the same workspace in the Vitis Unified IDE
+       (``vitis -w $(OUT_DIR)``).
+   * - ``interactive``
+     - Drop into a Python REPL with the ``vitis`` module loaded
+       (``vitis -i``).
+   * - ``test``
+     - Print all AIE environment variable values.
+   * - ``clean``
+     - Delete the build directory (``rm -rf $(OUT_DIR)``).
+
+Vitis AIE Variables
+-------------------
+
+These variables drive ``system_vitis_unified_aie.mk``. The platform/part,
+sources, and top-level graph variables must be set in the consuming
+Makefile **before** the ``include`` line; ``AIE_XSA_INPUT`` and ``AIE_DTBO``
+are recipe-time requirements passed on the ``make`` command line.
+
+.. envvar:: AIE_PLATFORM
+
+   Absolute path to the platform ``.xpfm``. Use this for dev boards with an
+   AMD-shipped xpfm (e.g. ``xilinx_vek280_base_*``). Mutually exclusive with
+   :envvar:`AIE_PART` — set exactly one.
+
+   :default: unset (the Makefile errors at parse time if neither
+             ``AIE_PLATFORM`` nor ``AIE_PART`` is defined)
+
+   .. code-block:: makefile
+
+      export AIE_PLATFORM := $(firstword $(wildcard \
+          $(XILINX_VITIS)/base_platforms/xilinx_vek280_base_*/xilinx_vek280_base_*.xpfm))
+
+   The wildcard pattern keeps the same Makefile working across Vitis
+   releases — AMD bumps the numeric suffix per release (``202510_1`` in
+   2025.1, ``202520_1`` in 2025.2, …) so a literal path would pin the
+   project to one Vitis version.
+
+.. envvar:: AIE_PART
+
+   Versal device ID (e.g. ``xcve2802-vsvh1760-2MP-e-S``). Use this for
+   custom AIE boards without a shipped xpfm. The PL clock hint comes from
+   the cfg's ``pl-freq=`` line. Mutually exclusive with :envvar:`AIE_PLATFORM`.
+
+   :default: unset
+
+.. envvar:: AIE_SOURCES
+
+   Whitespace-separated list of source paths. Each entry is either:
+
+   - a **file** path → imports just that file, **or**
+   - a **directory** path → imports every ``.cpp`` / ``.cc`` / ``.h`` /
+     ``.hpp`` file in that directory (**non-recursive** — subdirectories
+     are not walked).
+
+   All imports land flat at the component root. Mix local and shared
+   sources freely (including submodule paths).
+
+   :default: unset (parse-time error)
+
+   .. code-block:: makefile
+
+      SHARED_AIE := $(TOP_DIR)/submodules/aie-common-kernels
+      export AIE_SOURCES = \
+          $(CURDIR)/aie \
+          $(CURDIR)/aie/kernels \
+          $(SHARED_AIE)/util.cc
+
+.. envvar:: AIE_TOP_LEVEL_FILE
+
+   Top-level graph file **basename** only (e.g. ``graph.cpp``). All
+   ``AIE_SOURCES`` entries land flat at the component root, so this is
+   just the filename — never a path.
+
+   :default: unset (parse-time error)
+
+.. envvar:: AIE_XSA_INPUT
+
+   Absolute path to the Vivado-built ``.xsa``, required by the ``package``
+   target. Pass on the ``make`` command line:
+
+   .. code-block:: bash
+
+      make AIE_XSA_INPUT=<path>/<image>.xsa package
+
+   :default: unset (parse-time error from the ``package`` target)
+
+   .. note::
+
+      Supplied at the command line rather than baked into the Makefile
+      because the Vivado-side ``IMAGENAME`` embeds ``BUILD_TIME`` and is
+      not predictable from inside the AIE archetype.
+
+.. envvar:: AIE_DTBO
+
+   Absolute path to the matching ``.dtbo`` device-tree overlay, required
+   by the ``program`` target. Checked at recipe time (not parse time) so
+   other targets are unaffected.
+
+   :default: unset (recipe-time error from the ``program`` target)
+
+.. envvar:: AIE_BOARD_IP
+
+   ``user@host`` for the ``program`` target. Forwarded to
+   ``$(AIE_PROGRAM_SCRIPT)`` as the ``-i`` flag when set.
+
+   :default: unset (the default ``program.sh`` errors if no ``-i`` is
+             passed — most consumers set a project default with
+             ``AIE_BOARD_IP ?= root@<dev-ip>``)
+
+.. envvar:: OUT_DIR
+
+   Vitis workspace root. The AIE component is created at
+   ``$(OUT_DIR)/$(PROJECT)/``.
+
+   :default: ``$(PROJ_DIR)/build``
+
+.. envvar:: AIE_IP_DIR
+
+   Final deliverable directory for the dynamic PDI. Mirrors the unified
+   HLS convention of writing artifacts to ``$(PROJ_DIR)/ip/``.
+
+   :default: ``$(PROJ_DIR)/ip``
+
+.. envvar:: AIE_PDI
+
+   Output dynamic PDI path written by ``make package``.
+
+   :default: ``$(AIE_IP_DIR)/$(PROJECT)_aie_dynamic.pdi``
+
+.. envvar:: AIE_PKG_DIR
+
+   Scratch directory used by the package step (``v++ --package`` working
+   tree).
+
+   :default: ``$(OUT_DIR)/aie_package``
+
+.. envvar:: VPP_LOG
+
+   Log file path for the ``v++ --package`` invocation.
+
+   :default: ``$(OUT_DIR)/vpp_package.log``
+
+.. envvar:: USE_BOOTGEN_FALLBACK
+
+   Set to ``1`` to package via ``bootgen`` instead of ``v++ --package``.
+   Both paths produce a functionally equivalent dynamic PDI for the
+   AIE-overlay case.
+
+   :default: ``0``
+
+.. envvar:: AIE_PROGRAM_SCRIPT
+
+   Deploy helper invoked by ``make program``. The default helper is a
+   generic Versal/PetaLinux deploy: scp PDI+DTBO to
+   ``/boot/{pl.pdi,pl.dtbo}``, ssh-reboot, verify
+   ``/sys/class/fpga_manager/fpga0/state == operating``. Override to
+   point at a project-specific helper when richer verification
+   (application-specific systemd checks, ``xsdb`` readout, etc.) is
+   required.
+
+   :default: ``$(RUCKUS_DIR)/vitis/aie/program.sh``
+
+   The helper must accept the following flag contract:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 18 82
+
+      * - Flag
+        - Meaning
+      * - ``-p <path>``
+        - Runtime PDI to upload (required)
+      * - ``-d <path>``
+        - Matching device-tree overlay (required)
+      * - ``-i <user@host>``
+        - Board target (forwarded from :envvar:`AIE_BOARD_IP`)
diff --git a/system_vitis_unified_aie.mk b/system_vitis_unified_aie.mk
new file mode 100644
index 0000000..6c5822d
--- /dev/null
+++ b/system_vitis_unified_aie.mk
@@ -0,0 +1,226 @@
+##############################################################################
+## This file is part of 'SLAC Firmware Standard Library'.
+## It is subject to the license terms in the LICENSE.txt file found in the
+## top-level directory of this distribution and at:
+##    https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html.
+## No part of 'SLAC Firmware Standard Library', including this file,
+## may be copied, modified, propagated, or distributed except according to
+## the terms contained in the LICENSE.txt file.
+##############################################################################
+
+# Detect project name
+ifndef PROJECT
+export PROJECT = $(notdir $(PWD))
+endif
+
+# Detect project path
+ifndef PROJ_DIR
+export PROJ_DIR = $(abspath $(PWD))
+endif
+
+# Standard ruckus layout assumes the consumer Makefile lives at
+# firmware/<category>/<name>/Makefile (firmware/shared/<name>/ for shared
+# archetypes, firmware/targets/<name>/ for Vivado targets). $(PWD)/../..
+# resolves to firmware/, where submodules/ruckus lives. Override
+# TOP_DIR before include if you have a non-standard layout.
+ifndef TOP_DIR
+export TOP_DIR = $(abspath $(PWD)/../..)
+endif
+
+# Project Build Directory ("workspace")
+ifndef OUT_DIR
+export OUT_DIR = $(PROJ_DIR)/build
+endif
+
+# Synthesis Variables
+# VIVADO_VERSION feeds BUILD_STRING in system_shared.mk ("Vivado v...").
+export VIVADO_VERSION  := $(shell vivado -version | grep -Po "v(\d+\.)+\d+" | cut -c2-)
+export RUCKUS_DIR       = $(TOP_DIR)/submodules/ruckus
+
+##############################################################################
+## Hard-fail early if the environment was not sourced. Vitis 2025.1 minimum
+## is required for the AIE Python API used by vitis/aie/{create_proj,build}.py.
+##############################################################################
+ifndef XILINX_VITIS
+$(error XILINX_VITIS not set — source firmware/setup_env_slac.sh first)
+endif
+
+include $(TOP_DIR)/submodules/ruckus/system_shared.mk
+
+##############################################################################
+## Required caller-defined variables. All five must be set in the consuming
+## target's AIE Makefile before including this file.
+##############################################################################
+##############################################################################
+## Exactly one of AIE_PLATFORM (xpfm path) or AIE_PART (Versal device ID)
+## must be defined. Use AIE_PLATFORM for dev boards with an AMD-shipped
+## .xpfm (e.g. xilinx_vek280_base_*); use AIE_PART for custom Versal AIE
+## boards that don't ship an xpfm. Both define the AIE array geometry;
+## AIE_PLATFORM additionally carries platform-specific data (PL clock caps,
+## NoC config, AIE-PL interface constraints), while AIE_PART relies on the
+## cfg's pl-freq= for the PL clock hint.
+##############################################################################
+ifeq ($(strip $(AIE_PLATFORM)$(AIE_PART)),)
+$(error Define either AIE_PLATFORM (.xpfm path, e.g. $$(XILINX_VITIS)/base_platforms/<board>/<board>.xpfm) or AIE_PART (Versal device ID, e.g. xcve2802-vsvh1760-2MP-e-S) in the target's AIE Makefile)
+endif
+ifneq ($(and $(strip $(AIE_PLATFORM)),$(strip $(AIE_PART))),)
+$(error Define only one of AIE_PLATFORM or AIE_PART, not both — use AIE_PLATFORM for dev boards with a shipped .xpfm, AIE_PART for custom boards without one)
+endif
+
+ifndef AIE_SOURCES
+$(error AIE_SOURCES not set — define it in the target's AIE Makefile as a whitespace-separated list of file and/or directory paths. File entries import that one file; directory entries import every .cpp/.cc/.h/.hpp file in the directory (non-recursive). All imports land flat at the component root. e.g. AIE_SOURCES = $$(CURDIR)/aie $$(CURDIR)/aie/kernels $$(TOP_DIR)/submodules/aie-lib/util.cc)
+endif
+
+ifndef AIE_TOP_LEVEL_FILE
+$(error AIE_TOP_LEVEL_FILE not set — define it in the target's AIE Makefile (e.g. AIE_TOP_LEVEL_FILE = graph.cpp))
+endif
+
+##############################################################################
+## AIE_XSA_INPUT is required by the package step (not by proj/build). It must
+## be supplied by the caller at the command line because the Vivado-side
+## IMAGENAME embeds $(BUILD_TIME), so the .xsa filename produced by an
+## earlier `make pdi` in the upstream Vivado target is not predictable from
+## within this AIE archetype's make invocation.
+##############################################################################
+ifndef AIE_XSA_INPUT
+$(error AIE_XSA_INPUT not set — pass the absolute path to the Vivado-built .xsa, e.g. make AIE_XSA_INPUT=<path>/<image>.xsa package)
+endif
+
+##############################################################################
+## Derived / packaging-related paths. Mirrors the HLS convention of writing
+## the final deliverable to $(PROJ_DIR)/ip/, keeping the AIE archetype
+## self-contained and decoupled from any consuming Vivado target.
+##############################################################################
+ifndef AIE_PKG_DIR
+export AIE_PKG_DIR = $(OUT_DIR)/aie_package
+endif
+
+ifndef AIE_IP_DIR
+export AIE_IP_DIR = $(PROJ_DIR)/ip
+endif
+
+ifndef AIE_PDI
+export AIE_PDI = $(AIE_IP_DIR)/$(PROJECT)_aie_dynamic.pdi
+endif
+
+ifndef VPP_LOG
+export VPP_LOG = $(OUT_DIR)/vpp_package.log
+endif
+
+ifndef USE_BOOTGEN_FALLBACK
+export USE_BOOTGEN_FALLBACK = 0
+endif
+
+# AIE_PROGRAM_SCRIPT — helper invoked by `make program` to deploy AIE_PDI
+# to the board. Defaults to the ruckus-shipped vitis/aie/program.sh, which
+# is a generic Versal/PetaLinux deploy (scp PDI+DTBO → /boot/, reboot, verify
+# fpga_manager state). Override if your project needs richer verification
+# (e.g. application-specific systemd checks, xsdb readout, etc.). The helper
+# must accept:
+#     -p <pdi-path>    runtime PDI to upload
+#     -d <dtbo-path>   matching device-tree overlay
+#     -i <user@ip>     board target
+ifndef AIE_PROGRAM_SCRIPT
+export AIE_PROGRAM_SCRIPT = $(RUCKUS_DIR)/vitis/aie/program.sh
+endif
+
+.PHONY : all
+all: target
+
+###############################################################
+#### Printout Env. Variables ##################################
+###############################################################
+.PHONY : test
+test:
+	@echo VIVADO_VERSION:    $(VIVADO_VERSION)
+	@echo PROJECT:           $(PROJECT)
+	@echo PROJ_DIR:          $(PROJ_DIR)
+	@echo TOP_DIR:           $(TOP_DIR)
+	@echo OUT_DIR:           $(OUT_DIR)
+	@echo RUCKUS_DIR:        $(RUCKUS_DIR)
+	@echo AIE_PLATFORM:      $(AIE_PLATFORM)
+	@echo AIE_PART:          $(AIE_PART)
+	@echo AIE_SOURCES:       $(AIE_SOURCES)
+	@echo AIE_TOP_LEVEL_FILE:$(AIE_TOP_LEVEL_FILE)
+	@echo AIE_XSA_INPUT:     $(AIE_XSA_INPUT)
+
+###############################################################
+#### Project Creation #########################################
+###############################################################
+.PHONY : proj
+proj:
+	$(call ACTION_HEADER,"Vitis AIE Create Project")
+	@test -d $(OUT_DIR) || mkdir -p $(OUT_DIR)
+	@cd $(OUT_DIR); vitis -s $(RUCKUS_DIR)/vitis/aie/create_proj.py
+
+###############################################################
+#### Vitis AIE Batch Build (hw target) ########################
+###############################################################
+.PHONY : build
+build : proj
+	$(call ACTION_HEADER,"Vitis AIE Build (target=hw)")
+	@cd $(OUT_DIR); vitis -s $(RUCKUS_DIR)/vitis/aie/build.py
+
+###############################################################
+#### Vitis AIE x86 Simulation Build ###########################
+###############################################################
+.PHONY : x86sim
+x86sim : proj
+	$(call ACTION_HEADER,"Vitis AIE x86sim")
+	@cd $(OUT_DIR); vitis -s $(RUCKUS_DIR)/vitis/aie/build.py --x86sim
+
+###############################################################
+#### Package — wraps libadf.a + XSA into dynamic PDI ##########
+###############################################################
+.PHONY : package
+package : build
+	$(call ACTION_HEADER,"Vitis AIE Package")
+	@bash $(RUCKUS_DIR)/vitis/aie/package.sh
+
+###############################################################
+#### program — deploy AIE_PDI to the target board #############
+###############################################################
+# Wraps $(AIE_PROGRAM_SCRIPT) — defaults to ruckus's vitis/aie/program.sh,
+# overridable per project. Caller must pass AIE_DTBO=<path> on the command
+# line. AIE_BOARD_IP is forwarded as `-i` if set. Asserts are recipe-time
+# (not parse-time) so other targets aren't affected.
+.PHONY : program
+program:
+	$(call ACTION_HEADER,"Vitis AIE Program")
+	@if [ ! -r "$(AIE_PROGRAM_SCRIPT)" ]; then \
+	  echo "ERROR: AIE_PROGRAM_SCRIPT '$(AIE_PROGRAM_SCRIPT)' not found."; \
+	  echo "       Override AIE_PROGRAM_SCRIPT to point at your deploy helper."; \
+	  exit 1; \
+	fi
+	@if [ -z "$(AIE_DTBO)" ]; then \
+	  echo "ERROR: AIE_DTBO not set — pass the absolute path to the matching .dtbo."; \
+	  echo "       e.g. make AIE_DTBO=<vivado-target>/images/<name>.dtbo program"; \
+	  exit 1; \
+	fi
+	bash $(AIE_PROGRAM_SCRIPT) \
+	  -p $(AIE_PDI) \
+	  -d $(AIE_DTBO) \
+	  $(if $(AIE_BOARD_IP),-i $(AIE_BOARD_IP),)
+
+###############################################################
+#### Vitis AIE Interactive ####################################
+###############################################################
+.PHONY : interactive
+interactive : proj
+	$(call ACTION_HEADER,"Vitis AIE Interactive")
+	@cd $(OUT_DIR); vitis -i
+
+###############################################################
+#### Vitis AIE GUI ############################################
+###############################################################
+.PHONY : gui
+gui : proj
+	$(call ACTION_HEADER,"Vitis Unified IDE")
+	@cd $(OUT_DIR); vitis -w $(OUT_DIR)
+
+###############################################################
+#### Clean ####################################################
+###############################################################
+.PHONY : clean
+clean:
+	rm -rf $(OUT_DIR)
diff --git a/system_vitis_unified_hls.mk b/system_vitis_unified_hls.mk
index a5624cc..f8c4b7c 100644
--- a/system_vitis_unified_hls.mk
+++ b/system_vitis_unified_hls.mk
@@ -34,6 +34,7 @@ export SKIP_COSIM = 0
 endif
 
 # Build System Variables
+# VIVADO_VERSION feeds BUILD_STRING in system_shared.mk ("Vivado v...").
 export VIVADO_VERSION := $(shell vivado -version | grep -Po "v(\d+\.)+\d+" | cut -c2-)
 export RUCKUS_DIR     = $(TOP_DIR)/submodules/ruckus
 
diff --git a/vitis/aie/build.py b/vitis/aie/build.py
new file mode 100644
index 0000000..518c5db
--- /dev/null
+++ b/vitis/aie/build.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+##############################################################################
+## This file is part of 'SLAC Firmware Standard Library'.
+## It is subject to the license terms in the LICENSE.txt file found in the
+## top-level directory of this distribution and at:
+##    https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html.
+## No part of 'SLAC Firmware Standard Library', including this file,
+## may be copied, modified, propagated, or distributed except according to
+## the terms contained in the LICENSE.txt file.
+##############################################################################
+#
+# build.py — drives the AIE component build via the Vitis Unified Python API.
+# Defaults to target='hw' (production libadf.a); pass --x86sim for the
+# simulator build (analog of HLS csim).
+#
+# Required env vars (set by system_vitis_aie.mk):
+#   OUT_DIR   workspace root (must be the cwd; system_vitis_aie.mk does cd)
+#   PROJECT   AIE component name
+
+import vitis
+import os
+import argparse
+
+parser = argparse.ArgumentParser(prog="Vitis AIE build script")
+parser.add_argument("--x86sim", default=False, action="store_true",
+                    help="Build for x86 simulator instead of hardware.")
+args = parser.parse_args()
+
+target    = "x86sim" if args.x86sim else "hw"
+workspace = os.getenv("OUT_DIR")
+comp_name = os.getenv("PROJECT")
+
+client = vitis.create_client()
+client.set_workspace(workspace)
+
+aie_comp = client.get_component(comp_name)
+aie_comp.build(target=target)
+
+vitis.dispose()
diff --git a/vitis/aie/create_proj.py b/vitis/aie/create_proj.py
new file mode 100644
index 0000000..3ccf289
--- /dev/null
+++ b/vitis/aie/create_proj.py
@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+##############################################################################
+## This file is part of 'SLAC Firmware Standard Library'.
+## It is subject to the license terms in the LICENSE.txt file found in the
+## top-level directory of this distribution and at:
+##    https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html.
+## No part of 'SLAC Firmware Standard Library', including this file,
+## may be copied, modified, propagated, or distributed except according to
+## the terms contained in the LICENSE.txt file.
+##############################################################################
+#
+# create_proj.py — idempotent Vitis Unified IDE workspace + AIE component
+# bootstrap. Driven by system_vitis_unified_aie.mk. Skipped silently if the
+# component already exists (so `make build` / `make gui` can call `make proj`
+# as a cheap no-op prereq).
+#
+# Required env vars (set by system_vitis_unified_aie.mk):
+#   OUT_DIR              workspace root
+#   PROJECT              AIE component name
+#   AIE_PLATFORM (xor)   absolute path to .xpfm (dev boards with a shipped
+#   AIE_PART     (xor)   xpfm); OR Versal device ID (custom AIE boards
+#                        without an xpfm — e.g. xcve2802-vsvh1760-2MP-e-S).
+#                        Exactly one must be set; the Makefile asserts this.
+#   AIE_SOURCES          whitespace-separated list of source paths. Each
+#                        entry is either:
+#                          - a FILE path → imports just that file
+#                          - a DIRECTORY path → imports every source file
+#                            in that directory (non-recursive)
+#                        Source extensions: .cpp .cc .h .hpp
+#                        All files land flat at the component root.
+#   AIE_TOP_LEVEL_FILE   top-level graph file basename (e.g. graph.cpp)
+#
+# Convention (not configurable, mirrors the HLS flow):
+#   aie_config.cfg lives at $(PROJ_DIR)/aie_config.cfg — i.e. the same
+#   directory as the consuming Makefile. Referenced below as a relative
+#   path that Vitis resolves against the component directory.
+
+import vitis
+import os
+from collections import defaultdict
+
+SRC_EXTENSIONS = ('.cpp', '.cc', '.h', '.hpp')
+
+workspace          = os.getenv("OUT_DIR")
+comp_name          = os.getenv("PROJECT")
+aie_platform       = os.getenv("AIE_PLATFORM")
+aie_part           = os.getenv("AIE_PART")
+aie_sources        = os.getenv("AIE_SOURCES", "").split()
+aie_top_level_file = os.getenv("AIE_TOP_LEVEL_FILE")
+
+# Hardcoded — same convention as HLS's `cfg_file = '../../hls_config.cfg'`.
+# Resolves to $(PROJ_DIR)/aie_config.cfg (component dir is OUT_DIR/PROJECT,
+# OUT_DIR is PROJ_DIR/build, so ../../ lands in PROJ_DIR).
+aie_config         = '../../aie_config.cfg'
+
+if not aie_sources:
+    raise SystemExit("create_proj: AIE_SOURCES is empty — list the files "
+                     "and/or directories in the consuming Makefile, e.g. "
+                     "AIE_SOURCES = $(CURDIR)/aie $(CURDIR)/aie/kernels")
+
+# Idempotent — skip if the component is already realized in the workspace.
+if os.path.isdir(f'{workspace}/{comp_name}'):
+    print(f'AIE component "{comp_name}" already exists at {workspace}/{comp_name} — skipping create_proj.')
+    raise SystemExit(0)
+
+# Expand each AIE_SOURCES entry. Files are taken as-is; directories are
+# globbed non-recursively for SRC_EXTENSIONS. Missing entries error loudly.
+expanded = []
+for entry in aie_sources:
+    abspath = os.path.abspath(entry)
+    if os.path.isfile(abspath):
+        expanded.append(abspath)
+    elif os.path.isdir(abspath):
+        for name in sorted(os.listdir(abspath)):
+            full = os.path.join(abspath, name)
+            if os.path.isfile(full) and name.endswith(SRC_EXTENSIONS):
+                expanded.append(full)
+    else:
+        raise SystemExit(f"create_proj: AIE_SOURCES entry not found: {entry}")
+
+if not expanded:
+    raise SystemExit(f"create_proj: AIE_SOURCES expanded to zero files "
+                     f"(looked for extensions {SRC_EXTENSIONS}).")
+
+client = vitis.create_client()
+client.set_workspace(workspace)
+
+# create_aie_component accepts either platform=<xpfm> or part=<device-id>
+# (the Makefile guarantees exactly one is set).
+if aie_platform:
+    aie_comp = client.create_aie_component(
+        name     = comp_name,
+        platform = aie_platform,
+        template = "empty",
+    )
+else:
+    aie_comp = client.create_aie_component(
+        name     = comp_name,
+        part     = aie_part,
+        template = "empty",
+    )
+
+# Group expanded paths by parent directory so we issue one import_files()
+# call per directory. All files land flat at the component root.
+groups = defaultdict(list)
+for path in expanded:
+    groups[os.path.dirname(path)].append(os.path.basename(path))
+
+for from_loc, basenames in groups.items():
+    aie_comp.import_files(from_loc=from_loc, files=basenames)
+
+aie_comp.update_top_level_file(top_level_file=aie_top_level_file)
+aie_comp.add_cfg_file(aie_config)
+
+aie_comp.report()
+
+vitis.dispose()
diff --git a/vitis/aie/package.sh b/vitis/aie/package.sh
new file mode 100644
index 0000000..c6f8b5d
--- /dev/null
+++ b/vitis/aie/package.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# ----------------------------------------------------------------------------
+# This file is part of the 'SLAC Firmware Standard Library'. It is subject to
+# the license terms in the LICENSE.txt file found in the top-level directory
+# of this distribution and at:
+#    https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html.
+# No part of the 'SLAC Firmware Standard Library', including this file, may be
+# copied, modified, propagated, or distributed except according to the terms
+# contained in the LICENSE.txt file.
+# ----------------------------------------------------------------------------
+#
+# package.sh — wrap the Python-built AIE libadf.a + the Vivado-built XSA into
+# a dynamic PDI via `v++ --package` (primary) or `bootgen` (fallback when
+# USE_BOOTGEN_FALLBACK=1). Driven by the `package` target in
+# system_vitis_unified_aie.mk; runs after `make build` produced the AIE component
+# under $OUT_DIR/$PROJECT/.
+#
+# The Vitis Unified Python AIE component build only emits libadf.a — final
+# PDI packaging still requires v++ --package (or bootgen), so this step
+# remains bash.
+#
+# Required env vars (set by system_vitis_unified_aie.mk):
+#   AIE_XSA_INPUT  AIE_PKG_DIR  AIE_IP_DIR  AIE_PDI  VPP_LOG
+#   OUT_DIR  PROJECT  USE_BOOTGEN_FALLBACK
+
+set -euo pipefail
+
+if [ ! -f "${AIE_XSA_INPUT}" ]; then
+  echo "ERROR: AIE_XSA_INPUT not found at ${AIE_XSA_INPUT}"
+  echo "       Build the upstream Vivado target's XSA first."
+  exit 1
+fi
+
+# Locate the AIE component's hw libadf.a. The Vitis Unified IDE places it
+# under <workspace>/<comp>/build/hw/ but the exact subdir can vary across
+# minor Vitis versions — find the first match under the component dir.
+LIBADF=$(find "${OUT_DIR}/${PROJECT}" -path "*/build/hw/*" -name "libadf.a" 2>/dev/null | head -1)
+if [ -z "${LIBADF}" ]; then
+  echo "ERROR: libadf.a not found under ${OUT_DIR}/${PROJECT}/build/hw/"
+  echo "       Did 'make build' complete? Inspect the Vitis build log."
+  exit 1
+fi
+echo "Using AIE archive: ${LIBADF}"
+
+mkdir -p "${AIE_PKG_DIR}" "${AIE_IP_DIR}"
+echo "==== package (USE_BOOTGEN_FALLBACK=${USE_BOOTGEN_FALLBACK}) ===="
+
+if [ "${USE_BOOTGEN_FALLBACK}" = "1" ]; then
+  echo "---- bootgen fallback ----"
+  # Locate the AIE CDO bin files emitted by the component build.
+  AIE_CDO_DIR=$(find "${OUT_DIR}/${PROJECT}" -type d -path "*/ps/cdo" 2>/dev/null | head -1)
+  if [ -z "${AIE_CDO_DIR}" ]; then
+    echo "ERROR: AIE CDO directory (ps/cdo) not found under ${OUT_DIR}/${PROJECT}"
+    exit 1
+  fi
+  cat > "${AIE_PKG_DIR}/aie_overlay.bif" <<EOF
+all:
+{
+    image
+    {
+        name=aie_image, id=0x1c000000
+        { type=cdo
+          file = ${AIE_CDO_DIR}/aie_cdo_reset.bin
+          file = ${AIE_CDO_DIR}/aie_cdo_clock_gating.bin
+          file = ${AIE_CDO_DIR}/aie_cdo_error_handling.bin
+          file = ${AIE_CDO_DIR}/aie_cdo_elfs.bin
+          file = ${AIE_CDO_DIR}/aie_cdo_init.bin
+          file = ${AIE_CDO_DIR}/aie_cdo_enable.bin
+        }
+    }
+}
+EOF
+  bootgen -arch versal -image "${AIE_PKG_DIR}/aie_overlay.bif" -o "${AIE_PDI}" -w 2>&1 | tee "${VPP_LOG}"
+else
+  echo "---- v++ --package primary ----"
+  v++ --package \
+      --target hw \
+      --platform "${AIE_XSA_INPUT}" \
+      --package.out_dir "${AIE_PKG_DIR}" \
+      --package.boot_mode sd \
+      "${LIBADF}" \
+      2>&1 | tee "${VPP_LOG}"
+  PDI=$(find "${AIE_PKG_DIR}" -name "pl.pdi" -o -name "*_pld.pdi" -o -name "*.pdi" 2>/dev/null | head -1)
+  if [ -z "${PDI}" ]; then
+    echo "ERROR: v++ --package produced no PDI under ${AIE_PKG_DIR}"
+    echo "       Inspect ${VPP_LOG}; engage USE_BOOTGEN_FALLBACK=1"
+    echo "       Re-run with: make USE_BOOTGEN_FALLBACK=1 package"
+    exit 1
+  fi
+  cp -f "${PDI}" "${AIE_PDI}"
+fi
+
+echo "AIE dynamic PDI staged: ${AIE_PDI}"
diff --git a/vitis/aie/program.sh b/vitis/aie/program.sh
new file mode 100644
index 0000000..832b6a7
--- /dev/null
+++ b/vitis/aie/program.sh
@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# ----------------------------------------------------------------------------
+# This file is part of the 'SLAC Firmware Standard Library'. It is subject to
+# the license terms in the LICENSE.txt file found in the top-level directory
+# of this distribution and at:
+#    https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html.
+# No part of the 'SLAC Firmware Standard Library', including this file, may be
+# copied, modified, propagated, or distributed except according to the terms
+# contained in the LICENSE.txt file.
+# ----------------------------------------------------------------------------
+#
+# program.sh — generic AIE PDI deploy helper invoked by the `program` target
+# in system_vitis_unified_aie.mk. Uploads the dynamic PDI + matching DTBO
+# to /boot/{pl.pdi,pl.dtbo} on the target board (PetaLinux convention),
+# optionally reboots, and verifies the fpga_manager comes up in the
+# 'operating' state.
+#
+# Required flags:
+#   -p <path>        runtime PDI to upload
+#   -d <path>        matching device-tree overlay
+#   -i <user@host>   board target (no default — required)
+#
+# Optional flags:
+#   -r               dry-run: skip the reboot (uploads only)
+#   -h               show this help
+#
+# Exit codes:
+#   0  success: PDI deployed and fpga_manager in 'operating' state
+#   1  local pre-flight failed (missing/invalid -p/-d/-i, or static-PDI guard)
+#   2  scp/ssh failure during upload
+#   3  post-reboot verification failed (board didn't come up, or fpga0/state
+#      not 'operating')
+
+set -euo pipefail
+
+BOARD_IP=""
+PDI_LOCAL=""
+DTBO_LOCAL=""
+DO_REBOOT=1
+BOARD_UP_TIMEOUT=90
+PL_LOAD_TIMEOUT=30
+
+show_help() {
+    cat <<'EOF'
+Usage: program.sh -p <pdi> -d <dtbo> -i <user@host> [-r] [-h]
+
+Generic AIE PDI deploy helper. Uploads PDI + DTBO to /boot/, optionally
+reboots, verifies fpga_manager state.
+
+Flags:
+  -p <path>        runtime PDI to upload (required)
+  -d <path>        matching device-tree overlay (required)
+  -i <user@host>   board target (required, e.g. root@192.168.1.10)
+  -r               dry-run: skip the reboot
+  -h               show this help
+EOF
+    exit 0
+}
+
+while getopts "i:p:d:rh" flag; do
+    case "$flag" in
+        i) BOARD_IP="$OPTARG" ;;
+        p) PDI_LOCAL="$OPTARG" ;;
+        d) DTBO_LOCAL="$OPTARG" ;;
+        r) DO_REBOOT=0 ;;
+        h) show_help ;;
+        *) show_help ;;
+    esac
+done
+
+preflight() {
+    local fail=0
+    if [[ -z "$BOARD_IP" ]]; then
+        echo "[FAIL] -i <user@host> not provided"
+        fail=$(( fail + 1 ))
+    fi
+    # Defend against uploading the static (boot-image) PDI as the runtime
+    # overlay. The pair is <name>_static.pdi (BOOT.BIN half) vs
+    # <name>_dynamic.pdi / <name>_aie_dynamic.pdi (the overlay).
+    if [[ -n "$PDI_LOCAL" ]] && [[ "$PDI_LOCAL" == *_static* ]]; then
+        echo "[FAIL] -p filename '$PDI_LOCAL' contains '_static'."
+        echo "       Refusing to upload static PDI as runtime overlay;"
+        echo "       pass the *_aie_dynamic.pdi (or *_dynamic.pdi) instead."
+        fail=$(( fail + 1 ))
+    fi
+    if [[ -z "$PDI_LOCAL" ]] || [[ ! -s "$PDI_LOCAL" ]]; then
+        echo "[FAIL] -p missing or empty (PDI='$PDI_LOCAL')"
+        fail=$(( fail + 1 ))
+    else
+        echo "[PASS] pl.pdi present at $PDI_LOCAL ($(stat -c%s "$PDI_LOCAL") bytes)"
+    fi
+    if [[ -z "$DTBO_LOCAL" ]] || [[ ! -s "$DTBO_LOCAL" ]]; then
+        echo "[FAIL] -d missing or empty (DTBO='$DTBO_LOCAL')"
+        fail=$(( fail + 1 ))
+    else
+        echo "[PASS] pl.dtbo present at $DTBO_LOCAL ($(stat -c%s "$DTBO_LOCAL") bytes)"
+    fi
+    if [[ -n "$BOARD_IP" ]]; then
+        if ssh -o ConnectTimeout=5 -o BatchMode=yes -o ForwardX11=no \
+               "$BOARD_IP" 'true' >/dev/null 2>&1; then
+            echo "[PASS] $BOARD_IP reachable via ssh"
+        else
+            echo "[FAIL] $BOARD_IP unreachable via ssh (ssh-key auth required;"
+            echo "       no password prompt under BatchMode=yes)"
+            fail=$(( fail + 1 ))
+        fi
+    fi
+    [[ $fail -eq 0 ]] || return 1
+    return 0
+}
+
+upload() {
+    echo "---- scp pl.pdi  -> $BOARD_IP:/boot/pl.pdi ----"
+    scp -o BatchMode=yes -o ConnectTimeout=5 -o ForwardX11=no \
+        "$PDI_LOCAL" "$BOARD_IP:/boot/pl.pdi"
+    echo "[PASS] pl.pdi uploaded"
+    echo "---- scp pl.dtbo -> $BOARD_IP:/boot/pl.dtbo ----"
+    scp -o BatchMode=yes -o ConnectTimeout=5 -o ForwardX11=no \
+        "$DTBO_LOCAL" "$BOARD_IP:/boot/pl.dtbo"
+    echo "[PASS] pl.dtbo uploaded"
+}
+
+reboot_board() {
+    echo "---- rebooting $BOARD_IP (sync; reboot) ----"
+    # Disconnection from the reboot itself is expected; suppress rc with || true.
+    ssh -o BatchMode=yes -o ConnectTimeout=5 \
+        -o ServerAliveInterval=5 -o ServerAliveCountMax=2 \
+        -o ForwardX11=no \
+        "$BOARD_IP" '/bin/sync; /sbin/reboot' || true
+}
+
+wait_for_board_up() {
+    local elapsed=0
+    echo "---- polling $BOARD_IP for ssh liveness (deadline ${BOARD_UP_TIMEOUT}s) ----"
+    while [[ $elapsed -lt $BOARD_UP_TIMEOUT ]]; do
+        if ssh -o ConnectTimeout=3 -o BatchMode=yes -o ForwardX11=no \
+               "$BOARD_IP" 'true' >/dev/null 2>&1; then
+            echo "[PASS] board up after ${elapsed}s"
+            return 0
+        fi
+        sleep 5
+        elapsed=$(( elapsed + 5 ))
+    done
+    return 1
+}
+
+wait_for_pl_load_complete() {
+    local elapsed=0
+    echo "---- polling $BOARD_IP for fpga_manager 'operating' (deadline ${PL_LOAD_TIMEOUT}s) ----"
+    while [[ $elapsed -lt $PL_LOAD_TIMEOUT ]]; do
+        if ssh -o ConnectTimeout=3 -o BatchMode=yes -o ForwardX11=no \
+               "$BOARD_IP" "journalctl -b 2>/dev/null | grep -q 'fpga_manager/fpga0/state: operating'" \
+               >/dev/null 2>&1; then
+            echo "[PASS] PL load complete after ${elapsed}s"
+            return 0
+        fi
+        sleep 3
+        elapsed=$(( elapsed + 3 ))
+    done
+    return 1
+}
+
+check_fpga_state() {
+    local out
+    out=$(ssh -o ConnectTimeout=5 -o BatchMode=yes -o ForwardX11=no \
+              "$BOARD_IP" 'cat /sys/class/fpga_manager/fpga0/state' 2>&1) || true
+    out="${out%$'\n'}"
+    if [[ "$out" == "operating" ]]; then
+        echo "[PASS] fpga0/state == operating"
+        return 0
+    else
+        echo "[FAIL] fpga0/state == '$out' (expected 'operating')"
+        return 1
+    fi
+}
+
+print_summary() {
+    local overall="$1"
+    local verdict
+    if [[ $overall -eq 0 ]]; then
+        verdict="AIE PROGRAMMED"
+    else
+        verdict="FAILED"
+    fi
+    echo "=============================================================="
+    echo " AIE PROGRAM SUMMARY"
+    echo "--------------------------------------------------------------"
+    echo "  Board IP:           $BOARD_IP"
+    echo "  PDI uploaded:       $PDI_LOCAL"
+    echo "  DTBO uploaded:      $DTBO_LOCAL"
+    echo "  Reboot performed:   $([[ $DO_REBOOT -eq 1 ]] && echo yes || echo no)"
+    echo "--------------------------------------------------------------"
+    echo " Overall: $verdict"
+    echo "=============================================================="
+}
+
+printf '[%s] program.sh start: BOARD_IP=%s PDI=%s DTBO=%s DO_REBOOT=%s\n' \
+    "$(date -Iseconds)" "$BOARD_IP" "$PDI_LOCAL" "$DTBO_LOCAL" "$DO_REBOOT"
+
+preflight                  || exit 1
+upload                     || exit 2
+[[ $DO_REBOOT -eq 1 ]] && reboot_board
+wait_for_board_up          || { echo "FAIL: board did not come back up in ${BOARD_UP_TIMEOUT}s"; exit 3; }
+wait_for_pl_load_complete  || { echo "FAIL: PL load did not complete in ${PL_LOAD_TIMEOUT}s post-up"; exit 3; }
+check_fpga_state           || exit 3
+print_summary 0
+exit 0

From d0485381481d675df83871231b61c6c28e41f48e Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Sun, 24 May 2026 06:01:36 -0700
Subject: [PATCH 2/7] fix(vitis/aie): defer AIE_XSA_INPUT check to recipe-time
 in package

The parse-time `ifndef AIE_XSA_INPUT` guard fired on every make
invocation, breaking `make clean`, `make gui`, and other targets that
don't need the XSA. Move the check inside the `package` recipe,
mirroring the AIE_DTBO pattern used by `program`.
---
 system_vitis_unified_aie.mk | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/system_vitis_unified_aie.mk b/system_vitis_unified_aie.mk
index 6c5822d..d357233 100644
--- a/system_vitis_unified_aie.mk
+++ b/system_vitis_unified_aie.mk
@@ -76,16 +76,12 @@ $(error AIE_TOP_LEVEL_FILE not set — define it in the target's AIE Makefile (e
 endif
 
 ##############################################################################
-## AIE_XSA_INPUT is required by the package step (not by proj/build). It must
-## be supplied by the caller at the command line because the Vivado-side
+## AIE_XSA_INPUT is required by the package step (not by proj/build/clean/gui).
+## It must be supplied by the caller at the command line because the Vivado-side
 ## IMAGENAME embeds $(BUILD_TIME), so the .xsa filename produced by an
 ## earlier `make pdi` in the upstream Vivado target is not predictable from
-## within this AIE archetype's make invocation.
-##############################################################################
-ifndef AIE_XSA_INPUT
-$(error AIE_XSA_INPUT not set — pass the absolute path to the Vivado-built .xsa, e.g. make AIE_XSA_INPUT=<path>/<image>.xsa package)
-endif
-
+## within this AIE archetype's make invocation. Asserted at recipe-time inside
+## `package` so that clean/gui/proj/build/x86sim/interactive/test do not require it.
 ##############################################################################
 ## Derived / packaging-related paths. Mirrors the HLS convention of writing
 ## the final deliverable to $(PROJ_DIR)/ip/, keeping the AIE archetype
@@ -175,6 +171,11 @@ x86sim : proj
 .PHONY : package
 package : build
 	$(call ACTION_HEADER,"Vitis AIE Package")
+	@if [ -z "$(AIE_XSA_INPUT)" ]; then \
+	  echo "ERROR: AIE_XSA_INPUT not set — pass the absolute path to the Vivado-built .xsa,"; \
+	  echo "       e.g. make AIE_XSA_INPUT=<path>/<image>.xsa package"; \
+	  exit 1; \
+	fi
 	@bash $(RUCKUS_DIR)/vitis/aie/package.sh
 
 ###############################################################

From 5bc729602b8006e923807b74f8c879d91f6bb5a2 Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Sun, 24 May 2026 06:06:54 -0700
Subject: [PATCH 3/7] fix(vitis/aie): strip default cfg file before adding
 aie_config.cfg

Vitis 2025.2 auto-attaches a default `aiecompiler.cfg` at AIE component
creation; AIE components reject a second cfg file ("Multiple cfg files
are not allowed"), so add_cfg_file() failed for the SLAC convention of
$(PROJ_DIR)/aie_config.cfg.

Query report() for any existing cfg files and remove them before adding
ours. Idempotent: pre-2025.2 behavior (no auto-cfg) is unaffected since
the loop iterates over an empty list.
---
 vitis/aie/create_proj.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/vitis/aie/create_proj.py b/vitis/aie/create_proj.py
index 3ccf289..128dfbf 100644
--- a/vitis/aie/create_proj.py
+++ b/vitis/aie/create_proj.py
@@ -110,6 +110,14 @@
     aie_comp.import_files(from_loc=from_loc, files=basenames)
 
 aie_comp.update_top_level_file(top_level_file=aie_top_level_file)
+
+# Vitis 2025.2 attaches a default cfg file at component creation; AIE
+# components reject a second cfg file. Strip whatever is already attached
+# so add_cfg_file() below installs our $(PROJ_DIR)/aie_config.cfg cleanly.
+existing_cfg = aie_comp.report().get('cfg_files', []) or []
+for cfg in existing_cfg:
+    aie_comp.remove_cfg_file(cfg)
+
 aie_comp.add_cfg_file(aie_config)
 
 aie_comp.report()

From 1f74fcbace2ef407f1f4aa6ac09fb098a3c0f321 Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Sun, 24 May 2026 06:28:03 -0700
Subject: [PATCH 4/7] feat(vitis/aie): support :dest_subdir in AIE_SOURCES +
 auto-merge include paths

Two related changes for the AMD-canonical kernels-subdir layout (graph.h
referencing `adf::source(loop) = "kernels/loopback.cc"`):

1. AIE_SOURCES gains an optional `:dest_subdir` suffix per entry. Without
   it, files import flat at the component root (existing behavior). With
   it, files import into <component>/<dest_subdir>/.
   e.g. AIE_SOURCES = $(CURDIR)/aie $(CURDIR)/aie/kernels:kernels

2. create_proj.py now synthesizes PROJ_DIR/aie_config.generated.cfg
   combining auto-derived `include=` directives (one per unique
   dest_subdir, plus the component root) with the user's aie_config.cfg
   contents. The generated cfg is what gets attached to the component;
   without these include directives, the aiecompiler can't resolve
   `adf::source("subdir/file.cc")` paths after Vitis 2025.2's default
   cfg gets stripped.

Backward compatible: AIE_SOURCES entries without `:dest_subdir` keep the
flat-import behavior, and projects without subdirs still get a working
generated cfg (just `include=../..` plus user content).
---
 system_vitis_unified_aie.mk |  2 +-
 vitis/aie/create_proj.py    | 90 +++++++++++++++++++++++++++++--------
 2 files changed, 72 insertions(+), 20 deletions(-)

diff --git a/system_vitis_unified_aie.mk b/system_vitis_unified_aie.mk
index d357233..86e55b3 100644
--- a/system_vitis_unified_aie.mk
+++ b/system_vitis_unified_aie.mk
@@ -68,7 +68,7 @@ $(error Define only one of AIE_PLATFORM or AIE_PART, not both — use AIE_PLATFO
 endif
 
 ifndef AIE_SOURCES
-$(error AIE_SOURCES not set — define it in the target's AIE Makefile as a whitespace-separated list of file and/or directory paths. File entries import that one file; directory entries import every .cpp/.cc/.h/.hpp file in the directory (non-recursive). All imports land flat at the component root. e.g. AIE_SOURCES = $$(CURDIR)/aie $$(CURDIR)/aie/kernels $$(TOP_DIR)/submodules/aie-lib/util.cc)
+$(error AIE_SOURCES not set — define it in the target's AIE Makefile as a whitespace-separated list of `path[:dest_subdir]` entries. File entries import that one file; directory entries import every .cpp/.cc/.h/.hpp file in the directory (non-recursive). Without `:dest_subdir`, files land flat at the component root; with `:dest_subdir`, they import into <component>/<dest_subdir>/ (matches the AMD-canonical `kernels/` layout where graph.h does `adf::source(loop) = "kernels/loopback.cc";`). e.g. AIE_SOURCES = $$(CURDIR)/aie $$(CURDIR)/aie/kernels:kernels $$(TOP_DIR)/submodules/aie-lib/util.cc)
 endif
 
 ifndef AIE_TOP_LEVEL_FILE
diff --git a/vitis/aie/create_proj.py b/vitis/aie/create_proj.py
index 128dfbf..63d6d22 100644
--- a/vitis/aie/create_proj.py
+++ b/vitis/aie/create_proj.py
@@ -22,12 +22,19 @@
 #                        without an xpfm — e.g. xcve2802-vsvh1760-2MP-e-S).
 #                        Exactly one must be set; the Makefile asserts this.
 #   AIE_SOURCES          whitespace-separated list of source paths. Each
-#                        entry is either:
+#                        entry has the form `path[:dest_subdir]`:
 #                          - a FILE path → imports just that file
 #                          - a DIRECTORY path → imports every source file
 #                            in that directory (non-recursive)
 #                        Source extensions: .cpp .cc .h .hpp
-#                        All files land flat at the component root.
+#                        Without `:dest_subdir`, files land flat at the
+#                        component root. With `:dest_subdir`, they are
+#                        imported into <component>/<dest_subdir>/ — needed
+#                        for the AMD canonical layout where graph.h does
+#                        `adf::source(loop) = "kernels/loopback.cc";`.
+#                        Example:
+#                          AIE_SOURCES = $(CURDIR)/aie \
+#                                        $(CURDIR)/aie/kernels:kernels
 #   AIE_TOP_LEVEL_FILE   top-level graph file basename (e.g. graph.cpp)
 #
 # Convention (not configurable, mirrors the HLS flow):
@@ -48,10 +55,21 @@
 aie_sources        = os.getenv("AIE_SOURCES", "").split()
 aie_top_level_file = os.getenv("AIE_TOP_LEVEL_FILE")
 
-# Hardcoded — same convention as HLS's `cfg_file = '../../hls_config.cfg'`.
-# Resolves to $(PROJ_DIR)/aie_config.cfg (component dir is OUT_DIR/PROJECT,
-# OUT_DIR is PROJ_DIR/build, so ../../ lands in PROJ_DIR).
-aie_config         = '../../aie_config.cfg'
+# PROJ_DIR is the parent of OUT_DIR (the script runs with cwd=OUT_DIR per
+# system_vitis_unified_aie.mk). User cfg lives at PROJ_DIR/aie_config.cfg
+# by convention, mirroring HLS's hls_config.cfg.
+proj_dir         = os.path.abspath(os.path.join(workspace, '..'))
+aie_config_user  = os.path.join(proj_dir, 'aie_config.cfg')
+
+# Generated cfg actually attached to the component. We synthesize this so
+# that include= directives derived from AIE_SOURCES dest_subdirs are
+# always present alongside the user's [aie] settings — without it, the
+# aiecompiler can't resolve `adf::source("kernels/loopback.cc")` paths.
+# Lives at PROJ_DIR/aie_config.generated.cfg; included paths are relative
+# to v++'s working directory (<comp>/build/<target>/), so `../..` is the
+# component root and `../../<subdir>` is <comp>/<subdir>/.
+aie_config_generated     = os.path.join(proj_dir, 'aie_config.generated.cfg')
+aie_config_generated_rel = '../../aie_config.generated.cfg'
 
 if not aie_sources:
     raise SystemExit("create_proj: AIE_SOURCES is empty — list the files "
@@ -63,18 +81,25 @@
     print(f'AIE component "{comp_name}" already exists at {workspace}/{comp_name} — skipping create_proj.')
     raise SystemExit(0)
 
-# Expand each AIE_SOURCES entry. Files are taken as-is; directories are
-# globbed non-recursively for SRC_EXTENSIONS. Missing entries error loudly.
+# Expand each AIE_SOURCES entry. Each entry is `path[:dest_subdir]` —
+# files are taken as-is; directories are globbed non-recursively for
+# SRC_EXTENSIONS. Missing entries error loudly. `dest_subdir` (optional)
+# selects an in-component destination directory; default is component
+# root (flat). Each expanded item is recorded as (abs_file_path, dest_subdir).
 expanded = []
-for entry in aie_sources:
+for raw_entry in aie_sources:
+    if ':' in raw_entry:
+        entry, dest_subdir = raw_entry.rsplit(':', 1)
+    else:
+        entry, dest_subdir = raw_entry, ''
     abspath = os.path.abspath(entry)
     if os.path.isfile(abspath):
-        expanded.append(abspath)
+        expanded.append((abspath, dest_subdir))
     elif os.path.isdir(abspath):
         for name in sorted(os.listdir(abspath)):
             full = os.path.join(abspath, name)
             if os.path.isfile(full) and name.endswith(SRC_EXTENSIONS):
-                expanded.append(full)
+                expanded.append((full, dest_subdir))
     else:
         raise SystemExit(f"create_proj: AIE_SOURCES entry not found: {entry}")
 
@@ -100,25 +125,52 @@
         template = "empty",
     )
 
-# Group expanded paths by parent directory so we issue one import_files()
-# call per directory. All files land flat at the component root.
+# Group expanded paths by (parent dir, dest_subdir) so we issue one
+# import_files() call per (source dir, destination) pair. Files with no
+# dest_subdir land flat at the component root.
 groups = defaultdict(list)
-for path in expanded:
-    groups[os.path.dirname(path)].append(os.path.basename(path))
+for path, dest_subdir in expanded:
+    groups[(os.path.dirname(path), dest_subdir)].append(os.path.basename(path))
 
-for from_loc, basenames in groups.items():
-    aie_comp.import_files(from_loc=from_loc, files=basenames)
+for (from_loc, dest_subdir), basenames in groups.items():
+    if dest_subdir:
+        aie_comp.import_files(from_loc=from_loc, files=basenames,
+                              dest_dir_in_cmp=dest_subdir)
+    else:
+        aie_comp.import_files(from_loc=from_loc, files=basenames)
 
 aie_comp.update_top_level_file(top_level_file=aie_top_level_file)
 
+# Synthesize PROJ_DIR/aie_config.generated.cfg from auto-derived
+# include= directives + the user's aie_config.cfg. Include paths are
+# relative to v++'s working directory (<comp>/build/<target>/), so
+# `../..` is the component root and `../../<subdir>` reaches each
+# AIE_SOURCES dest_subdir. The component root is always added so that
+# graph.h / kernels.h are discoverable.
+unique_dests = sorted({d for _, d in expanded if d})
+include_lines = ['include=../..']
+include_lines += [f'include=../../{d}' for d in unique_dests]
+header = '\n'.join(include_lines) + '\n\n'
+if os.path.isfile(aie_config_user):
+    with open(aie_config_user, 'r') as f:
+        user_body = f.read()
+else:
+    user_body = ''
+with open(aie_config_generated, 'w') as f:
+    f.write('# Auto-generated by ruckus vitis/aie/create_proj.py — DO NOT EDIT.\n')
+    f.write('# Edits to aie_config.cfg are merged on every `make proj`.\n')
+    f.write('# include= paths are derived from AIE_SOURCES dest_subdirs.\n\n')
+    f.write(header)
+    f.write(user_body)
+
 # Vitis 2025.2 attaches a default cfg file at component creation; AIE
 # components reject a second cfg file. Strip whatever is already attached
-# so add_cfg_file() below installs our $(PROJ_DIR)/aie_config.cfg cleanly.
+# so add_cfg_file() below installs the generated cfg cleanly.
 existing_cfg = aie_comp.report().get('cfg_files', []) or []
 for cfg in existing_cfg:
     aie_comp.remove_cfg_file(cfg)
 
-aie_comp.add_cfg_file(aie_config)
+aie_comp.add_cfg_file(aie_config_generated_rel)
 
 aie_comp.report()
 

From cdf3c7885ae754a507e327cebafc113731008321 Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Sun, 24 May 2026 07:40:23 -0700
Subject: [PATCH 5/7] fix(vitis/aie): auto-fall back to bootgen when v++
 --package rejects XSA

AMD policy: v++ --package only accepts accelerated/PFM-style platforms.
SLAC's standard Versal SoC firmware XSAs (axi-soc-versal-core) are
non-accelerated, so v++ --package always errors with [v++ 60-1606]
"is a non-accelerated platform". The bootgen escape hatch
(USE_BOOTGEN_FALLBACK=1) already existed for this case, but required
the caller to know about it.

Detect that specific rejection in the v++ log and transparently retry
via bootgen. Other v++ failures still surface as hard errors with the
USE_BOOTGEN_FALLBACK=1 hint. USE_BOOTGEN_FALLBACK=1 still skips v++
entirely as before.
---
 vitis/aie/package.sh | 49 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/vitis/aie/package.sh b/vitis/aie/package.sh
index c6f8b5d..4e47527 100644
--- a/vitis/aie/package.sh
+++ b/vitis/aie/package.sh
@@ -45,9 +45,15 @@ echo "Using AIE archive: ${LIBADF}"
 mkdir -p "${AIE_PKG_DIR}" "${AIE_IP_DIR}"
 echo "==== package (USE_BOOTGEN_FALLBACK=${USE_BOOTGEN_FALLBACK}) ===="
 
-if [ "${USE_BOOTGEN_FALLBACK}" = "1" ]; then
+# bootgen path — assemble AIE CDO bins into a dynamic PDI directly. Used
+# when (a) USE_BOOTGEN_FALLBACK=1 is set explicitly, or (b) v++ --package
+# rejected AIE_XSA_INPUT as a non-accelerated platform. SLAC's standard
+# Versal SoC firmware XSAs (axi-soc-versal-core) are non-accelerated, so
+# the auto-fallback covers the SLAC default flow without the caller
+# having to know about the bootgen escape hatch.
+run_bootgen() {
   echo "---- bootgen fallback ----"
-  # Locate the AIE CDO bin files emitted by the component build.
+  local AIE_CDO_DIR
   AIE_CDO_DIR=$(find "${OUT_DIR}/${PROJECT}" -type d -path "*/ps/cdo" 2>/dev/null | head -1)
   if [ -z "${AIE_CDO_DIR}" ]; then
     echo "ERROR: AIE CDO directory (ps/cdo) not found under ${OUT_DIR}/${PROJECT}"
@@ -70,9 +76,14 @@ all:
     }
 }
 EOF
-  bootgen -arch versal -image "${AIE_PKG_DIR}/aie_overlay.bif" -o "${AIE_PDI}" -w 2>&1 | tee "${VPP_LOG}"
+  bootgen -arch versal -image "${AIE_PKG_DIR}/aie_overlay.bif" -o "${AIE_PDI}" -w 2>&1 | tee -a "${VPP_LOG}"
+}
+
+if [ "${USE_BOOTGEN_FALLBACK}" = "1" ]; then
+  run_bootgen
 else
   echo "---- v++ --package primary ----"
+  set +e
   v++ --package \
       --target hw \
       --platform "${AIE_XSA_INPUT}" \
@@ -80,14 +91,32 @@ else
       --package.boot_mode sd \
       "${LIBADF}" \
       2>&1 | tee "${VPP_LOG}"
-  PDI=$(find "${AIE_PKG_DIR}" -name "pl.pdi" -o -name "*_pld.pdi" -o -name "*.pdi" 2>/dev/null | head -1)
-  if [ -z "${PDI}" ]; then
-    echo "ERROR: v++ --package produced no PDI under ${AIE_PKG_DIR}"
-    echo "       Inspect ${VPP_LOG}; engage USE_BOOTGEN_FALLBACK=1"
-    echo "       Re-run with: make USE_BOOTGEN_FALLBACK=1 package"
-    exit 1
+  VPP_RC=${PIPESTATUS[0]}
+  set -e
+
+  if [ "${VPP_RC}" -ne 0 ]; then
+    # AMD policy: v++ --package rejects non-accelerated platforms (stock
+    # SoC XSAs without PFM acceleration metadata). SLAC SoC XSAs are
+    # always non-accelerated, so auto-fall back to bootgen on this exact
+    # rejection. Any other failure stays a hard error.
+    if grep -qE "non-accelerated platform|\[v\+\+ 60-1606\]" "${VPP_LOG}"; then
+      echo "INFO: v++ --package rejected '${AIE_XSA_INPUT}' as a non-accelerated platform — falling back to bootgen automatically."
+      run_bootgen
+    else
+      echo "ERROR: v++ --package failed (rc=${VPP_RC}). See ${VPP_LOG}."
+      echo "       Force the bootgen path with: make USE_BOOTGEN_FALLBACK=1 package"
+      exit "${VPP_RC}"
+    fi
+  else
+    PDI=$(find "${AIE_PKG_DIR}" -name "pl.pdi" -o -name "*_pld.pdi" -o -name "*.pdi" 2>/dev/null | head -1)
+    if [ -z "${PDI}" ]; then
+      echo "ERROR: v++ --package succeeded but produced no PDI under ${AIE_PKG_DIR}"
+      echo "       Inspect ${VPP_LOG}; engage USE_BOOTGEN_FALLBACK=1"
+      echo "       Re-run with: make USE_BOOTGEN_FALLBACK=1 package"
+      exit 1
+    fi
+    cp -f "${PDI}" "${AIE_PDI}"
   fi
-  cp -f "${PDI}" "${AIE_PDI}"
 fi
 
 echo "AIE dynamic PDI staged: ${AIE_PDI}"

From 0e3708efdfc44c840e6ec82c536ca3492a9227e6 Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Sun, 24 May 2026 07:47:07 -0700
Subject: [PATCH 6/7] chore(vitis/aie): localize stray outputs under build/,
 keep PROJ_DIR clean

Two cleanups so AIE archetype projects don't accumulate Vitis/Bootgen
clutter in the project root:

- create_proj.py: write the synthesized aie_config.generated.cfg under
  OUT_DIR (build/) instead of PROJ_DIR. It's a regenerable build
  artifact, not user-managed, so it belongs alongside the workspace.
  Reference path drops to `../aie_config.generated.cfg` (relative to
  the component dir).

- package.sh: cd into AIE_PKG_DIR before invoking v++/bootgen so their
  CWD-anchored strays (_x/, v++.package_summary, v++_package.log,
  xcd.log, .Xil/) land in build/aie_package/ instead of PROJ_DIR. Also
  pass --temp_dir/--log_dir/--report_dir explicitly so v++ never
  re-anchors them outside AIE_PKG_DIR even when run from elsewhere.

Net effect: PROJ_DIR keeps only the source tree (Makefile, aie/,
aie_config.cfg) plus build/ and ip/. All Vitis/Bootgen working
artifacts disappear into build/.
---
 vitis/aie/create_proj.py | 11 ++++++-----
 vitis/aie/package.sh     |  9 +++++++++
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/vitis/aie/create_proj.py b/vitis/aie/create_proj.py
index 63d6d22..6bda996 100644
--- a/vitis/aie/create_proj.py
+++ b/vitis/aie/create_proj.py
@@ -65,11 +65,12 @@
 # that include= directives derived from AIE_SOURCES dest_subdirs are
 # always present alongside the user's [aie] settings — without it, the
 # aiecompiler can't resolve `adf::source("kernels/loopback.cc")` paths.
-# Lives at PROJ_DIR/aie_config.generated.cfg; included paths are relative
-# to v++'s working directory (<comp>/build/<target>/), so `../..` is the
-# component root and `../../<subdir>` is <comp>/<subdir>/.
-aie_config_generated     = os.path.join(proj_dir, 'aie_config.generated.cfg')
-aie_config_generated_rel = '../../aie_config.generated.cfg'
+# Lives under OUT_DIR (build/), keeping PROJ_DIR clean — the file is a
+# regenerable build artifact, not user-managed. include= paths are
+# relative to v++'s working directory (<comp>/build/<target>/), so
+# `../..` is the component root and `../../<subdir>` is <comp>/<subdir>/.
+aie_config_generated     = os.path.join(workspace, 'aie_config.generated.cfg')
+aie_config_generated_rel = '../aie_config.generated.cfg'
 
 if not aie_sources:
     raise SystemExit("create_proj: AIE_SOURCES is empty — list the files "
diff --git a/vitis/aie/package.sh b/vitis/aie/package.sh
index 4e47527..31057d6 100644
--- a/vitis/aie/package.sh
+++ b/vitis/aie/package.sh
@@ -45,6 +45,12 @@ echo "Using AIE archive: ${LIBADF}"
 mkdir -p "${AIE_PKG_DIR}" "${AIE_IP_DIR}"
 echo "==== package (USE_BOOTGEN_FALLBACK=${USE_BOOTGEN_FALLBACK}) ===="
 
+# Localize stray outputs. v++ and bootgen drop _x/, v++.package_summary,
+# v++_package.log, xcd.log, and .Xil/ in the invocation cwd. Run them from
+# AIE_PKG_DIR so all of that lands under build/aie_package/ instead of
+# polluting PROJ_DIR.
+cd "${AIE_PKG_DIR}"
+
 # bootgen path — assemble AIE CDO bins into a dynamic PDI directly. Used
 # when (a) USE_BOOTGEN_FALLBACK=1 is set explicitly, or (b) v++ --package
 # rejected AIE_XSA_INPUT as a non-accelerated platform. SLAC's standard
@@ -89,6 +95,9 @@ else
       --platform "${AIE_XSA_INPUT}" \
       --package.out_dir "${AIE_PKG_DIR}" \
       --package.boot_mode sd \
+      --temp_dir "${AIE_PKG_DIR}/_x" \
+      --log_dir "${AIE_PKG_DIR}/_x/logs" \
+      --report_dir "${AIE_PKG_DIR}/_x/reports" \
       "${LIBADF}" \
       2>&1 | tee "${VPP_LOG}"
   VPP_RC=${PIPESTATUS[0]}

From ce62454005bbba520238783e97d888707f511159 Mon Sep 17 00:00:00 2001
From: Larry Ruckman <ruckman@slac.stanford.edu>
Date: Sun, 24 May 2026 08:21:19 -0700
Subject: [PATCH 7/7] fix(vitis/aie): resolve AIE_XSA_INPUT to absolute path
 before cd
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit started running v++/bootgen from AIE_PKG_DIR to
localize stray outputs, but that broke callers passing AIE_XSA_INPUT as
a relative path (e.g. ../../targets/<name>/images/<name>.xsa from the
AIE project dir). v++ resolves --platform against its own cwd, so a
relative AIE_XSA_INPUT failed with "platform is not found or is not
valid" — and that error doesn't match the non-accelerated-platform
auto-fallback regex, so the build hard-failed instead of falling back.

realpath the input once at script entry, before the cd. Absolute paths
pass through unchanged.
---
 vitis/aie/package.sh | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/vitis/aie/package.sh b/vitis/aie/package.sh
index 31057d6..64aeb74 100644
--- a/vitis/aie/package.sh
+++ b/vitis/aie/package.sh
@@ -30,6 +30,11 @@ if [ ! -f "${AIE_XSA_INPUT}" ]; then
   echo "       Build the upstream Vivado target's XSA first."
   exit 1
 fi
+# Resolve AIE_XSA_INPUT to an absolute path BEFORE the `cd "${AIE_PKG_DIR}"`
+# below. Callers commonly pass it as a relative path (e.g.
+# AIE_XSA_INPUT=../../targets/.../foo.xsa from the AIE project dir) and
+# v++ resolves --platform against its own cwd.
+AIE_XSA_INPUT=$(realpath "${AIE_XSA_INPUT}")
 
 # Locate the AIE component's hw libadf.a. The Vitis Unified IDE places it
 # under <workspace>/<comp>/build/hw/ but the exact subdir can vary across