/
PetaLinux to EDF Migration Guide

PetaLinux to EDF Migration Guide

For EDF flows please follow our page https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250585601
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

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:

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

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

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-machine-conf --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 directory

EDF 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 environment

Create 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 https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3250586143/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 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

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-boot

EDF 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-xlnx

Kernel 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 kernel

EDF 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-xlnx

Building

PetaLinux Example

petalinux-build # The default image built is petalinux-image-minimal

EDF 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-cmdline

Many 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-boot

EDF Example

MACHINE=<machine-name> bitbake xilinx-bootbin

Generate MCS Image

PetaLinux Example

petalinux-package --boot --u-boot --format MCS

EDF 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 --wic

EDF 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:1

More 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 --kernel

EDF 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:

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3258089693/Operating+System+Integration+and+Development+AMD+Versal+device+portfolio#Building-Images-for-QEMU

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/3268149250/Operating+System+Integration+and+Development+AMD+ZynqMP+device+portfolio#Building-Images-for-QEMU

Boot Image on Hardware with JTAG

PetaLinux Example

petalinux-boot --jtag

EDF 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-myapplications

Step 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) EOF

Step 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 } EOF

Step 4 - Change the directory back, and build the application

popd bitbake whowhere

Step 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-image

Creating and Adding Custom Applications

PetaLinux Example

petalinux-create -t apps --name myapp --enable

Yocto 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-myapplications

Step 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 EOF

Step 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} } EOF

Step 4 - Change back directory, and build the application

popd bitbake hello-world

Step 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-image

Creating and Adding Custom Kernel Modules

PetaLinux Example

petalinux-create -t modules --name mymodule --enable

Yocto 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-myapplications

Step 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.conf

Step 5 - Build root file system with the included out-of-tree module

popd bitbake edf-linux-disk-image

Kernel 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 https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842475/PetaLinux+Yocto+Tips#PetaLinuxYoctoTips-HowtoAutoRunApplicationatStartup

Yocto Example

Follow the steps at https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842475/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/files

Create 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 myappinit

If all builds well, enable it in your layer:

echo "IMAGE_INSTALL:append = \" myappinit\"" >> ../sources/meta-myapplications/conf/layer.conf

And 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-myapplications

Confirm that it is enabled using

bitbake-layers show-layers

Adding 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 rootfs

Select the package and then run

petalinux-build

Yocto 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-image

Adding 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 rootfs

Yocto 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