Unified Guide for Versal Gen 2 PL Loading and Yocto Integration

This page consolidates the PL deployment guidance for VEK385 into one place. It covers two practical workflows:

  1. Non-Yocto: generate/copy pl.dtsi/dtbo + PDI and load on target.

  2. Yocto: create a custom layer/machine integration that installs PL firmware in the image.

Non-Yocto Workflow

Generate PL Artifacts

  1. Clone Example Hardware Repo

    Use the official example or your custom design:

    $ git clone https://github.com/Xilinx/amd-yocto-hw-platforms.git -b xilinx_v2026.1
$ cd amd-yocto-hw-platforms/eval_board_examples/vek385_axi_uartlite

  2. Build the Design

    $ source <path to Vivado Install>/Vivado/settings64.sh
$ make all JOBS=8
$ make gen_overlay

    This generates:

    • pl.dtsi (Device Tree Source Include)

    • pl.dtbo (Device Tree Overlay Binary)

    • <design>_pld.pdi (Partial PDI)

    • shell.json (for dfx-mgr)

    Output directory: <design>-fw/ (e.g., vek385_axi_uartlite-fw/)

  3. Manual Flow (Vivado GUI/CLI)

    • Open base Vivado project.

    • Modify/add IP blocks as needed.

    • Make sure the golden .ncr file from the base project is included.

    • Generate XSA, run SDTGen, and create the firmware bundle as described above.

References:

Transfer and Load on Target

  1. Copy Firmware Bundle to Target

    # scp -r <user>@<host/ ip address>:<path to firmware directory>/vek385_axi_uartlite-fw /lib/firmware/xilinx/.

  2. List Available Packages

    # dfx-mgr-client -listPackage

    Use the numeric value from the ID column when loading by ID.

  3. Load the PL Firmware

    # dfx-mgr-client -loadByName vek385_axi_uartlite-fw

    The PL is now loaded and device drivers are updated through the overlay.

    Alternative: Using fpga-util

    # fpgautil -b /lib/firmware/xilinx/vek385_axi_uartlite-fw/vek385_axi_uartlite_pld.pdi -o /lib/firmware/xilinx/vek385_axi_uartlite-fw/pl.dtbo

    Use -f Partial for partial reconfiguration if needed.

  4. Use the Right Tool (and avoid mixed guidance)

    Use this rule to remove ambiguity:

    • Use fpgautil when you want direct, explicit loading of a flat/segmented PL payload (.pdi) and overlay (.dtbo) by path.

    • Use dfx-mgr when you need package discovery, slot-aware DFX accelerator load/unload, or daemon-managed runtime behavior.

    • For VEK385 segmented configuration bring-up, start with fpgautil. Move to dfx-mgr only when you need managed DFX package operations.

References:

Yocto Workflow

Generate PL Artifacts

Use gen-machine-conf with the SDT handoff directory from Vivado/SDTGen to produce pl.dtsi matching your hardware:

$ gen-machine-conf parse-sdt --template <template-yaml> --hw-description <path-to-sdt-handoff-dir> -O <machine-override> --machine-name <machine-name>

  • For segmented config: add -g full

  • Output: pl.dtsi matching your hardware

References:

Create a Yocto Recipe

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

  2. Create Layer and Recipe

    $ bitbake-layers create-layer <path-to-meta-custom>
$ bitbake-layers add-layer <path-to-meta-custom>
$ mkdir -p <path-to-meta-custom>/recipes-firmware/<firmware-app>/files
$ cp <your files> <path-to-meta-custom>/recipes-firmware/<firmware-app>/files/
$ recipetool create -o <path-to-meta-custom>/recipes-firmware/<firmware-app>/<firmware-app>.bb file://<path-to-meta-custom>/recipes-firmware/<firmware-app>/files

  3. Edit the Recipe to Use dfx_user_dts

    Example vek385-axi-uartlite-fw.bb:

    SUMMARY = "VEK385 AXI UARTLite PL firmware"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

inherit dfx_user_dts

SRC_URI = " \
    file://vek385_axi_uartlite_pld.pdi \
    file://pl.dtsi \
    file://pl.dtbo \
    file://shell.json \
"

COMPATIBLE_MACHINE ?= "^$"
COMPATIBLE_MACHINE:versal-2ve-2vm-vek385-sdt-seg = "${MACHINE}"

# Install directory under /lib/firmware/xilinx/
FW_INSTALL_DIR = "vek385_axi_uartlite-fw"

    • For segmented config, shell.json is optional.

    • For DFX, include shell.json.

  4. Content of shell.json

    {
    "shell_type": "XRT_FLAT",
    "num_slots": "1"
}

  5. Steps to generate pl.dtbo

    pl.dtsi is generated in the build/conf/dts/${MACHINE}/pl-overlay-full by the preceding gen_machineconf step. Convert pl.dtsi to pl.dtbo:

    $ dtc -I dts -O dtb -o pl.dtbo pl.dtsi

References:

  1. Add to Image and Enable Overlay

    In local.conf:

    MACHINE_FEATURES += "fpga-overlay"
IMAGE_INSTALL:append = " vek385-axi-uartlite-fw fpga-manager-script"

  2. Build and Deploy

    $ MACHINE=<machine-name> bitbake <image-name>

    The recipe installs the firmware to /lib/firmware/xilinx/vek385_axi_uartlite-fw/ on the target.

Load PL from Yocto Image

Use dfx-mgr-client or fpgautil as in the preceding example to load the PL and overlay.

Directory Structure

Firmware Bundle Example:

vek385_axi_uartlite-fw/
├── pl.dtbo
├── pl.dtsi
├── shell.json
└── vek385_axi_uartlite_pld.pdi

Yocto Firmware Directory:

/lib/firmware/xilinx/vek385_axi_uartlite-fw/
├── pl.dtbo
├── pl.dtsi
├── shell.json
└── vek385_axi_uartlite_pld.pdi

Quick Reference

Use Case

Steps

Key Tools/Files

Rapid Dev

Build with Makefile or Vivado, transfer to /lib/firmware/xilinx, load with dfx-mgr-client or fpgautil

pl.dtsi, pl.dtbo, <design>_pld.pdi, shell.json

Yocto Layer

Generate pl.dtsi, create recipe with dfx_user_dts, add to image, deploy

Same as the preceding row, plus Yocto recipe

References