This is a getting started guide providing walk through style examples using the AMD Embedded Development Framework (EDF). This sections covers Operating System Integration and Development - The full software build flow. For other personas 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 image, in more complex scenarios this can involve hypervisors, containers, multiple OSes based on processing domains (For example, RTOS's and bare-metal components etc.) It also entails more low-level boot component like 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 that 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.

   $ curl https://storage.googleapis.com/git-repo-downloads/repo > repo $ chmod a+x repo $ 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 but you should not need to touch this directory. To learn more about repo, look at 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 the repositories.

   $ repo sync

4. Start a branch with 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 ${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 an 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"

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.

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

1. Build Yocto pre-requisites by following Operating System Integration and Development AMD ZynqMP™ 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 ZCU104: $ MACHINE=zynqmp-zcu104-sdt-full bitbake xilinx-bootbin

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

   1. See Common Specifications | EDF Common disk images containing EDF Linux® OS Yocto machine definitions an...Preview for Yocto machine definitions and supported recipes

   2. An example is shown below for amd-cortexa53-mali-common (ZynqMP family)

      linux-image-recipe

      # Syntax: $ MACHINE=<machine-name> bitbake edf-linux-disk-image #Example Usage for ZynqMP $ MACHINE=amd-cortexa53-mali-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: Discovery and Evaluation AMD ZynqMP™ device portfolio | Writing the EDF Linux® disk image (wic) to the boot media : SD cardPreview

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 Discovery and Evaluation AMD ZynqMP™ device portfolio | How to boot a board using the pre built Images : Single stage boot SD mode Se...Preview

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 xilinx-bootbin   # Example Usage for ZCU104: $ MACHINE=zynqmp-zcu104-sdt-full bitbake xilinx-bootbin

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

   # Syntax: $ MACHINE=<machine-name> bitbake qemu-helper-native   # Example Usage for ZCU104: $ MACHINE=amd-cortexa53-mali-common bitbake qemu-helper-native

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 board and common images to this new directory.

   $ mkdir -p tmp/deploy/images/zcu104-common-qemu-images $ cp -r ./tmp/deploy/images/amd-cortexa53-mali-common/* tmp/deploy/images/zcu104-common-qemu-images/ $ cp -r ./tmp/deploy/images/zynqmp-zcu104-sdt-full/* tmp/deploy/images/zcu104-common-qemu-images/

6. Merge the BOOT-zynqmp-zcu104-sdt-full board and edf-linux-disk-image-zynqmp-zcu104-sdt-full qemuboot files and generate a new combined qemuboot.conf file using qemuboot-tool.

   $ ../sources/meta-xilinx/meta-xilinx-core/scripts/qemuboot-tool \ load tmp/deploy/images/zcu104-common-qemu-images/BOOT-zynqmp-zcu104-sdt-full.qemuboot.conf \ remove image_link_name \ remove image_name \ merge tmp/deploy/images/zcu104-common-qemu-images/edf-linux-disk-image-zynqmp-zcu104-sdt-full.rootfs.qemuboot.conf \ > tmp/deploy/images/zcu104-common-qemu-images/zcu104-common-combined.qemuboot.conf

7. After successfully creation of the combined qemuboot.conf file, the content of the tmp/deploy/images/zcu104-common-qemu-images/zcu104-common-combined.qemuboot.conf should look like the following. 

   zcu104-common-combined.qemuboot.conf:

   $ cat tmp/deploy/images/zcu104-common-qemu-images/zcu104-common-combined.qemuboot.conf [config_bsp] deploy_dir_image = . image_link_name = edf-linux-disk-image-amd-cortexa53-mali-common.rootfs image_name = edf-linux-disk-image-amd-cortexa53-mali-common.rootfs-20251121234700 kernel_imagetype = Image machine = zynqmp-zcu104-sdt-full 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.qemu-sd qb_default_kernel = BOOT-zynqmp-zcu104-sdt-full.bin qb_drive_type = /dev/sd qb_dtb = qemu-hw-devicetrees/multiarch/board-zynqmp-zcu104.dtb qb_graphics = qb_kernel_cmdline = none qb_kernel_cmdline_append = swiotlb=0 qb_machine = -machine arm-generic-fdt qb_mem = -m 4G qb_network_device = -net nic -net nic -net nic -net nic,netdev=net0,macaddr=@MAC@ qb_nfsrootfs_extra_opt = qb_no_pni = net.ifnames=0 qb_opt_append = -nodefaults -global xlnx,zynqmp-boot.cpu-num=0 -global xlnx,zynqmp-boot.use-pmufw=true -device loader,addr=0xfffc0000,data=0x584c4e5801000000,data-be=true,data-len=8 -device loader,addr=0xfffc0008,data=0x0000000800000000,data-be=true,data-len=8 -device loader,addr=0xfffc0010,data=0x1000000000000000,data-be=true,data-len=8 -device loader,addr=0xffd80048,data=0xfffc0000,data-len=4,attrs-secure=on -device loader,file=@DEPLOY_DIR_IMAGE@/arm-trusted-firmware.elf,cpu-num=0 -device loader,file=@DEPLOY_DIR_IMAGE@/u-boot.elf -device loader,file=@DEPLOY_DIR_IMAGE@/system.dtb,addr=0x100000,force-raw=on -boot mode=5 -pmu-args ' -M microblaze-fdt -display none -hw-dtb @DEPLOY_DIR_IMAGE@/qemu-hw-devicetrees/multiarch/zynqmp-pmu.dtb -kernel @DEPLOY_DIR_IMAGE@/pmu-rom.elf -device loader,file=@DEPLOY_DIR_IMAGE@/pmu-firmware-zynqmp-zcu104-sdt-full.elf -device loader,addr=0xfd1a0074,data=0x1011003,data-len=4 -device loader,addr=0xfd1a007C,data=0x1010f03,data-len=4 ' qb_rng = qb_rootfs = qb_rootfs_extra_opt = qb_rootfs_opt = -drive if=sd,index=1,file=@ROOTFS@,format=raw qb_serial_opt = qb_smp = qb_system_name = qemu-system-aarch64-multiarch serial_consoles = 115200;ttyPS0 115200;ttyPS1 staging_bindir_native = ../../../work/x86_64-linux/qemu-helper-native/1.0/recipe-sysroot-native/usr/bin staging_dir_host = ../../../work/zynqmp_zcu104_sdt_full-amd-linux/xilinx-bootbin/1.0/recipe-sysroot staging_dir_native = ../../../work/zynqmp_zcu104_sdt_full-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.

   $ runqemu tmp/deploy/images/zcu104-common-qemu-images/zcu104-common-combined.qemuboot.conf nographic slirp

   Qemu Boot Log:

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

Building an SDK for application cross-development

A pre-built SDK for Linux application cross-development is provided. See Getting Started - Walkthrough Examples | Software Application Development using SDKPreview 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 https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3268149250/Operating+System+Integration+and+Development+AMD+ZynqMP+device+portfolio#EDF-Yocto-Project%E2%84%A2-build-setup-instructions

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 SDK for application development.

   sdk-build:

   $ MACHINE=amd-cortexa53-mali-common bitbake meta-edf-app-sdk $ ls tmp/deploy/amd-cortexa53-mali-common/installer/*.sh tmp/deploy/sdk/amd-edf-glibc-x86_64-meta-edf-app-sdk-cortexa72-cortexa53-amd-cortexa53-mali-common-toolchain-25.11+development-027ae3f30fdccfa8b8043955821a11c6286cd66e.sh

5. See https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258089893/Software+Application+Development#SDK-installation for information on 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/x/bQCRvw

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

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.