This page is part of a getting started guide providing walk through style examples using the AMD Embedded Development Framework (EDF). This section covers Operating System Integration and Development - The full software build flow. For other persona and tasks, see the parent pages.

Some of the prompts on this page use exact steps for specific boards. If your specific board is not mentioned you can look at the following information in order to verify your board is supported for the flow described here, and how to modify the examples for your specific board: Common Specifications | EDF prebuilt Yocto machine definitionsPreview

Table of Contents

Operating System Integration and Development

The operating system (OS) developer creates custom OS images based on application or system requirements. In the simplest case, it is a plain Linux^® OS image, in more complex scenarios this can involve hypervisors, containers, multiple OSes based on processing domains (for example, RTOSes and bare-metal components) etc.

It also entails more low-level boot components such as PMU, PLM and PSM firmware (AMD-specific), U-Boot, ARM TF-A, OPTEE etc. The Yocto Project™ provides a build environment that allows users to create custom, complex, heterogenous boot and OS images.

Note: at this stage, basic to advanced Yocto knowledge is required depending on the task you want to perform.

Open

Yocto Project build setup instructions for EDF

This section describes how to get your build host ready to work with EDF meta layers and the required upstream layers.

1. Download and install the Repo tool (if it was not installed in a previous step) Note: If you have repo installed through a package manager, that should be removed first as it is likely out of date and will cause issues. Note: Curl is used to install repo, this may need to be installed your system via the package feed for your Operating System (apt-get, yum, dnf, etc).

   $ curl https://storage.googleapis.com/git-repo-downloads/repo > repo $ chmod a+x repo $ echo "Create a user specific ~/bin directory if one does not exist" $ mkdir ~/bin $ mv repo ~/bin/ $ PATH=~/bin:$PATH $ repo --help

2. Initialize a Repo client.

   1. Create the edf project directory.

      $ mkdir -p yocto/edf $ cd yocto/edf

   2. Clone the Yocto meta layer source using the yocto manifest as show below.  A successful initialization will end with a message stating that Repo is initialized in your working directory. Your directory should now contain a .repo directory where repo control files such as the manifest are stored. However you should not need to touch this directory. To learn more about Repo, see Repo command reference  |  Android Open Source Project

      $ repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2025.2 -m default-edf.xml

3. Fetch all of the repositories.

   $ repo sync

4. Start a branch for development starting from the revision specified in the manifest. This is an optional step.

   $ repo start <branch_name> --all

5. Initialize a build environment using the edf-init-build-env script.  Once the environment is initialized, bblayers.conf and local.conf are set from the meta-amd-edf layer default templates.

   $ source edf-init-build-env

6. If you are building without network access, follow the below steps (otherwise skip this step):

   1. Extract the downloads and sstate tarball files to the ${TOPDIR}/build directory:

      $ tar -xf downloads.tar.gz -C <path-to>/yocto/edf/build $ tar -xf sstate-cache.tar.gz -C <path-to>/yocto/edf/build

   2. Adjust the download (SOURCE_MIRROR_URL) and sstate (SSTATE_MIRRORS) mirrors variables by editing build/conf/local.conf to point to local paths as shown below.
      Note: INHERIT += "own-mirrors" is already included in the local.conf file.

      SOURCE_MIRROR_URL = "file:///<path-to>/yocto/edf/build/downloads" SSTATE_MIRRORS = "\ file://.* file:///<path-to>/yocto/edf/build/sstate-cache/PATH \n \ "

   3. Set the BB_NO_NETWORK variable in build/conf/local.conf 

      BB_NO_NETWORK = "1" PREMIRRORS:append = ""

7. For the NFS build host system, modify the build/conf/local.conf and add the TMPDIR path as shown below. On local storage, $TMPDIR will be set to build/tmp.

   TMPDIR = "/tmp/<user-name>/yocto/release_version/build":wq!

8. Depending on the build configuration, several 10s of GB of storage space might be required in the TMPDIR. Make sure you have plenty of storage space available. Alternatively, to save disk space, you can add the below to your build/conf/local.conf. This option removes the work dir after build and only keeps the logs.

   INHERIT += "rm_work"

9. In the following sections we will use the build environment set up in this section.

TMPDIR = "/tmp/<user-name>/yocto/release_version/build":wq!

EDF Linux® disk image build using a prebuilt Yocto Project machine and pre-built Vivado artifacts (PDI) - Multi-stage boot (QSPI / OSPI → SD / UFS)

1. Build Yocto Project pre-requisites by following Yocto Project build setup instructions for EDF

2. Build the EDF boot firmware (OSPI image)

   $ MACHINE=versal-2ve-2vm-vek385-sdt-seg bitbake edf-ospi

3. Build the EDF Linux disk image (wic) containing general purpose (GP) Linux

   $ MACHINE=amd-cortexa78-mali-common bitbake edf-linux-disk-image

4. On successful build, the images for the target machine will be available in the relevant output directory ${TMPDIR}/deploy/images/${MACHINE}/ 

   $ ls -la tmp/deploy/images/versal-2ve-2vm-vek385-sdt-seg/ $ ls -la tmp/deploy/images/amd-cortexa78-mali-common/

5. Flash the OSPI ${TMPDIR}/deploy/images/versal-2ve-2vm-vek385-sdt-seg/edf-ospi-versal-2ve-2vm-vek385-sdt-seg-<timestamp>.bin image file by following Development Flows - How it all works | Creating a image for multi stage boot (Primary Boot Device → Secondary Boot dev...Preview

6. Flash the ${TMPDIR}/deploy/images/amd-cortexa78-mali-common/edf-linux-disk-image-amd-cortexa78-mali-common.rootfs-<timestamp>.wic.xz  to SD card by following Development Flows - How it all works | Creating a bootable SD CARD image (Single stage boot : SD / eMMC / USB / UFS) ...Preview

7. Boot the VEK385 board from OSPI boot mode to boot GP Linux

8. Upon first boot, Linux requires a password to be set for the default user account.

EDF Linux® disk image build using a prebuilt Yocto Project machine and pre-built Vivado artifacts (PDI) - SDCARD boot

1. Build Yocto pre-requisites by following Operating System Integration and Development AMD Versal™ device portfolio | Yocto Project build setup instructions for EDFPreview

2. Build the Boot.bin image for the board.

   1. See Common Specifications | EDF prebuilt Yocto machine definitionsPreview for the list of pre-built machines that support generating a boot.bin file.

      xilinx-bootbin-recipe

      # Syntax: $ MACHINE=<machine-name> bitbake xilinx-bootbin   # Example Usage for VEK280: $ MACHINE=versal-vek280-sdt-seg bitbake xilinx-bootbin # Example Usage for VCK190: $ MACHINE=versal-vck190-sdt-seg bitbake xilinx-bootbin

3. Build EDF Common disk images containing EDF Linux® OS (wic).

   1. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586143/Common+Specifications#EDF-Common-disk-images-containing-EDF-Linux%C2%AE-OS----Yocto-machine-definitions-and-supported-recipes for Yocto machine definitions and supported recipes

   2. An example is shown below for amd-cortexa72-common (Versal family)

      Note: Versal-Net family is not supported in 2025.2.

      linux-image-recipe

      # Syntax: $ MACHINE=<machine-name> bitbake edf-linux-disk-image #Example Usage for versal-gp $ MACHINE=amd-cortexa72-common bitbake edf-linux-disk-image

4. Combine the xilinx-bootbin and EDF Common disk images to make single SD card image (boot.bin, kernel, rootfs, boot script), by adding the boot.bin to the EFI partition in the WIC Image (Partition 0 = index 1 in the WIC)

4. Flashing the SD card

The generated image now needs to be flashed to the SD card.

Follow the instructions from here: https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258155011/Discovery+and+Evaluation+AMD+Versal+Device+Portfolio#Writing-the-EDF-Linux%C2%AE-disk-image-(wic)-to-the-secondary-boot-media-%3A-SD-card

Once the flashing completes, safely remove the SD card and insert it into the SD card slot of the board.

5. Boot the board as described in https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258155011/Discovery+and+Evaluation+AMD+Versal+Device+Portfolio#How-to-boot-a-board-using-the-pre-built-Images-%3A-Single-stage-boot-SD-mode---Setup

Building Images for QEMU

1. Set up the build environment and Yocto Project™ pre-requisites by following Yocto Project build setup instructions for EDF

2. Build the Boot.bin image.

   1. See Common Specifications | EDF prebuilt Yocto machine definitionsPreview for the list of pre-built machines that support generating a boot.bin file.

      xilinx-bootbin-recipe

      # Syntax: $ MACHINE=<machine-name> bitbake edf-ospi # Example Usage for VEK385: $ MACHINE=versal-2ve-2vm-vek385-sdt-seg edf-ospi

3. Build the qemu-helper-native package to set up QEMU network tap devices
   qemu-helper-native (for VEK385):

3. Manually configure a tap interface for your build system. As root run <path-to>/sources/poky/scripts/runqemu-gen-tapdevs, which should generate a list of tap devices. Once the tap interfaces are successfully created, you should be able to see all of the interfaces by running the ifconfig or ip a command.

   $ sudo ./<path-to-layer>/poky/scripts/runqemu-gen-tapdevs $(id -u $USER) $(id -g $USER) 4

4. Combine the xilinx-bootbin and qemu helper native images to make single wic.qemu-sd (boot.bin, kernel, rootfs, boot script), by adding the boot.bin to the EFI partition in the WIC Image (Partition 0 = index 1 in the WIC)

4. Now you can simulate the image using QEMU emulator. 

5. Create a directory under ${DEPLOY_DIR}/images (tmp/deploy/images) and copy the versal-2ve-2vm-vek385-sdt-seg board and amd-cortexa78-mali-common artifacts to this new directory.

   $ mkdir -p tmp/deploy/images/vek385-qemu $ cp -r tmp/deploy/images/versal-2ve-2vm-vek385-sdt-seg/* tmp/deploy/images/vek385-qemu $ cp -r tmp/deploy/images/amd-cortexa78-mali-common/* tmp/deploy/images/vek385-qemu

6. Merge the versal-2ve-2vm-vek385-sdt-seg and amd-cortexa78-mali-common qemuboot files and generate a new combined vek385-combined.qemuboot.conf file using qemuboot-tool.

   $ ./<path-to>/yocto/edf/sources/meta-xilinx/meta-xilinx-core/scripts/qemuboot-tool \ load tmp/deploy/images/vek385-qemu/BOOT-versal-2ve-2vm-vek385-sdt-seg.qemuboot.conf \ remove image_link_name \ remove image_name \ merge tmp/deploy/images/vek385-qemu/edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.qemuboot.conf \ > tmp/deploy/images/vek385-qemu/vek385-combined.qemuboot.conf

7. On successfully creating the combined vek385-combined.qemuboot.conf file, the contents should look similar to the following:

   vek385-combined.qemuboot.conf:

   $ cat tmp/deploy/images/vek385-qemu/vek385-combined.qemuboot.conf [config_bsp] deploy_dir_image = . image_link_name = edf-linux-disk-image-amd-cortexa78-mali-common.rootfs image_name = edf-linux-disk-image-amd-cortexa78-mali-common.rootfs-20251120145551 kernel_imagetype = Image machine = versal-2ve-2vm-vek385-sdt-seg qb_cmdline_ip_slirp = ip=dhcp qb_cmdline_ip_tap = ip=192.168.7.@CLIENT@::192.168.7.@GATEWAY@:255.255.255.0::eth0:off:8.8.8.8 net.ifnames=0 qb_default_fstype = wic.ufs qb_default_kernel = BOOT-versal-2ve-2vm-vek385-sdt-seg.bin qb_drive_type = /dev/sd qb_dtb = qemu-hw-devicetrees/multiarch/board-versal2-psxc-vek385.dtb qb_graphics = qb_kernel_cmdline = none qb_kernel_cmdline_append = swiotlb=0 qb_machine = -machine arm-generic-fdt qb_mem = -m 8G qb_network_device = -net nic,netdev=net0,macaddr=@MAC@ -net nic qb_nfsrootfs_extra_opt = qb_no_pni = net.ifnames=0 qb_opt_append = -serial null -serial null -serial null -serial mon:stdio -nodefaults -boot mode=8 -bootbin versal_2ve_2vm:@DEPLOY_DIR_IMAGE@/qemu-ospi-versal-2ve-2vm-vek385-sdt-seg.bin -plm-args ' -M microblaze-fdt -device loader,addr=0xf0000000,data=0xba020004,data-len=4 -device loader,addr=0xf0000004,data=0xb800fffc,data-len=4 -device loader,addr=0xF1110624,data=0x0,data-len=4 -device loader,addr=0xF1110620,data=0x1,data-len=4 -hw-dtb @DEPLOY_DIR_IMAGE@/qemu-hw-devicetrees/multiarch/board-versal2-pmxc-virt.dtb -display none ' -asu-args ' -M riscv-fdt -hw-dtb @DEPLOY_DIR_IMAGE@/qemu-hw-devicetrees/multiarch/board-versal2-asu-virt.dtb -display none ' -drive file=@DEPLOY_DIR_IMAGE@/qemu-ospi-versal-2ve-2vm-vek385-sdt-seg.bin,if=mtd,format=raw,index=0 qb_rng = qb_rootfs = qb_rootfs_extra_opt = qb_rootfs_opt = -device scsi-hd,drive=d1,bus=scsi.0,channel=0,scsi-id=0,lun=0,logical_block_size=4096,physical_block_size=4096 -drive file=@ROOTFS@,if=none,id=d1,format=raw qb_serial_opt = qb_smp = qb_system_name = qemu-system-aarch64-multiarch serial_consoles = 115200;ttyAMA0 staging_bindir_native = ../../../work/x86_64-linux/qemu-helper-native/1.0/recipe-sysroot-native/usr/bin staging_dir_host = ../../../work/versal_2ve_2vm_vek385_sdt_seg-amd-linux/xilinx-bootbin/1.0/recipe-sysroot staging_dir_native = ../../../work/versal_2ve_2vm_vek385_sdt_seg-amd-linux/xilinx-bootbin/1.0/recipe-sysroot-native tune_arch = aarch64 uninative_loader = ../../../sysroots-uninative/x86_64-linux/lib/ld-linux-x86-64.so.2

8. Launch the QEMU boot instance by executing the runqemu script.

Qemu Boot Log:

9. Upon first boot, Linux requires a password to be set for the default user account.

Build and Deploy Zephyr RTOS DomU Guest OS Image

A pre-built Zephyr RTOS Xen DomU Guest OS Image is provided. This Guest OS uses zephyr-synchronization kernel image. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3258155011#Versal%E2%84%A2--Xen-UEFI-Zephyr-RTOS-DomU-Guest-OS. The following tutorial show how to build and deploy Zephyr RTOS Guest OS Image.

1. Set up the build environment and Yocto Project pre-requisites by following Yocto Project build setup instructions for EDF

2. Use xenvmgicv3 machine to build zephyr-synchronization or other zephyr kernel available in meta-zephyr/meta-zephyr-core/recipes-kernel/zephyr-kernel at rel-v2025.2 · Xilinx/meta-zephyr . See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/edit-v2/3450568721#XENVMGICV3%3A

3. Create a recipe xen-custom-domu-image

   $ mkdir -p <meta-custom-layer>/recipes-extended/xen-custom-domu-image $ mkdir -p <meta-custom-layer>/recipes-extended/xen-custom-domu-image/xen-custom-domu-image $ touch <meta-custom-layer>/recipes-extended/xen-custom-domu-image/xen-custom-domu-image.bb

4. To run Zephyr RTOS DomU Guest OS first we need to create Xen DomU configuration file.

   $ touch <meta-custom-layer>/recipes-extended/xen-custom-domu-image/xen-custom-domu-image/zephyr-helloworld-xenvmgicv3.cfg

5. Content of <meta-custom-layer>/recipes-extended/xen-custom-domu-image/xen-custom-domu-image/zephyr-helloworld-xenvmgicv3.cfg should look like below.

   # Guest name name = "zephyr-helloworld-xenvmgicv3" # Kernel image to boot kernel = "/boot/zephyr-helloworld-xenvmgicv3.bin" # Kernel command line options - Allocate 32MB memory = 32 # Number of VCPUS vcpus = 1

6. Copy the zephyr-helloworld-xenvmgicv3.bin file from ${TMPDIR}/deploy/images/xenvmgicv3 directory to <meta-custom-layer>/recipes-extended/xen-custom-domu-image/xen-custom-domu-image/ or you can host this binary is web similar to Index of /sswreleases/rel-v2025.2/edf_files/2025.2/11100846/external/zephyr-synchronization

   $ cp -r ${TMPDIR}/deploy/images/xenvmgicv3/zephyr-helloworld-xenvmgicv3-{TIMESTAMP}.bin <meta-custom-layer>/recipes-extended/xen-custom-domu-image/xen-custom-domu-image/zephyr-helloworld-xenvmgicv3.bin

7. Now add these files to recipe and deploy to rootfs as shown.

   SUMMARY = "Xen Zephyr Hello World DomU Guest OS image recipe" LICENSE = "MIT" LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" SRC_URI = "\ file://zephyr-helloworld-xenvmgicv3.bin \ file://zephyr-helloworld-xenvmgicv3.cfg \ " COMPATIBLE_MACHINE = "^$" COMPATIBLE_MACHINE:versal = "${MACHINE}" COMPATIBLE_MACHINE:versal-2ve-2vm = "${MACHINE}" do_configure() { : } do_compile() { : } do_install () { install -d ${D}/boot install -m 0644 ${WORKDIR}/zephyr-helloworld-xenvmgicv3.bin ${D}/boot install -d -m 0755 ${D}${sysconfdir}/xen install -m 0644 ${WORKDIR}/zephyr-helloworld-xenvmgicv3.cfg ${D}${sysconfdir}/xen/zephyr-helloworld-xenvmgicv3.cfg } FILES:${PN} += " \ /boot/* \ ${sysconfdir}/xen/zephyr-helloworld-xenvmgicv3.cfg \ "

8. Add xen-custom-domu-image recipe to IMAGE_INSTALL variable in build/conf/local.conf file.

   IMAGE_INSTALL:append = "xen-custom-domu-image"

9. Build the edf-linux-disk-image.

   1. Versal Gen 1

      $ MACHINE=amd-cortexa72-common bitbake edf-linux-disk-image

   2. Versal Gen 2

      $ MACHINE=amd-cortexa78-mali-common bitbake edf-linux-disk-image

10. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258155011/Discovery+and+Evaluation+AMD+Versal+Device+Portfolio#Versal%E2%84%A2--Xen-UEFI-Zephyr-RTOS-DomU-Guest-OS on how to run xen domu image.

Building an SDK for application cross-development

A pre-built SDK for Linux application cross-development is provided. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258089893/Software+Application+Development#Software-Application-Development-using-SDK for instructions on how to use it. An SDK is not extensible; if a user wants to enable additional dev tools or dev packages in the SDK, a new SDK has to be built and installed. The following tutorial shows how to modify and build a new EDF Linux SDK.

1. Set up the build environment and Yocto Project pre-requisites by following Yocto Project build setup instructions for EDF

2. The SDK recipe can be found in sources/meta-amd-edf/recipes-core/meta/meta-edf-app-sdk.bb

3. This recipe can be modified to contain additional recipes as required - append the recipes to the TOOLCHAIN_TARGET_TASK list 

4. Build the SDK for application development.

   sdk-build:

   $ MACHINE=amd-cortexa78-mali-common bitbake meta-edf-app-sdk $ ls tmp/deploy/amd-cortexa78-mali-common/installer/*.sh tmp/deploy/sdk/amd-edf-glibc-x86_64-meta-edf-app-sdk-cortexa72-cortex-amd-cortexa78-mali-common-toolchain-25.05+release-e984eec4e65cbc06d089cfe812760f5307a95f7e.sh

5. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258089893/Software+Application+Development#SDK-installation for installing the generated SDK and for cross-building an example hello world application.

Related Links

• Shared Libraries

• Why LD_LIBRARY_PATH is bad

• https://web.git.yoctoproject.org/poky/plain/meta-skeleton/recipes-skeleton/hello-autotools/hello_2.10.bb

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

• Software Hardware Exchange Loop (SHEL) FlowPreview

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.