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

1. Rapid development: quickly generate/copy pl.dtsi/dtbo + PDI and load on target.

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

1. Rapid Development: Quickly Create & Transfer pl.dtsi/dtbo and PDI

A. Generate PL Artifacts (PDI, pl.dtsi, pl.dtbo)

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 xlnx_rel_v2025.2 cd amd-yocto-hw-platforms/eval_board_examples/vek385_bram_gpio_timer

2. Build the Design

   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_bram_gpio_timer-fw/)

3. Manual Flow (Vivado GUI/CLI)

   • Open base Vivado project.

   • Modify/add IP blocks as needed.

   • Ensure the golden .ncr file from the base project is included.

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

   References:

   • Hardware Application Development

B. Transfer & Load on Target

1. Copy Firmware Bundle to Target

   scp -r vek385_bram_gpio_timer-fw <user>@<target_ip>:/lib/firmware/xilinx/

2. List Available Packages

   sudo dfx-mgr-client -listPackage

3. Load the PL Firmware

   sudo dfx-mgr-client -load vek385_bram_gpio_timer-fw

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

   Alternative: Using fpga-util

   sudo fpgautil -b /lib/firmware/xilinx/vek385_bram_gpio_timer-fw/vek385_bram_gpio_timer_pld.pdi -o /lib/firmware/xilinx/vek385_bram_gpio_timer-fw/pl.dtbo

   • Use -f Partial for partial reconfiguration if needed.

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

• 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.

5. References:

   • https://github.com/Xilinx/dfx-mgr/blob/master/README.md

   • Solution Versal PL Programming

2. Yocto Integration: Create a Layer for a Custom Machine (with PL Content)

A. Generate pl.dtsi with gen-machine-conf

• Use the SDT handoff directory from Vivado/SDTGen:

  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:

  • https://github.com/Xilinx/gen-machine-conf/blob/main/README.md

  • AMD EDF - Segmented Configuration using AMD Yocto Project recipes

B. Create a Yocto Firmware Recipe

1. 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

2. Edit the Recipe to Use dfx_user_dts
   Example firmware-app.bb:

   SUMMARY = "vek385 segmented PL firmware" LICENSE = "MIT" LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" inherit dfx_user_dts SRC_URI = " \ file://vek385_bram_gpio_timer_pld.pdi \ file://pl.dtsi \ file://pl.dtbo \ file://shell.json \ " COMPATIBLE_MACHINE:vek385 = "${MACHINE}"

   • For segmented config, shell.json is optional.

   • For DFX, include shell.json.

3. Content of shell.json

4. Steps to generate pl.dtbo

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

4. References:

   • https://raw.githubusercontent.com/Xilinx/meta-xilinx/rel-v2024.2/meta-xilinx-core/classes-recipe/dfx_user_dts.bbclass

   • README.dfx.user.dts.md

5. Add to Image and Enable Overlay
   In local.conf:

   MACHINE_FEATURES += "fpga-overlay" IMAGE_INSTALL:append = " firmware-app fpga-manager-script"

6. Build and Deploy

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

   • The firmware will be installed to /lib/firmware/xilinx/<firmware-app>/ on the target.

C. Load PL from Yocto Image

• Use dfx-mgr-client or fpgautil as above to load the PL and overlay.

3. Directory Structure & Key Files

• Firmware Bundle Example:

  vek385_bram_gpio_timer-fw/ ├── pl.dtbo ├── pl.dtsi ├── shell.json └── vek385_bram_gpio_timer_pld.pdi

• Yocto Firmware Directory:

  /lib/firmware/xilinx/<firmware-app>/ ├── pl.dtbo ├── pl.dtsi ├── shell.json └── <design>_pld.pdi

4. References & Further Reading

• Hardware Application Development

• Solution Versal PL Programming

• AMD EDF - Segmented Configuration using AMD Yocto Project recipes

• https://github.com/Xilinx/dfx-mgr/blob/master/README.md

• README.dfx.user.dts.md

• dfx_user_dts.bbclass

Summary Table