Versal AI Engine Global Memory I/O Out-of-Box Demo

This page describes an AMD Embedded Development Framework (EDF) demo for Versal evaluation boards. The demo runs an AI Engine (AIE) matrix-multiplication workload that transfers data through Global Memory I/O (GMIO) between the PS and the AIE array. A container bundles the application binary together with the matching PL firmware management tools so that everything runs inside an OCI container on top of an EDF image.

Overview

The demo combines two pieces that ship through the meta-amd-edf-demos Yocto layer:

A container application recipe that builds an OCI container image bundling the AIE GMIO matrix-multiplication application binary together with dfx-mgr-client (so the container can load and interact with the PL firmware that the host exposes) and packagegroup-core-base-utils (for the in-container shell environment).
A PL firmware recipe that packages the AIE GMIO PL design for the target board and installs it under /lib/firmware/xilinx using the dfx_user_dts mechanism so that dfx-mgr can discover and load it at runtime.

Together these pieces demonstrate how EDF can run a containerized AIE application on top of a dynamically loaded PL design on Versal devices.

The recipes referenced by this page live in the meta-amd-edf-demos layer; see References at the bottom of this page for the upstream recipe URLs.

Demo Components

The following table summarizes the two recipe types that make up the demo and the role each one plays.

Recipe	Type	Purpose
`<board>-pl-aie-gmio-fw`	PL firmware	Packages the AIE GMIO PL design for the `<board>` and installs it under `/lib/firmware/xilinx` using the `dfx_user_dts` mechanism so that `dfx-mgr-client` can load it at runtime.
`container-app-<board>-aie-gmio`	Container application	Builds an OCI container image that bundles the AIE GMIO matrix-multiplication application binary and `dfx-mgr-client` so the container can interact with the loaded PL firmware. One recipe variant exists per supported board (see supported boards).

Supported Boards

The following table lists the boards and corresponding BitBake MACHINE values used when building the container application.

Board	Container recipe	`MACHINE`
VCK190	`container-app-vck190-aie-gmio`	`amd-cortexa72-common`
VEK280	`container-app-vek280-aie-gmio`	`amd-cortexa72-common`
VEK385	`container-app-vek385-aie-gmio`	`amd-cortexa78-mali-common`

Building the Demo

BitBake builds the container application recipe from a Yocto build environment. The environment must include the meta-amd-edf-demos layer.

Clone the meta-amd-edf-demos layer:

$ git clone -b rel-v2026.1 https://github.com/Xilinx/meta-amd-edf-demos \
      sources/meta-amd-edf-demos

Set up the Yocto environment and add the demos layer:

$ source edf-init-build-env
$ bitbake-layers add-layer ../sources/meta-amd-edf-demos/

Build the container application for the target board. Choose the command that matches your hardware:

$ MACHINE=amd-cortexa72-common bitbake container-app-vck190-aie-gmio
$ MACHINE=amd-cortexa72-common bitbake container-app-vek280-aie-gmio
$ MACHINE=amd-cortexa78-mali-common bitbake container-app-vek385-aie-gmio

The output is a compressed container rootfs tarball (container-app-<board>-aie-gmio-<machine>.rootfs.tar.bz2) in the BitBake deploy directory. Copy this file to the running target for ad-hoc evaluation.

Note

The meta-amd-edf-demos layer also provides a matching PL firmware recipe for each board (for example, <board>-pl-aie-gmio-fw). The firmware is installed automatically when it is included in the target image, or it can be copied to the board manually for evaluation.

Running the Demo on the Target

The following steps treat <board> and <machine> as placeholders. Replace <board> with your actual board name (for example, vek385) and <machine> with the corresponding MACHINE value throughout.

The steps assume the board has booted an EDF image with dfx-mgr and a container runtime (for example docker or podman) installed, and that the container tarball and PL firmware files are already present on the target.

Prepare the Firmware Directory

The firmware directory /lib/firmware/xilinx/<board>-pl-aie-gmio-fw must contain aie-matrix-multiplication.xclbin, pl.dtso, shell.json, and aie-matrix-multiplication.dtbo. These files are installed automatically when the PL firmware recipe is included in the target image. If they are not already on the target, create the directory and copy the four files in by hand (skip this step if the firmware was installed automatically by the image):

amd-edf:~$ sudo mkdir -p \
    /lib/firmware/xilinx/<board>-pl-aie-gmio-fw

Create a Docker Volume for the Firmware

Create a named Docker volume that maps to the firmware directory so that the container can reach the PL firmware files:

amd-edf:~$ sudo docker volume create \
    --name aie-matrix-multiplication \
    --driver local \
    --opt type=none \
    --opt o=bind \
    --opt device=/lib/firmware/xilinx/<board>-pl-aie-gmio-fw

Verify that the volume was created:

amd-edf:~$ sudo docker volume ls

Import the Container Image

Extract and import the container tarball into the local container runtime (skip this step if the image is already present):

amd-edf:~$ bunzip2 container-app-<board>-aie-gmio-<machine>.rootfs.tar.bz2
amd-edf:~$ sudo docker import \
    container-app-<board>-aie-gmio-<machine>.rootfs.tar \
    container-app-<board>-aie-gmio:latest

Confirm the image is listed:

amd-edf:~$ sudo docker images

Run the Container

Start an interactive container session, exposing the host dfx-mgr socket, devices, and firmware volume so that the in-container tools can reach the PL design:

amd-edf:~$ sudo docker run \
    --name aie-matrix-multiplication \
    --privileged \
    -v aie-matrix-multiplication:/lib/firmware/xilinx/<board>-pl-aie-gmio-fw \
    -v /var/run/dfx-mgrd.socket:/var/run/dfx-mgrd.socket \
    -v /dev/:/dev/ \
    -it container-app-<board>-aie-gmio:latest bash

Load the Programmable Logic Firmware

From inside the running container, load the AIE GMIO PL firmware:

# dfx-mgr-client -loadByName <board>-pl-aie-gmio-fw

Confirm the package shows as loaded:

# dfx-mgr-client -listPackage

Run the Matrix-Multiplication Application

Execute the matrix-multiplication application, passing the .xclbin file as an argument:

# aie-matrix-multiplication \
    /lib/firmware/xilinx/<board>-pl-aie-gmio-fw/aie-matrix-multiplication.xclbin

The application runs the AIE GMIO matrix-multiplication workload and prints the result to the console.

Unloading the Programmable Logic Firmware

When the demo finishes, exit the container and unload the firmware from the host:

amd-edf:~$ sudo dfx-mgr-client -unloadByName <board>-pl-aie-gmio-fw