This is a getting started guide providing walk through style examples using the AMD Embedded Development Framework (EDF) covering initial board setup and running a pre-built disk image, hardware and software applications development using the pre-built image, and full custom hardware & software builds and image creation.

Table of Contents

Hardware Application Development

Open

Custom RTL or hardware design is a key part of the value of Adaptive SOC and FPGA devices.

This section shows to generate PL images (payloads) that are compatible with a base design such as the EDF pre-built disk images and OSPI boot images utilizing Segmented Configuration. See also https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586143

These flows enable different payloads (PL or other) to be deployed to a board and then loaded or re-loaded from Linux at run time, speeding up development (by testing on a running system) and enabling dynamic payload management on deployed systems with Linux / U-boot as the system manager (for example version management, fallback, recovery).

This example is based on and compatible with the Embedded Common Platform CED design which is the Vivado design used to create the EDF BSP’s, the EDF pre-built OSPI firmware and EDF Linux Disk images.

• The Tcl scripts to build a compatible PL payload via a scripted flow are available here (See relevant folder for your Evaluation board): amd-yocto-hw-platforms/eval_board_examples/vek385_bram_gpio_timer at xlnx_rel_v2025.1 · Xilinx/amd-yocto-hw-platforms

• The flow to re-generate the base image (which this payload is compatible with) is covered in https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258188188/Custom+Hardware+Development+AMD+Versal+device+portfolio#Vivado-base-design-and-base-platform

PL design / payload content:

The PL IP example application has the below IPs:

• AXI BRAM

• AXI GPIO

  • GPIO0: x4 User LEDs 

  • GPIO1: x2 User push buttons

  • GPIO2: x4 User DIP switches

• AXI TIMER

The block design is shown below, and can be viewed in Vivado after generation.

The steps to generate this compatible design are similar to the steps used when generating the base design, and use the XPR and XSA from the base design as inputs.

Block design image (VEK385):

Maintaining and checking compatibility of a generated PL firmware application (child design) with the base/parent Vivado project

Compatibility is enabled and verified through the Segmented Configuration workflows in Vivado, using some files created when the base / parent project was compiled.

• See the following pages for more information on Segmented Configuration

  • Vivado-Design-Tutorials/Versal/Boot_and_Config/Segmented_Configuration at 2024.2 · Xilinx/Vivado-Design-Tutorials

  • https://www.amd.com/content/dam/amd/en/documents/products/adaptive-socs-and-fpgas/vivado/segmented-configuration.pdf

NOC solution file (.ncr) from base project

Post compile UID checks

PL Design Unique ID

$ make checkpdi PDI_UNIQUE_ID:0xe2261acc GOLDEN_UNIQUE_ID:0xe2261acc UNIQUE ID MATCHED The above check only compares the vivado base ced boot.pdi UNIQUE ID with child design boot.pdi UNIQUE ID. Read the unique id of boot.pdi which is packed as part boot.bin/ospi.bin using the attached script. If above PDI_UNIQUE_ID and below boot.bin/ospi.bin UNIQUE ID should match then only you can use boot.bin/ospi with child design firmware Open   For boot.bin $ ./get_uniqueid.sh <downloaded artifacts>/versal-2ve-2vm-vek385-sdt-seg_xilinx-bootbin/boot.bin boot.bin Specified Boot.bin Reading BIN file from offset: 0x0 *** Unique ID of BANK offset 0x0 is 0xe2261acc For ospi.bin $ ./get_uniqueid.sh <downloaded artifacts>/versal-2ve-2vm-vek385-sdt-seg_edf-ospi/edf-ospi-versal-2ve-2vm-vek385-sdt-seg.bin Reading BIN file from offset: 0x1580000 *** Unique ID of BANK offset 0x1580000 is 0xe2261acc Reading BIN file from offset: 0x87C0000 *** Unique ID of BANK offset 0x87C0000 is 0xe2261acc

DCP file check with pr_verify

We have segmented based parent and child designs. During design generation, the NoC routing will be captured in dcp files. We need to ensure that the routing should be same across parent and child design.

We need to run pr_verify using dcp files as in the example below using the sample Tcl file

cat pr_verify.tcl

pr_verify -initial <path to dcp from parent design/vek385_base.runs/impl_1/versal_gen2_platform_wrapper_routed.dcp> -additional <path to child design dcp/vek385_bram_gpio_timer.runs/impl_1/versal_gen2_platform_wrapper_routed.dcp >

The above pr_verify.tcl should be run in Vivado batch mode as shown below 

Building a compatible PL design payload and creating a Firmware Bundle (Device Tree Overlay)

Refer to Hardware Design Repo Overview for cloning the hardware design repo and for setting up the AMD tools.

This example can be built using the following make commands which build the design artifacts for the BRAM/GPIO/TIMER example design, which is compatible with EDF pre-built disk image and base design for the board. (VEK385 is shown, update paths for your evaluation board). The makefile uses Tcl (main.tcl and gen_sdt.tcl) scripts as a part of make steps to build the design and generate the output files

The generated directories will be created

• Vivado project directory hw_project - The folder contains the XPR project file which can be used to open and edit the project in Vivado

• SDT directory hw_project_sdt - The SDT directory is needed to generate the firmware bundle 

• Firmware directory <designname>-fw (VEK385 example vek385_bram_gpio_timer-fw)  - The firmware directory contains the pld PDI, the matching device tree overlay binary (dtbo), and a metadata json file

The generated firmware directory will include:

• shell.json - This metadata file is consumed by dfx-mgr

• pl.dtbo - The device tree overlay binary describes the devices in the incremental hardware design. It is used by Linux to load the corresponding device drivers

• <design name>_pld.pdi (VEK385 example - vek385_bram_gpio_timer_pld.pdi) - The pld PDI is the incremental PL payload that gets loaded from Linux on top of the boot PDI

Example output (from VEK385 design)-

Custom Designs- Manual Flows for building the compatible PL design payload and creating a Firmware Bundle (Device Tree Overlay)

All steps contained in the Makefile be done manually through the Vivado GUI and command line utilities.

Create the Compatible PL design in the GUI.

1. Open the parent / base Vivado project in the Vivado GUI

   1. Follow the steps in https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258188188 then open the design in the Vivado GUI

2. Create a new PL payload by modifying or extending the default PL payload - Add or modify IP blocks in the block design add custom logic etc.

3. Save the updated design

4. Ensure the NCR file has been added to the project. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258090078/Hardware+Application+Development#NOC-solution-file-(.ncr)-from-base-project )

5. Generate output products and the XSA.

6. Validate the compatibility of the project by following relevant sections. See - https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258090078/Hardware+Application+Development#Post-compile-UID-checks and https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258090078/Hardware+Application+Development#DCP-file-check-with-pr_verify

Create the SDTgen design artifacts (hand off information)

Note: make sdt can be used build the SDTgen design artifacts from the XSA.

Create the firmware bundle to enable dfx-mgr-client to manage multiple PL Payloads and configure the PL from Linux

• Firmware bundle - a directory containing device tree overlay (.dtbo), PL payload (.pdi) and .json file (dfx-mgr-client configuration file)

Note: make gen_overlay can be used build the firmware bundle from the SDTGen artifacts

1. Create a directory to contain the files in the firmware bundle, and copy in the source *_pld.pdi file

2. Create a shell.json file in the firmware bundle directory (<project name>-fw) with the following content :

3. Use Lopper to create the Linux Device Tree from the System Device Tree

4. Use Device Tree Compiler to create the device tree overlay (.dtbo)

You now have a firmware bundle (directory) that can be transferred to the running system for use.

Deploying the PL firmware application onto target

The firmware files can be copied to the /lib/firmware/xilinx directory on the running system for immediate use - using SCP, TFTP or a similar network tool, or via direct copy to the SDCARD. See GitHub - Xilinx/dfx-mgr for more information on dfx-manager.

Optionally the firmware bundle could be packaged and included as part of the Yocto image build by writing a Yocto recipe - https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258090263/Application+Deployment+using+Yocto+Recipes+AMD+Versal+device+portfolio#Firmware-Bundle

Listing and loading the firmware package (vek385 example):

Running the pl axi _timer example after deploying pl firmware

Related Links

• https://xilinx-wiki.atlassian.net/wiki/x/bQCRvw

• Software Hardware Exchange Loop (SHEL) FlowPreview

• Vivado-Design-Tutorials/Versal/Boot_and_Config/Segmented_Configuration at 2025.1 · Xilinx/Vivado-Design-Tutorials

• https://www.amd.com/content/dam/amd/en/documents/products/adaptive-socs-and-fpgas/vivado/segmented-configuration.pdf

Trademarks

Yocto Project and all related marks and logos are trademarks of The Linux Foundation. This website is not, in any way, endorsed by the Yocto Project or The Linux Foundation.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.