ZCU111 Programmable Logic SDFEC and RFDC Demo

This page describes an AMD Embedded Development Framework (EDF) demo for the ZCU111 RFSoC evaluation board. The demo runs PL-based Soft Decision Forward Error Correction (SDFEC) and RF Data Converter (RFDC) functionality on top of dynamically loaded PL firmware. A container bundles the matching validation tools.

Overview

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

• A container application that bundles the RFDC and SDFEC test tools (rfdc-selftest, rfdc-intr, rfdc-read-write, sdfec-demo, sdfec-interrupts, and sdfec-multi-ldpc-codes). The container also includes dfx-mgr-client support so that it can drive PL firmware that the host’s dfx-mgrd loads on the container’s behalf.

• A PL firmware recipe that packages the SDFEC and RFDC PL design for the ZCU111. The recipe uses the dfx_user_dts mechanism so that dfx-mgr can discover and load the firmware at runtime through the AMD Dynamic Function eXchange (DFX) manager.

Together, these pieces show how EDF can run a containerized validation application on top of a dynamically loaded PL design on the ZCU111.

The recipes referenced by this page (zcu111-pl-sdfec-rfdc-fw and container-app-zcu111-sdfec-rfdc) 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 recipes that make up the demo and the role each one plays.

Recipe	Type	Purpose
zcu111-pl-sdfec-rfdc-fw	PL firmware	Packages the SDFEC and RFDC PL design for ZCU111 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-zcu111-sdfec-rfdc	Container application	Builds an OCI container image that bundles rfdc-selftest, rfdc-intr, rfdc-read-write, sdfec-demo, sdfec-interrupts, and sdfec-multi-ldpc-codes, together with dfx-mgr-client so the container can interact with the loaded PL firmware.

Programmable Logic Firmware Recipe

The PL firmware recipe zcu111-pl-sdfec-rfdc-fw provides the ZCU111 SDFEC and RFDC PL design as a loadable firmware package.

The recipe inherits dfx_user_dts, which:

• compiles the recipe-supplied pl.dtsi into an overlay .dtbo;

• installs the bitstream and the overlay under /lib/firmware/xilinx/<package-name>/; and

• registers the package with dfx-mgr so that dfx-mgr-client -listPackage enumerates it on the target.

For background on the dfx_user_dts flow and how it fits into the EDF segmented build, refer to:

• AMD EDF Segmented Configuration using AMD Yocto Project Recipes

Container Application Recipe

The container application recipe container-app-zcu111-sdfec-rfdc builds an OCI container image on top of container-app-base from meta-virtualization. The container rootfs includes:

• rfdc-selftest – self-test of the RFDC driver against the loaded PL design.

• rfdc-intr – interrupt-driven RFDC test.

• rfdc-read-write – low-level RFDC register read/write utility.

• sdfec-demo, sdfec-interrupts, and sdfec-multi-ldpc-codes – SDFEC validation utilities.

• dfx-mgr-client – so the container can list and load PL firmware packages that the host’s dfx-mgr exposes.

For the general container application packaging pattern, refer to the Application Deployment page.

Building the Demo

BitBake builds the container application from a Yocto build environment. The environment must include the meta-amd-edf-demos layer and target the ZCU111 machine. The firmware is included through CONTAINER_APP.

1. Source the Yocto build environment (see Setting Up the Yocto Environment)

2. Clone meta-amd-edf-demos layer:

   $ cd ../sources
   $ git clone https://github.com/AMD-AECG-SSW-PUBLIC/meta-amd-edf-demos.git -b 2026.1
   

3. Add meta-amd-edf-demos layer

   $ cd build/
   $ bitbake-layers add-layer ../sources/meta-amd-edf-demos/
   

4. Build the container application:

   $ MACHINE=amd-cortexa53-common bitbake container-app-zcu111-sdfec-rfdc
   

The container-app-zcu111-sdfec-rfdc recipe adds zcu111-pl-sdfec-rfdc-fw to CONTAINER_APP, which includes the firmware package in the resulting container rootfs.

The generated container rootfs tarball is available under ${DEPLOY_DIR_IMAGE}/ (typically tmp/deploy/images/amd-cortexa53-common/). Copy it to the running target before continuing.

Running the Demo on the Target

The following steps assume the ZCU111 has booted an EDF image with dfx-mgr and a container runtime (for example docker or podman) installed. The steps also assume that the preceding container image is present on the target.

Using a Prebuilt Container Image

The AMD EDF Docker Hub registry publishes prebuilt images for this demo. Pulling one of those images avoids the local Yocto build and the manual bunzip2 / docker import steps in the following section.

Note

The xilinx/edf:zcu111-sdfec-rfdc-26.06 tag is available once the 26.06 image is published to the registry. Until then, use the locally built path in Using the Locally Built Container Image.

1. Pull the prebuilt EDF container image:

   $ sudo docker pull xilinx/edf:zcu111-sdfec-rfdc-26.06
   

2. Create the host-side firmware directory and the bind-mount Docker volume that the container populates:

   $ sudo mkdir -p /lib/firmware/xilinx/zcu111-pl-sdfec-rfdc-fw
   $ sudo docker volume create --name producer_consumer \
       --driver local --opt type=none --opt o=bind \
       --opt device=/lib/firmware/xilinx/zcu111-pl-sdfec-rfdc-fw
   

3. Run the container, mounting the firmware volume and the host’s dfx-mgrd socket:

   $ sudo docker run --rm --name producer_consumer \
       --privileged \
       -v /mnt:/mnt \
       -v /dev:/dev \
       -v producer_consumer:/lib/firmware/xilinx/zcu111-pl-sdfec-rfdc-fw \
       -v /var/run/dfx-mgrd.socket:/var/run/dfx-mgrd.socket \
       -it xilinx/edf:zcu111-sdfec-rfdc-26.06 bash
   

4. From the in-container shell, continue with Load PL Firmware and Run the Demo (Inside the Container) to load the PL firmware and exercise each demo tool.

Note

• The prebuilt container image already includes the required runtime components and demo applications.

• The same host-side prerequisites apply: the device nodes under /dev must be bind-mounted, and the DFX manager socket (/var/run/dfx-mgrd.socket) must be mounted for firmware loading support.

Using the Locally Built Container Image

Use this path when you built the container from source with the meta-amd-edf-demos layer (see Building the Demo) and copied the resulting rootfs tarball to the target.

Unpack and Import the Container Image

1. List the available PL firmware packages:

   $ sudo dfx-mgr-client -listPackage
   

2. Unpack the generated rootfs tarball:

   $ bunzip2 container-app-zcu111-sdfec-rfdc-amd-cortexa53-common.rootfs-<date>.tar.bz2
   

3. Import the container rootfs as a Docker image:

   $ sudo docker import \
       container-app-zcu111-sdfec-rfdc-amd-cortexa53-common.rootfs-<date>.tar
   

4. List the available container images:

   $ sudo docker images
   

Create Docker Volume and Run the Application from the Container Image

1. Create the host-side firmware directory:

   $ sudo mkdir -p /lib/firmware/xilinx/zcu111-pl-sdfec-rfdc-fw
   

2. Create a Docker volume that bind-mounts the firmware directory:

   $ sudo docker volume create --name producer_consumer \
       --driver local --opt type=none --opt o=bind \
       --opt device=/lib/firmware/xilinx/zcu111-pl-sdfec-rfdc-fw
   

3. Verify the created volume:

   $ sudo docker volume ls
   

4. Run the container with the firmware volume and dfx-mgrd socket mounted:

   $ sudo docker run --rm --name producer_consumer \
       --privileged \
       -v /mnt:/mnt \
       -v /dev:/dev \
       -v producer_consumer:/lib/firmware/xilinx/zcu111-pl-sdfec-rfdc-fw \
       -v /var/run/dfx-mgrd.socket:/var/run/dfx-mgrd.socket \
       -it <image_id> bash
   

5. From the in-container shell, continue with Load PL Firmware and Run the Demo (Inside the Container).

Load PL Firmware and Run the Demo (Inside the Container)

These steps run from the bash-5.2# shell inside the container started by either path above. The container’s dfx-mgr-client reaches the host’s dfx-mgrd over the bind-mounted /var/run/dfx-mgrd.socket.

1. List the available PL firmware packages and note the zcu111-pl-sdfec-rfdc-fw ID:

   bash-5.2# dfx-mgr-client -listPackage
   

2. Load the SDFEC and RFDC PL firmware. Use one of the following forms:

   bash-5.2# dfx-mgr-client -loadByName zcu111-pl-sdfec-rfdc-fw
   

   or, by the numeric ID reported by -listPackage (for example 3):

   bash-5.2# dfx-mgr-client -load <ID>
   

3. Confirm that the package now shows as loaded by re-running dfx-mgr-client -listPackage.

4. Run the demo tools:

   bash-5.2# rfdc-selftest
   bash-5.2# rfdc-intr
   bash-5.2# rfdc-read-write
   bash-5.2# sdfec-demo
   bash-5.2# sdfec-interrupts
   bash-5.2# sdfec-multi-ldpc-codes
   

Note

The exact command-line options for rfdc-selftest, rfdc-intr, rfdc-read-write, sdfec-demo, sdfec-interrupts, and sdfec-multi-ldpc-codes follow the upstream tool usage. Run each tool with --help (or the tool’s documented help flag) inside the container for the full option list.

Unloading the Programmable Logic Firmware

When the demo finishes, unload the firmware. The unload talks to the same dfx-mgrd over /var/run/dfx-mgrd.socket, so it can run either from the host or from inside the container:

$ sudo dfx-mgr-client -unloadByName zcu111-pl-sdfec-rfdc-fw

References

• zcu111-pl-sdfec-rfdc-fw_1.0-2026.1.bb

• container-app-zcu111-sdfec-rfdc.bb

• dfx_user_dts.bbclass

• container-app-base.bb

• AMD EDF prebuilt container images (Docker Hub) – prebuilt demo images, including the ZCU111 SDFEC/RFDC image.