/
Custom Hardware Development AMD Versal™ device portfolio

Custom Hardware Development AMD Versal™ device portfolio

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 and software builds and image creation.

Table of Contents

Custom Hardware Development

A hardware developer can create one or more hardware (HW) designs, resulting in one or more firmware bundles (boot.pdi, PL.pdi). The firmware can be integrated with or built with the OS and boot images. A software application can interact with the hardened and/or adaptive features of the hardware design.

We will differentiate between the base HW design firmware which is baked into the boot image, and application-specific incremental HW design firmware that is loaded into the PL at Linux run-time in support of a specific application.

The following tutorials show how to generate a base HW design and its firmware package and two examples of application-specific HW designs and firmware. One is a Vivado™ Design Suite based design (RTL), the other a Vitis™ software platform-based design. We also show how to generate various handoff artifacts needed when moving from HW to the SW or OS domain.

Typically, a hardware design team provides a new custom base HW design/Vivado™ Design Suite XSA that matches their product requirements, for example, a custom board or even a static PL design if the production image has a fixed function. The XSA is handed off to the OS development team which then generates a new Yocto Project™ machine configuration based on this base XSA using the provided sdtgen and gen-machine-conf tooling as a starting point (see https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3164209163).

The EDF Linux® distribution (distro) can be used as starting point for the OS build, but the end-user can also opt to use the upstream Yocto Project poky distro or their own custom distro for their final product based on their product requirements. Customizing the OS configuration might require expert knowledge. Some common items are covered here https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586081 , and there is extensive documentation available online for this purpose (Yocto Project Mega-Manual ) .

Similarly, creating and customizing your own Vivado Design Suite/RTL design might require expert knowledge and there is extensive documentation available on this subject.

AMD EDF 25.05 (VEK385 EA) - AMD Vivado™ Design Suite 2025.2

  • A Vitis™ software platform-based design is not included in this release. This is scheduled for inclusion after the AMD Vivado™ Design Suite 2025.2 release.

image-20250328-112709.png

EDF Hardware Design Repository Overview

The following section gives an overview of the hardware design repository which provides the baseline for the Yocto Project™ machine configuration used in this tutorial.

$ git clone https://github.com/Xilinx/amd-yocto-hw-platforms.git -b xlnx_rel_v2025.2 #example for xlnx_rel_v2025.2 version. $ cd amd-yocto-hw-platforms $ tree eval_board_base/vek385_base/ eval_board_base/vek385_base/ ├── Makefile └── scripts     ├── gen_sdt.tcl     └── main.tcl

Ensure you use the branch of amd-yocto-hw-platforms that matches the EDF version in use

Its recommended to use the latest version available.

See https://xilinx-wiki.atlassian.net/wiki/x/RgPAwQ for detail on released versions.

The directory structure lists the VEK385 base design that can be built from the EDF Hardware Design repo:

  1. <board name>_base - This is the embedded common platform CED design mapped to a target evaluation board, it enables segmented configuration which allows deployment of a common boot PDI (loaded from the primary boot device by the EDF Boot Firmware), and a PL PDI loaded at Linux runtime (deferred PL load).
    The embedded common platform CED includes a minimal PL payload that has some basic peripherals mapped to the evaluation board: PL UART, DIP switch, push buttons, and user LEDs via a pair of AXI GPIO controllers, and a simple BRAM controller. The PL payload firmware (PL PDI, and device tree PL .dtbo) will be loaded after Linux boot from the user space.

A top-level Makefile is provided for easy build orchestration. Each of the above-mentioned designs can easily be built with a single make command. The make command builds a series of artifacts:

  1. The hardware design which typically ends with exporting a Vivado™ Design Suite XSA.

  2. The system device tree (SDT) artifacts directory which is needed for handoff to the software build flow - Yocto Project™ build

  3. A firmware (FW) bundle (only for bram_gpio ) which is needed to dynamically load the PL/AIE designs from Linux

While the Makefile is convenient, we will also provide step-by-step instructions for running the respective commands by hand.

The following design examples are compatible with the AMD Vivado™ Design Suite 2025.1 EA tools version.

Vivado base design and base platform

The following tutorial shows how to generate the Vivado™ Design Suite base design XSA from a Tcl based project and how to generate the system device tree handoff artifacts that are needed to set up the Yocto build.

Refer to https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258188188/Custom+Hardware+Development+AMD+Versal+device+portfolio#EDF-Hardware-Design-Repository-Overview for details on setting up the hardware design repo and setting up the tools.

From the top-level directory, we use make to build the base design project from Tcl. This step will take some time as we are running implementation to generate the routed dcp which is used later by pr_verify for checking design compatibility for segmented config when creating alternative compatible PL payloads.

Additionally the build reads a noc solution file from the Vivado install area for the CED to re-seed the NOC solution, and checks the unique ID of boot.pdi for the pre-built Vivado CED against the newly generated boot.pdi to confirm if it has same unique ID or not. This will ensure compatibility between the pre-built boot firmware and users who created their custom design from the Vivado CED (and can then deploy the PL image directly to a system running the re-built boot firmware and boot image).

 

Note: See the output directory for the .dcp file used to check for compatibility of designs in the Segmented Configuration flow (pr_verify)

The command below uses JOBS=8 to run 8 parallel compiles, with each compile spawning multiple threads, where the maximum number of threads is by default limited to the number of CPU cores detected. This will requires significant RAM and Processor resources.

For example: JOBS=8 - The number of processes = 8 x <number of cores>, with matching RAM requirements.

  • If you are running on a system with limited resources, it is recommend to set JOBS=1

$ cd eval_board_base/vek385_base $ make all JOBS=8

The make command generates the following artifacts inside the base/ folder:

  1. Project directory hw_project - The folder contains the Vivado .xpr project file which can be used to open and edit the project in the Vivado Design Suite

  2. SDT artifacts directory hw_project_sdt - The SDT directory is used as handoff artifact to set up the Yocto Project™ disk image build

You can now open the generated Vivado Design Suite project to view the generated design:

  1. Open the generated xpr project file from the command line (See the Vivado Design Suite documentation for other ways to open the project)

$ cd hw_project/vek385_base $ vivado vek385_base.xpr &

Here is a screenshot of the block design:

vek385_base_ced.png

The output of the generated sdt artifacts directory looks as follows. You can see that two different PDIs were generated for the segmented configuration flow: 

  1. boot PDI <board name>_base_boot.pdi - this PDI is used in the boot image (boot.bin) and is stored in the OSPI as a boot image to be loaded by the EDF Boot Firmware.

  2. pld PDI <board_name>_base_pld.pdi - This is the PL PDI used to load the PL. This file is one of the input files to create the firmware bundle to load the PL from Linux userspace or U-Boot, and can be added to the rootfs build or copied directly to the running system. See Firmware Bundle and Deploying the PL firmware application onto target for step to create the firmware bundle.

Note

Getting started - Walk through examples - Custom Hardware Development expects the following:

  • SDTGen to have been run to generate a System Device Tree directory (containing the PL.PDI and hardware project derived Device Trees)

  • <system Device Tree Directory>/pl.dtsi (PL Device Tree) to have been manually updated to reflect PL content if needed

  • gen-machine-conf to have been run to populate the Yocto Project build directory

See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586337

The Yocto Project build recipes (created by recipetool-create) then handles the file conversion, Device Tree Overlay and integration into the root fs as part of the Image build process

The firmware package could also be created manually, and/or copied directly to the running image for testing using SCP, tftp, or via SD Card.

 

SDTGen is run as part of the build process in the Makefile, the contents of the System Device Tree Handoff Directory are shown below.

It contains a series of device tree files with system-top.dts being the top-level device tree.

$ tree -L 1 hw_project_sdt/ hw_project_sdt/ ├── aie_primitive.json ├── extracted ├── HashBlock0.bin ├── include ├── pcw.dtsi ├── pl.dtsi ├── system-top.dts ├── vek385_base_boot.pdi ├── vek385_base.isd ├── vek385_base.mmi ├── vek385_base_pld.pdi ├── versal2-clk-ccf.dtsi ├── versal2.dtsi └── versal2-vek385-revA.dtsi

The following tutorial shows the steps for generating the sdt handoff directory by hand using the SDTGen tool

bash-4.4$ sdtgen sdtgen% set_dt_param -debug enable sdtgen% set_dt_param -zocl enable sdtgen% set_dt_param -dir ./hw_project_sdt sdtgen% set_dt_param -xsa ./hw_project/vek385_base/outputs/vek385_base.xsa sdtgen% set_dt_param -board_dts versal2-vek385-reva sdtgen% generate_sdt INFO: [Hsi 55-2053] elapsed time for repository (/opt/Vivado/data/embeddedsw) loading 1 seconds hsi::open_hw_design: Time (s): cpu = 00:00:13 ; elapsed = 00:00:15 . Memory (MB): peak = 671.430 ; gain = 94.055 ; free physical = 70545 ; free virtual = 350031 WARNING: no s_axi_aclk for clockwizard IP block: " clkx5_wiz_0"   WARNING: no s_axi_aclk for clockwizard IP block: " clkx5_wiz_0"   WARNING: no s_axi_aclk for clockwizard IP block: " clkx5_wiz_0"   WARNING: no s_axi_aclk for clockwizard IP block: " clkx5_wiz_0"   INFO: Reading AIE hardware properties from XSA. WARNING: ps_wizard_0_mmi_0_mmi_10gbe: No reset found WARNING: ps_wizard_0_ps11_0_ethernet_0: No reset found WARNING: ps_wizard_0_ps11_0_i2c_0: No reset found WARNING: ps_wizard_0_ps11_0_i2c_1: No reset found sdtgen% exit exit

You can inspect the generated output in the hw_project_sdt2 directory which should match the output of the hw_project_sdt directory generated as part of the make command.

Generating a new Yocto Project Machine Configuration

Alternatively to using the prebuilt Yocto machine configuration based on cached SDT artifacts as described in the previous tutorial, you can generate your own Yocto machine configuration. This section describes how to generate a Yocto machine configuration using the gen-machine-conf tool from an SDT handoff directory.

Note

The previous tutorial (Getting started - Walk through examples - OS Integration and Development ) generated a disk image using a prebuilt Yocto Project™ machine configuration based on cached SDT artifacts.

When importing the sdtgen output or System-Device-Tree into gen-machine-conf, make sure to start a new shell and set up the Yocto/gen-machine-conf environment separately.
Never mix environments between Vivado, Yocto, and PetaLinux, doing so can lead to unpredictable behavior.

For custom machines, the BOOT.BIN generated using the xilinx-bootbin recipe is sufficient. It provides the same core functionality as edf-ospi, except for the image selector and image recovery applications. The same BOOT.BIN can be used for both SD boot and OSPI boot, For OSPI boot, flash the BOOT.BIN file into the OSPI partition.

 

Related Links

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.

© 2025 Advanced Micro Devices, Inc. Privacy Policy