PetaLinux to EDF Migration Guide
For EDF flows please follow our page AMD Embedded Development Framework (EDF)
This page and the included tutorials are for reference purpose only. User's facing issues (bugs or errors) during the migration will need to fix them on their own. AMD are always here to support, but these issues should not be considered as part of the migration process.
Overview
- 1 Overview
- 2 BSP Directory Structure
- 2.1 PetaLinux BSP
- 2.2 EDF BSP
- 3 Migration Steps: PetaLinux to Yocto EDF
- 4 Design overview
- 5 Creating a Project
- 6 Configuring
- 7 Building
- 8 Packaging
- 9 Booting
- 10 Customizing the Root File System
- 11 Customizing Device Trees
- 11.1 PetaLinux Example
- 11.2 Yocto Example
- 12 Apply Patches
- 13 PetaLinux Yocto Tips
- 14 Technical_FAQ
PetaLinux
PetaLinux is an embedded Linux Software Development Kit (SDK) targeting FPGA-based system-on-chip (SoC) designs or FPGA designs.
EDF
The AMD Embedded Development Framework (EDF) is a common framework to support platform level development and embedded software solutions for AMD adaptive SoC and FPGA products, as well as their evaluation boards.
BSP Directory Structure
PetaLinux BSP
The .bsp file contains:
Prebuilt images
Design files
Configuration files
EDF BSP
The BSP is split across multiple locations and does not use a .bsp tar file. In PetaLinux, there are no Tcl sources for design file generation, but in EDF, the design Tcls are open-sourced.
Resources:
Prebuilt images: https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html
Design files:GitHub - Xilinx/amd-yocto-hw-platforms
Configurations files: GitHub - Xilinx/meta-amd-adaptive-socs at rel-v2025.2
Migration Steps: PetaLinux to Yocto EDF
Note: there is no direct conversion from a PetaLinux XSA-based project to EDF. First, migrate the PetaLinux XSCT project to a PetaLinux SDT project. Then, migrate the SDT project to EDF using the steps outlined in the following section.
Steps to Migrate a PetaLinux XSCT Project to a PetaLinux SDT Project
This section describes the process of migrating an existing PetaLinux project created using XSA into the Petalinux SDT.
Example user configuration in PetaLinux Project
a. kernel configuration
To configure the kernel, run the following:
petalinux-config -c kernelThis opens a kernel configuration menu. Note that it might take some time for the menu to load.
For example: Remove ZynqMP SHA3 support from kernel configuration.
Navigate to “Device Drivers → ZynqMP SHA3” in the kernel configuration and deselect the option to exclude SHA3 support.
b. Root File System configuration
To configure the Root File System, run:
petalinux-config -c rootfsFor example: Adding util-linux package to the root filesystem
c. U-boot configuration
To configure the U-boot, run:
petalinux-config -c u-bootFor example: update the autoboot delay to 5 seconds:
Navigate to [*] Autoboot → Boot options → (2) Delay before automatically booting and change the value from 2 to 5 seconds.
Steps to Migrate a PetaLinux SDT Project to Yocto EDF
This section describes the process of migrating an Existing PetaLinux project to the SDT Yocto EDF flow.
Verifying user added PetaLinux configuration in the EDF Project
Design overview
Design flow step | PetaLinux Tool/Work flow | Yocto EDF Tool/Work flow |
|---|---|---|
Hardware platform creation (for custom hardware only) | AMD Vivado™ design tools | AMD Vivado™ design tools |
Create a PetaLinux project | petalinux-create project | repo init + repo sync with Yocto manifest, source edf-init-build-env |
Initialize a PetaLinux project (for custom hardware only) | petalinux-config --get-hw-description | gen-machineconf --hw-description design.xsa |
Configure system-level options | petalinux-config | Edit conf/local.conf and bblayers.conf |
Create user components | petalinux-create apps/modules | Create custom layers and recipes |
Configure U-Boot | petalinux-config -c u-boot | MACHINE=<machine-name> bitbake -c menuconfig u-boot-xlnx |
Configure the Linux kernel | petalinux-config -c kernel | MACHINE=<machine-name> bitbake -c menuconfig linux-xlnx |
Configure the root filesystem | petalinux-config -c rootfs | Modify IMAGE_INSTALL in local.conf |
Build the system | petalinux-build | MACHINE=<machine-name> bitbake <image-name> |
Package for deploying the system | petalinux-package | Artifacts appear in tmp/deploy/images/<machine>/ |
Boot the system for testing | petalinux-boot | Boot via TFTP or Use SD card with generated boot files |
Creating a Project
Setting up the PetaLinux / Yocto environment
In PetaLinux, the tools need to be made available to the command line, however no project-specific initialization is required. With Yocto, the SDK needs to be set up for the local project prior to running bitbake commands.
For either tool, this setup only needs to be done once per command line session.
PetaLinux Example
source /opt/tools/PetaLinux/2025.2/tool/settings.sh
cd xilinx-zcu102-2025.2 #PetaLinux project directoryEDF Example
Source the Yocto build environment script for your workspace.
This must be done for every new shell session before running bitbake commands.
cd yocto/rel-v2025.2
source edf-init-build-env # Sets up Yocto build environmentCreate a new empty project from a template
A new “blank project”
PetaLinux Example
With PetaLinux, the architecture is specified as the template given at project creation time.
petalinux-create -t project -n <PROJECT NAME> --template [microblaze,zynq,zynqMP,versal,versal-net]EDF Project Example
For Yocto Project, the machine is not defined on project creation. It can be modified in build/conf/local.conf afterwards. By default, the machine is set to zynqmp-generic, however it can be changed in local.conf, or on invocation of the bitbake build command, using the MACHINE=[target template] command line override.
You can find the info about prebuilt machines in this link Common Specifications | EDF prebuilt Yocto machine definitions
# Download and install Repo tool:-
curl https://storage.googleapis.com/git-repo-downloads/repo > repo
chmod a+x repo
mv repo ~/bin/
PATH=~/bin:$PATH
repo --help
# Set up the EDF workspace:
mkdir -p yocto/rel-v2025.2
cd yocto/rel-v2025.2
# Initialize the repo for the desired release:
repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2025.2 -m default-edf.xml #EDF Distribution
repo sync
# Initialize the build environment:
source edf-init-build-env For more details, see the Operating System Integration and Development AMD Versal™ device portfolio | Yocto Project build setup instructions for EDF
Create a new project and target a specific pre-built BSP
A PetaLinux BSP is a configuration file containing all of the necessary settings and artifacts required to build a project with the PetaLinux tools for a given hardware project. The file has a .bsp extension, and can be downloaded from the AMD website for a given board.
PetaLinux Example
Download a BSP file from the website - for example, xilinx-zcu102-v2025.2-10171136.bsp
Create a new PetaLinux project using the BSP:
petalinux-create --type project -s xilinx-zcu102-v2025.2-10171136.bsp
cd xilinx-zcu102-2025.2/For more details, see the https://docs.amd.com/r/en-US/ug1144-petalinux-tools-reference-guide/Creating-a-Project-Using-PetaLinux-BSP
EDF Project Example
EDF does not use .bsp files. Instead, it uses machine configuration files (in the meta-amd-adaptive-socs/meta-amd-adaptive-socs-bsp layer or similar) to target specific boards. Pre-built machine definitions are available and can be selected during the Yocto project setup.
Use the steps outlined in this section to create an EDF Project: https://amd.atlassian.net/wiki/spaces/PSSANONECC/pages/1162851516/Petalinux+to+EDF+Migration+guide#Create-a-new-empty-project-from-a-template
Configuring
Importing a Hardware Configuration
PetaLinux Example
petalinux-config --get-hw-description <path to XSA file>EDF Example
Use the gen-machine-conf tool to generate a Yocto machine configuration from your XSA or SDT.
Reference: gen-machine-conf/README.md at xlnx_rel_v2025.2 · Xilinx/gen-machine-conf
U-Boot Configuration Updates
PetaLinux Example
Open U-Boot configuration menu. Custom settings are stored in: /project-spec/meta-user/recipes-bsp/u-boot/files/user.cfg
petalinux-config -c u-bootEDF Example
Launch U-Boot menuconfig In Yocto environment, To persist changes, copy the generated .config to your layer’s defconfig:
cp tmp/work/<machine>/u-boot-xlnx/<version>/build/.config <layer>/recipes-bsp/u-boot/u-boot-xlnx/defconfig
bitbake -c menuconfig u-boot-xlnxKernel Configuration Updates
PetaLinux Example
Opens kernel configuration menu to enable/disable drivers, options, or features. The changes are stored in: project-spec/meta-user/recipes-kernel/linux/linux-xlnx/user.cfg
petalinux-config -c kernelEDF Example
Launches kernel configuration menu within Yocto build system. To persist changes, copy the generated .config to your layer’s defconfig:cp tmp/work/<machine>/linux-xlnx/<version>/build/.config <layer>/recipes-kernel/linux/linux-xlnx/defconfig
bitbake -c menuconfig linux-xlnxBuilding
PetaLinux Example
petalinux-build # The default image built is petalinux-image-minimalEDF Example
We need a two-step build process to get the boot artifacts in EDF flow, unlike the PetaLinux flow
Boot firmware: Boot firmware is tightly coupled with the board.
boot.bin: pdi/bit, plm, fsbl, u-boot, dtb, tf-a, optee(versal2 only))
spi image: image sel , image recovery and dual boot.bin
# Build the Boot.bin image.
MACHINE=<machine-name> bitbake xilinx-bootbin
# Build the Boot.bin image.
MACHINE=<machine-name> bitbake edf-ospi
Platform specific boot artifacts: This boot images are specific to platforms such as MPSOC, Versal and Versal Gen 2 etc..
Kernel image, Rootfs
# Build SoC Common disk image (wic) containing general purpose (GP) Linux.
MACHINE=amd-cortexa53-common bitbake edf-linux-disk-image
# Build SoC Common ramdisk image
$ MACHINE=amd-cortexa53-common bitbake core-image-full-cmdlineMany other image targets exist in Yocto, and these can be further customized. For a list of some common image types, see https://docs.yoctoproject.org/dev/ref-manual/images.html
Packaging
Generate the boot Image
This step is used to generate a boot.bin file for booting the target. This would usually contain a PDI file, PLM, PSM firmware, TF-A, U-Boot boot loader and DTB.
PetaLinux Example
petalinux-package --boot --u-bootEDF Example
MACHINE=<machine-name> bitbake xilinx-bootbinGenerate MCS Image
PetaLinux Example
petalinux-package --boot --u-boot --format MCSEDF Example
There is no direct command to generate MCS image file but details to accomplish this can be found in the meta-xilinx documentation here : meta-xilinx/docs/README.booting.flash.md at master · Xilinx/meta-xilinx
WIC/SD card Image
PetaLinux Example
petalinux-package --boot --fsbl zynqmp_fsbl.elf --fpga system.bit --u-boot --force
petalinux-package --wicEDF Example
Below commands can help
MACHINE=zynqmp-zcu102-sdt-full bitbake xilinx-bootbin
MACHINE=amd-cortexa53-mali-common bitbake edf-linux-disk-image
Combine boot firmware with platform images
1.Install Yocto app sdk to get the wic utility
2.Source sdk env
Example:
source amd-cortexa72-common_meta-edf-app-sdk/sdk/environment-setup-cortexa72-cortexa53-amd-linux
2.wic cp boot.bin edf-linux-disk-image-amd-cortexa53-mali-common.rootfs.wic:1
Example:
wic cp boot.bin edf-linux-disk-image-amd-cortexa53-mali-common.rootfs.wic:1More detail on how to write an SD card image can be found in meta-xilinx/docs/README.booting.storage.md at master · Xilinx/meta-xilinx or Flashing and Booting the PetaLinux Image Using WIC Image
Booting
Boot Image on QEMU
PetaLinux Example
petalinux-boot --qemu --u-boot
petalinux-boot --qemu --kernelEDF Example
QEMU boot prebuilt images are not available by default in EDF for MPSOC, Versal Gen1 older families.
Follow the steps below to obtain the QEMU images:
Operating System Integration and Development AMD Versal™ device portfolio | Building Images for QEMU
Operating System Integration and Development AMD ZynqMP™ device portfolio | Building Images for QEMU
Boot Image on Hardware with JTAG
PetaLinux Example
petalinux-boot --jtagEDF Example
Customizing the Root File System
Although this guide is a intended to provide a cross reference, AMD is moving toward doing things “the Yocto Project way”, this means that some ways things are done in PetaLinux will be changing. It is strongly recommended that users become familiar with https://docs.yoctoproject.org/dev-manual/customizing-images.html.
Including Prebuilt Applications
PetaLinux Example
petalinux-create -t apps --template install --name myapp --enable
cd <plnx-proj-root>/project-spec/meta-user/recipes-apps/myapp/files
rm myapp
cp <path-to-prebuilt-app> ./Yocto Example
This example looks a lot longer, as all files, including the source code for “who where” are included below to make a complete working example that builds. PetaLinux achieves a similar goal by copying a template from the installation.
Step 1 - Create a new application layer
Only perform this step if you do not already have an application layer created
bitbake-layers create-layer ../sources/meta-myapplications
bitbake-layers add-layer ../sources/meta-myapplicationsStep 2 - Add your prebuilt application and Makefile
mkdir -p ../sources/meta-myapplications/recipes-whowhere/whowhere/files
pushd ../sources/meta-myapplications/recipes-whowhere/whowhere/files
cat << EOF > whoami_whereami.sh
#!/bin/sh
echo "You are" $(whoami) "on machine" $(hostname) "running" $(uname -s) $(uname -r)
EOFStep 3 - Make a Bitbake recipe
This points the build system to your Makefile and sources and specifies to use make to build and install them
cat << EOF | sed 's/^ /'$'\t''/' > ../whowhere_0.1.bb
FILESEXTRAPATHS:prepend = "${THISDIR}/files:"
LICENSE = "CLOSED"
LIC_FILES_CHKSUM = ""
SRC_URI = "file://whoami_whereami.sh\\
"
S = "\${WORKDIR}"
do_install () {
install -Dm 0755 \${S}/whoami_whereami.sh \${D}\${bindir}/whoami_whereami
}
EOFStep 4 - Change the directory back, and build the application
popd
bitbake whowhereStep 5 - Add the application to all images using your applications layer.conf and test
echo "IMAGE_INSTALL:append = \" whowhere\"" >> ../sources/meta-myapplications/conf/layer.conf
bitbake edf-linux-disk-imageCreating and Adding Custom Applications
PetaLinux Example
petalinux-create -t apps --name myapp --enableYocto Example
This example looks a lot longer, as all files, including the source code for “Hello world” and its Makefile are included below to make a complete working example that builds. PetaLinux achieves a similar goal by copying a template from the installation.
Step 1 - Create a new application layer
Only perform this step if you do not already have an application layer created
bitbake-layers create-layer ../sources/meta-myapplications
bitbake-layers add-layer ../sources/meta-myapplicationsStep 2 - Add your source code and Makefile
mkdir -p ../sources/meta-myapplications/recipes-hello-world/hello-world/files
pushd ../sources/meta-myapplications/recipes-hello-world/hello-world/files
cat << EOF > hello-world.c
#include <stdio.h>
int main(void)
{
printf("Hello, World!\n");
return 0;
}
EOF
## Makefile ##
cat << EOF | sed 's/^ /'$'\t''/' > Makefile
all: hello-world
hello-world: hello-world.c
\$(CC) \$(CFLAGS) \$(LDFLAGS) \$^ -o \$@
install:
install -d \${DESTDIR}\${BINDIR}
install -m 0755 hello-world \${DESTDIR}\${BINDIR}
uninstall:
\${RM} \${DESTDIR}/hello-world
clean:
\${RM} hello-world
EOFStep 3 - Make a Bitbake recipe
This points the build system to your Makefile and sources and specifies to use make to build and install them
## hello-world_0.1.bb ##
cat << EOF | sed 's/^ /'$'\t''/' > ../hello-world_0.1.bb
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
LICENSE = "CLOSED"
LIC_FILES_CHKSUM = ""
SRC_URI = "file://hello-world.c\
file://Makefile\
"
S = "\${WORKDIR}"
do_compile () {
oe_runmake
}
do_install () {
oe_runmake install DESTDIR=\${D} BINDIR=\${bindir}
}
EOFStep 4 - Change back directory, and build the application
popd
bitbake hello-worldStep 5 - Add the application to all images using your applications layer.conf and test
echo "IMAGE_INSTALL:append = \" hello-world\"" >> ../sources/meta-myapplications/conf/layer.conf
bitbake edf-linux-disk-imageCreating and Adding Custom Kernel Modules
PetaLinux Example
petalinux-create -t modules --name mymodule --enableYocto Example
Please see Incorporating Out-of-Tree Modules in the Yocto Mega Manual for details on building out-of-tree kernel modules. A brief example is illustrated below based off of those instructions
Step 1 - Create a new application layer
Only perform this step if you do not already have an application layer created
bitbake-layers create-layer ../sources/meta-myapplications
bitbake-layers add-layer ../sources/meta-myapplicationsStep 2 - Copy a kernel out-of-tree module example from the poky meta-skeleton sources into the local layer
mkdir -p ../sources/meta-myapplications/recipes-kernel
pushd ../sources/meta-myapplications/recipes-kernel
cp -rv ../../poky/meta-skeleton/recipes-kernel/hello-mod .Step 4 - Enable kernel module build in the layer
echo "MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += \"hello-mod\"" >> ../conf/layer.confStep 5 - Build root file system with the included out-of-tree module
popd
bitbake edf-linux-disk-imageKernel modules can be found in /lib/modules/<kernel-version> on the running target:
$ ls /lib/modules/`uname -r`/extra
hello.ko
$ sudo modprobe hello
[ 62.576953] hello: loading out-of-tree module taints kernel.
[ 62.578843] Hello World!
$ sudo rmmod hello
[ 477.634516] Goodbye Cruel World!Application Auto Run at Startup
PetaLinux Example
Follow the steps at PetaLinux Yocto Tips | PetaLinuxYoctoTips HowtoAutoRunApplicationatStartup
Yocto Example
Follow the steps at PetaLinux Yocto Tips | PetaLinuxYoctoTips HowtoAutoRunApplicationatStartup with the following changes:
Instruction Step 1 - Instead of using petalinux-create to create an application, make a new layer if needed, enable it for build, and create an empty folder ready to copy the myapp-init.service and myappinit.bb files:
bitbake-layers create-layer ../sources/meta-myapplications
bitbake-layers add-layer ../sources/meta-myapplications
mkdir -p ../sources/meta-myapplications/recipes-apps/myapp-init/filesCreate the myappinit.bb, files/myapp-init.service and files/myapp-init files as per the instructions into ../sources/meta-myapplications/recipes-apps/myapp-init
Instruction Step 4 - instead of running petalinux-build, run:
bitbake myappinitIf all builds well, enable it in your layer:
echo "IMAGE_INSTALL:append = \" myappinit\"" >> ../sources/meta-myapplications/conf/layer.confAnd then build with
bitbake core-image-minimal # (or a image of your choice)Adding Layers
PetaLinux Example
petalinux-config → Yocto Settings → User Layers
Yocto Example
Customizing Your Build for Specific Hardware has documentation on the bitbake-layers command. A quick example for a locally-hosted layer is shown below. Read the Yocto Mega Manual for more examples.
Enable the new layer using the bitbake-layers command:
bitbake-layers add-layer ../sources/meta-myapplicationsConfirm that it is enabled using
bitbake-layers show-layersAdding an Existing Recipe into the Root File System
PetaLinux Example
Locate the recipe
Add the CONFIG_<recipename> into <plnx-proj-root>/project-spec/meta-user/conf/user-rootfsconfig. Run
petalinux-config -c rootfsSelect the package and then run
petalinux-buildYocto Example
Modify either the conf/local.conf or a custom enabled layer’s conf/layer.conf and add the package:
echo "IMAGE_INSTALL:append = \" myrecipe\"" >> ../sources/meta-myapplications/conf/layer.conf #or
echo "IMAGE_INSTALL:append = \" myrecipe\"" >> conf/local.conf
bitbake edf-linux-disk-imageAdding a Package Group
PetaLinux Example
Step by step guide in detail are in UG1144:
Create a bb file
Add the configuration to user-rootfsconfig
Run the following command to select:
petalinux-config -c rootfsYocto Example
GUI package group modification functionality is not directly replicated in Yocto, the Yocto project expects this functionality to be text based. Users can add package groups to an image recipe (recommended for longer term use) or conf/local.conf(only recommended for adding packaged groups temporarily).
Please refer to Customizing Images Using Custom Package Groups for further details on how to customize and add package groups.
AMD maintained package groups can be found by searching for packagegroups in the meta-xilinx layers. For example using the command find ./ -name "*packagegroup*"
Customizing Device Trees
PetaLinux Example
© 2025 Advanced Micro Devices, Inc. Privacy Policy