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.

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 https://source.android.com/setup/develop/repo

      $ repo init -u https://github.com/Xilinx/yocto-manifests.git -b refs/tags/amd-edf-rel-v25.05 -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. Download the meta-xilinx-restricted-vek385 [meta-xilinx-restricted-vek385.tar.gz] tarball files from the VEK385 EA lounge.

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

4. Extract the meta-xilinx-restricted-vek385 layer to the <path-to>/yocto/edf/sources directory.

   $ tar -xf meta-xilinx-restricted-vek385.tar.gz -C <path-to>/yocto/edf/sources

5. Add the meta-xilinx-restricted-vek385 layer to build using the bitbake-layers command. Change <version> to the applicable version for the release of EDF.

   $ cd <path-to>/yocto/edf/build $ bitbake-layers add-layer <path-to>/yocto/edf/sources/meta-xilinx-restricted-vek385-<version>/meta-xilinx-restricted-ea/meta-xilinx-restricted-vek385/

6. Build the EDF boot firmware (OSPI image)

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

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

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

8. 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/ # On NFS storage image directory path, See Yocto AMD EDF build instructions step 6 $ ls -la ${TMPDIR}/deploy/images/versal-2ve-2vm-vek385-sdt-seg/ $ ls -la ${TMPDIR}/deploy/images/amd-cortexa78-mali-common/

9. 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 https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586081/Development+Flows+-+How+it+all+works#Creating-a-image-for-multi-stage-boot-(Primary-Boot-Device-%E2%86%92-Secondary-Boot-device)

10. 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 https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586081/Development+Flows+-+How+it+all+works#Creating-a-bootable-SD-CARD-image-(Single-stage-boot-%3A-SD-%2F-eMMC-%2F-USB-%2F-UFS)----Combining-boot.bin-and-EDF-Linux%C2%AE-common-disk-image

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

12. 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 https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258089693/Operating+System+Integration+and+Development+AMD+Versal+device+portfolio#Yocto-Project-build-setup-instructions-for-EDF

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 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-cortexa72-common (Versal family)

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

      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: Discovery and Evaluation AMD Versal Device Portfolio | Writing the EDF Linux® disk image (wic) to the secondary 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 Versal 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 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 images to this new directory.

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

6. Merge the versal-2ve-2vm-vek385-sdt-seg board and amd-cortexa78-mali-common qemuboot files and generate a new 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-common-qemu-images/BOOT-versal-2ve-2vm-vek385-sdt-seg.qemuboot.conf remove image_link_name remove image_name merge tmp/deploy/images/vek385-common-qemu-images/edf-linux-disk-image-amd-cortexa78-mali-common.rootfs.qemuboot.conf > tmp/deploy/images/vek385-common-qemu-images/vek385-common-combined.qemuboot.conf

7. On successfully creating the combined qemuboot.conf file, the content of the tmp/deploy/images/vek385-common-qemu-images/vek385-common.qemuboot.conf file should look similar to the following 

   vek385-common.qemuboot.conf:

   $ cat tmp/deploy/images/vek385-common-qemu-images/vek385-common-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-20250505194101 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.
   
   

7. 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 Software Application Development | 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 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/sdk/*.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 Software Application Development | SDK installationPreview for installing the generated SDK and for cross-building an example hello world application.

Related Links

• http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN80

• http://xahlee.info/UnixResource_dir/_/ldpath.html

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

• Segmented Configuration or Dynamic Function eXchangePreview

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