Versal Base NoC Performance Demo

This cookbook is written for the VEK280 board only.

This page describes an AMD Embedded Development Framework (EDF) demo for Versal evaluation boards. The demo takes the base-noc-perf container from a Yocto build, deploys it to a Versal target, loads the NoC performance device-tree overlay with fpgautil, and exercises the NoC performance monitor.

Overview

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

  • A firmware recipe (<board>-base-noc-perf) that fetches the NoC performance overlay and installs the dtbo under /lib/firmware/xilinx/<board>-base-noc-perf/.

  • A container application recipe (container-app-<board>-base-noc-perf) that builds a container image bundling packagegroup-core-base-utils (in-container shell environment), fpga-manager-script (for fpgautil), perf, util-linux-dmesg, util-linux-mount, and the firmware package so that the overlay can be loaded and the NoC performance monitor exercised from inside the container.

Together these pieces demonstrate how EDF can load a NoC performance overlay dynamically and measure on-die interconnect traffic on Versal devices.

Supported Boards

The examples on this page use VEK280. For other Versal boards, replace vek280 with the target board name throughout.

Board

MACHINE

VCK190

amd-cortexa72-common

VEK280

amd-cortexa72-common

VMK180

amd-cortexa72-common

VPK120

amd-cortexa72-common

VPK180

amd-cortexa72-common

VRK160

amd-cortexa72-common

VRK165

amd-cortexa72-common

Note

The DDR memory controller (DDRMC) performance events are unavailable on VPK180. perf list lists NoC master unit (NMU) events, but does not list DDRMC events. See Known Issues for the release in which they are expected.

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.2 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 recipe:

$ MACHINE=amd-cortexa72-common bitbake container-app-vek280-base-noc-perf

Running the Demo on the Target

The following steps assume the board has booted an EDF image with a container runtime (for example docker) installed, and that the container tarball is available for copying to the target.

Copy the Artifact to the Target

Copy the container rootfs tarball to the running target:

$ scp <build-dir>/tmp/deploy/images/amd-cortexa72-common/\
container-app-vek280-base-noc-perf-amd-cortexa72-common.rootfs.tar.bz2 \
  root@<target-ip>:/home/amd-edf/

Import the Container Image

On the target, unpack and import the container tarball into Docker:

amd-edf:~$ cd /home/amd-edf
amd-edf:~$ bunzip2 container-app-vek280-base-noc-perf-amd-cortexa72-common.rootfs.tar.bz2
amd-edf:~$ docker import container-app-vek280-base-noc-perf-amd-cortexa72-common.rootfs.tar vek280_noc

Confirm the image appears in the list (Docker tags it vek280_noc:latest):

amd-edf:~$ docker images

Prepare the Host Firmware Directory and Volume

fpgautil loads the overlay through the kernel firmware loader (request_firmware), which reads the host kernel’s firmware search path. Expose the container’s firmware directory to the host through a bind-mounted Docker volume so the host kernel can find the dtbo. Do this one time per app. The volume is persistent.

amd-edf:~$ sudo mkdir -p /lib/firmware/xilinx/vek280-base-noc-perf
amd-edf:~$ sudo docker volume create \
    --name vek280-noc \
    --driver local \
    --opt type=none \
    --opt o=bind \
    --opt device=/lib/firmware/xilinx/vek280-base-noc-perf

On first run, Docker copies the container’s dtbo into this (empty) host directory, so /lib/firmware/xilinx/vek280-base-noc-perf/ on the host will contain vek280-base-noc-perf.dtbo.

Run the Container

Start an interactive container session, exposing the firmware volume and configfs so that the in-container tools can load the overlay:

amd-edf:~$ sudo docker run --rm -it --privileged \
    -v vek280-noc:/lib/firmware/xilinx/vek280-base-noc-perf \
    -v /sys/kernel/config:/sys/kernel/config \
    vek280_noc:latest /bin/bash
  • /bin/bash – required because CONTAINER_APP_CMD is empty (no entrypoint).

  • --privileged – required to write configfs / sysfs and load the overlay.

  • -v vek280-noc:... – exposes the app firmware to the host firmware path.

  • -v /sys/kernel/config:/sys/kernel/config – configfs for device-tree overlays.

Inside the container you are running as root, as shown by the # prompt in the commands that follow.

Set the Kernel Firmware Search Path

fpgautil asks the kernel to load the overlay by basename, and the kernel only searches its standard firmware directories. From inside the container, point it at the app firmware directory so it can find the dtbo:

# echo -n /lib/firmware/xilinx/vek280-base-noc-perf \
    > /sys/module/firmware_class/parameters/path

Verify the search path and that the dtbo is present:

# cat /sys/module/firmware_class/parameters/path
# ls -l /lib/firmware/xilinx/vek280-base-noc-perf/

Load the NoC Performance Overlay

First clear any stale default region left over from a previous run, then load the overlay with fpgautil:

# rmdir /sys/kernel/config/device-tree/overlays/full 2>/dev/null
# fpgautil \
    -o /lib/firmware/xilinx/vek280-base-noc-perf/vek280-base-noc-perf.dtbo \
    -n vek280-base-noc-perf

Confirm it applied. The status file reads applied when the overlay is live, and the kernel log records the overlay application:

# cat /sys/kernel/config/device-tree/overlays/vek280-base-noc-perf/status
# dmesg | tail -20

Verify the NoC PMU Device

The overlay adds the NoC performance monitor device (amd,noc-pmu). List the platform devices to confirm the device node amd-noc-pmu was created, then check for its driver symlink. The symlink is present only after a driver has bound to the device. If the platform device exists but has no driver symlink and perf list reports no NoC events, the NoC performance monitor driver is not enabled in the running kernel and must be built in or loaded as a module:

# ls /sys/bus/platform/devices/ | grep -i noc
# ls -l /sys/bus/platform/devices/amd-noc-pmu/driver

Run a NoC Performance Measurement

After the performance monitor is available under perf, discover the NoC events, then count one of them over a fixed interval, for example five seconds:

# perf list | grep -i noc
# perf stat -a -e <noc_pmu>/<event>/ sleep 5

Replace <noc_pmu> / <event> with the names shown by perf list.

For example, count read bytes on NoC master unit nmu_6 for one second:

# perf stat -e amd-noc-pmu/nmu_6_read_byte/ sleep 1

 Performance counter stats for 'system wide':

            9408      amd-noc-pmu/nmu_6_read_byte/

     1.002059704 seconds time elapsed

Unloading the NoC Performance Overlay

When the demo finishes, unload the overlay:

# fpgautil -R -n vek280-base-noc-perf

Alternatively, remove the overlay directory from configfs directly:

# rmdir /sys/kernel/config/device-tree/overlays/vek280-base-noc-perf

Reload the overlay to repeat the experiments:

# fpgautil \
    -o /lib/firmware/xilinx/vek280-base-noc-perf/vek280-base-noc-perf.dtbo \
    -n vek280-base-noc-perf

Exit the container with exit. With --rm the container is removed on exit. The image and the persistent firmware volume remain.