/
PetaLinux to Yocto - Command Cross Reference

PetaLinux to Yocto - Command Cross Reference

Owned by Chaplin, Kris
Last updated: Jan 31, 2025 by Povilus, Sam
9 min read

This reference is a summary of the major commands in PetaLinux and their equivalent functionality in native Yocto. This can be used as a ready reckoner for those who are used to using PetaLinux and are looking to replicate their workflow in Yocto.

The primary source of detail on Yocto commands should be the documentation provided by the project. This can be found at https://docs.yoctoproject.org/dev/ . Select the version of Yocto from the pull down menu for version-specific context of the documentation

Table of Contents

Creating a Project

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]

Yocto 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 can be changed in local.conf, or on invocation of the bitbake build command, using the MACHINE=[target template] command line override.

mkdir myproject && cd myproject repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2023.1 repo sync source setupsdk ls -l ../sources/meta-xilinx/meta-xilinx-core/conf/machine/*.conf # Show available templates sed -i "/MACHINE ??=/c\MACHINE ??= \"zynqmp-generic\"" conf/local.conf # Set the machine template in conf/local.conf (change as desired) # Alternatively, you could just override with MACHINE=zynqmp-generic on the bitbake command when building to select the appropriate board.

Create a new project and target a specific pre-built BSP

A PetaLinux BSP is a configuration file containing all 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. The meta-xilinx-bsp layer has a number of built-in BSPs in native Yocto that can be used as a starting point for supported boards.

PetaLinux Example

Download a BSP file from the website - for example, xilinx-zcu102-v2023.1-05080224.bsp

petalinux-create --type project -s xilinx-zcu102-v2023.1-05080224.bsp cd xilinx-zcu102-2023.1/

Yocto Project Example

mkdir myproject && cd myproject repo init -u https://github.com/Xilinx/yocto-manifests.git -b rel-v2023.1 repo sync source setupsdk ls ../sources/meta-xilinx/meta-xilinx-bsp/conf/machine/*.conf ../sources/meta-kria/conf/machine/*.conf # Show available BSPs sed -i "/MACHINE ??=/c\MACHINE ??= \"zcu102-zynqmp\"" conf/local.conf # Set the machine in conf/local.conf (change as desired) # Alternatively, you could just override with MACHINE=zcu102-zynqmp on the bitbake command when building to select the appropriate board.

Configuring and Building

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/2023.1/tool/settings.sh cd xilinx-zcu102-2023.1 #PetaLinux project directory

Yocto Example

cd myproject source setupsdk #This file is made during initial clone with repo.

Importing a Hardware Configuration

PetaLinux Example

petalinux-config --get-hw-description <path to XSA file>

Yocto Example

This Yocto Example is broken into two pieces. In the first piece, we create a new layer, which allows us to store details about a machine configuration. This layer has a configuration file made, to specify that the hardware is similar to the ZCU102 board, and then we make any necessary changes in that file to override defaults. In our case, we override the XSA file that is being used, to point to our own one. Note - this only needs to be done once per new xsa file. Once the layer is in place and configured, we only need to follow part 2, to change the machine name in local.conf to use the configuration specified.

Understanding and Creating Layers from the Yocto project documentation gives more detail on layers, how to create them and add them and best practices

Part 1 - Setting up a new layer and machine configuration (do once)

bitbake-layers create-layer ../sources/meta-myhardware # Create a new layer for your custom hardware configuration to live (name as applicable) bitbake-layers add-layer ../sources/meta-myhardware # Allow bitbake to find the layer when building mkdir ../sources/meta-myhardware/conf/machine # Make a new folder in your layer to store machine configurations cat << EOF > ../sources/meta-myhardware/conf/machine/myhardware-zcu102-zynqmp.conf #Base this machine configuration off of the zcu102 board and then make changes below require conf/machine/zcu102-zynqmp.conf HDF_BASE = "file://" # Replace with the path to your XSA file from hardware HDF_PATH = "/path/to/my/design.xsa" EOF

Part 2 - Edit the configuration to use the newly created machine configuration

The command below replaces the line in local.conf to specify the new target machine using the command line tools. However in an active project you might prefer to open the file in a text editor, find the line and modify it by hand.

sed -i "/MACHINE ??=/c\MACHINE ??= \"myhardware-zcu102-zynqmp\"" conf/local.conf # Set the machine in conf/local.conf (change name as applicable)

Building a System Image

PetaLinux Example

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

Yocto Example

bitbake petalinux-image-minimal

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 and Booting

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

Yocto Example

bitbake xilinx-bootbin

Generate MCS Image

PetaLinux Example

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

Yocto Example

Details can be found in the meta-xilinx documentation here : https://github.com/Xilinx/meta-xilinx/blob/master/docs/README.booting.flash.md

Boot Image on QEMU

PetaLinux Example

petalinux-boot --qemu --u-boot petalinux-boot --qemu --kernel

Yocto Example

runqemu nographic slirp

 

More runqemu options are available in the documentation https://docs.yoctoproject.org/dev/dev-manual/qemu.html

Boot Image on Hardware with an SD card

PetaLinux Example

petalinux-package --boot --fsbl zynqmp_fsbl.elf --fpga system.bit --u-boot --force petalinux-package --wic

Yocto Example

To automatically create an SD card raw image WIC file, you can either add IMAGE_FSTYPES:append=" wic" to conf/local.conf:

sed -i '/MACHINE ??=/a IMAGE_FSTYPES:append=" wic"' conf/local.conf

or if you have a custom machine layer, you can add the IMAGE_FSTYPES += “wic” field to that layer:

echo 'IMAGE_FSTYPES += "wic"' >> ../sources/meta-myhardware/conf/machine/myhardware-zcu102-zynqmp.conf # Change path to match your machine layer

The next invocation of bitbake <target filesystem image> will then create the WIC file to be copied to the SD card.

More detail on how to write an SD card image can be found in https://github.com/Xilinx/meta-xilinx/blob/master/docs/README.booting.storage.md or Flashing and Booting the PetaLinux Image Using WIC Image

Boot Image on Hardware with JTAG

PetaLinux Example

petalinux-boot --jtag

Yocto Example

A recipe is being added to meta-xilinx for the 2024.1 release. In the interim, petalinux-boot --jtag has a --tcl option that can be used to output an architecture-specific example script file, which can be modified to use the artifacts generated by the Yocto build system.

Upgrading the Workspace

Upgrade the workspace

PetaLinux Example

petalinux-build -x mrproper petalinux-upgrade -f [sdk update path] petalinux-build

Yocto Example

Details of updating a Yocto project to the latest branch can be found in the online documentation General Migration Considerations

Upgrading the Installed tool with more Platforms

PetaLinux Example

petalinux-upgrade -u https://petalinux.xilinx.com/sswreleases/rel-v2023/sdkupdate/ -p <architecture>

Yocto Example

Yocto does not need a manual install step. If MACHINE is changed to a new architecture, bitbake will perform the necessary steps to build for that platform.

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 “whowhere” 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 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 back directory, 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 petalinux-image-minimal

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 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 specifyies to use make to build and install them

cat << EOF | sed 's/^ /'$'\t''/' > ../hello-world_0.1.bb 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 petalinux-image-minimal

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 petalinux-image-minimal

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 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/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 core-image-minimal

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*"

Related content

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy