Showing results for 
Show  only  | Search instead for 
Did you mean: 

Introduction to PetaLinux Part 1

12 0 13.6K

Please Note: This blog uses tools tips. Anywhere you see an underlined word, hover over it to see an explanation! 



This blog is aimed at anyone who wants to get started with PetaLinux and learn about its key tools, concepts and capabilities. In the first blog entry, we will look at how to create a PetaLinux project for the ZCU102 development board, and how to modify an image. 

I will run through the basic steps needed in this tutorial, however, the scope of the blog is limited. You can find out more information about PetaLinux on the Xilinx website here


What Is PetaLinux? 

PetaLinux is a set of high level commands that are built on top of the Yocto Linux distribution. PetaLinux tools allow you to customize, build, and deploy Embedded Linux solutions/Linux images for Xilinx processing systems. It is tailored to accelerate design productivity, and works with the Xilinx hardware design tools (like Vivado) to ease the development of Linux systems for Zynq® UltraScale+™ MPSoC, Zynq®-7000 SoCs, and MicroBlaze™.

Basically, it is a set of simplified commands that can be used to quickly and easily make custom Linux systems/images for Xilinx boards!   

PetaLinux Design Flow:

The PetaLinux design flow can be seen below. This tutorial will mostly focus on areas 1-4 shown in the diagram. It is assumed that you have already installed and set up the PetaLinux tools on your system, but if you have not, you can read the Getting Started Guide here.

The 'Software Settings & Bootloader' section, which is usually done in the SDK, will not be explored in detail in this blog. The section is completed automatically when the Tcl script provided with this blog is run. 



Step 1: Create the Hardware Platform:

Note: you can skip this step by using the pre-built HDF file delivered with this blog post.


This section covers the steps to follow when you want to create custom hardware for your board using Vivado 2018.3. From Vivado we will output a Hardware Description File (HDF). 

In order to build a targeted PetaLinux project for a board, the PetaLinux tools need to be aware of the underlying hardware system on the board. The HDF file describes the hardware architecture of your board. It is mandatory if you want to build a PetaLinux project, so that the resulting image can configure the board correctly when powered on.

To speed up the design process, a Tcl script is attached to this blog. When run in Vivado, the Tcl script will do the following:

  • Create the Output Products for the block diagram
  • Create the Hardware Description Language (HDL) wrapper
  • Generate the Bitstream
  • Export the hardware to SDK to create the Hardware Description Language (HDF) file



Download the Tcl script attached to this blog. It contains a list of instructions to create and build the hardware in Vivado 2018.3.

Launch Vivado 2018.3.

Use the cd command in the Tcl prompt at the bottom of the GUI to change directory to the location where the Tcl script is saved:



Next use the source command to run the script:



This will create the hardware block diagram shown below.

It represents the underlying architecture on our Zynq UltraScale+ board:


Alternatively, if you do not want to use the Tcl script and are familiar with Vivado, you can create the design manually using the diagram above as a reference. If you want to use a version of Vivado older than 2018.3, you must create the diagram manually. 


Step 2: Create the PetaLinux Project


In this step we will create a basic PetaLinux project using the HDF file created in the previous step.

These steps are run on a machine using Linux OS. As I have a Windows system, I use a virtual machine with Linux OS and PetaLinux 2018.3 installed.

There are two sources that can be used to create a PetaLinux project, BSP and a template project. 

  1. BSP

This contains some pre-built files which can be used to speed up the development process. It can only be used with standard Xilinx development boards as it contains a HDF file that describes the underlying architecture of the board.

Because it contains a HDF file, you can skip Step 1 above if you use this method. In total, it contains the following:

  • PetaLinux Project and Workspace
  • HW Project, HDF and bitstream
  • Prebuilt images for FS-BOOT (in case of MicroBlaze), ATF (bl31 in case of Zynq UltraScale+), Linux, U-Boot, pmufw (Zynq UltraScale+), rootfs, dtb (device tree blob), BOOT.bin etc.

Various BSPs for different boards can be found here.

To create a PetaLinux project with a BSP, use the following command in the Linux terminal running PetaLinux:

petalinux-create -t project -s <path to BSP>


  1. Template Project

In this tutorial we will be using a template project for the ZynqMP to create the PetaLinux project. A template project must be used if you have a custom Xilinx board, but can also be used with standard Xilinx development boards. A BSP cannot be used with custom boards, as it contains a HDF which only describes standard Xilinx development board architectures. 



Open a terminal in Linux running PetaLinux. 

Type the following command into the Linux terminal. This creates a template of a project called first_linux for the zynqMP.

petalinux-create --type project --template zynqMP --name first_linux

Next you can combine the template just created, with the hardware information created in Vivado in Step 1.

Inside the HDF file exported from Vivado, is the Hardware Handoff File (HWH). PetaLinux uses HSI utilities to extract information about the hardware from this file, as well as information such as IP, nets, ports, and interfaces that are used in other tools such as the devicetree generator. It will also be used to populate some of the system level project information about your hardware system. 

To extract the hardware information, use the following commands:

cd first_linux 
petalinux-config --get-hw-description=<path to HDF>

The system config window will appear. This is where users can make system level changes to the PetaLinux project.

This config can also be opened using the petalinux-config command. As no system level changes are needed, you can exit out of the window and then save.





Step 3: Editing the Image


In this step we will try and modify the standard PetaLinux project created by the PetaLinux tools in the previous step. 

PetaLinux uses recipes to perform tasks. For example, if you wanted to generate a devicetree, normally you would need to complete a series of different steps to do this (Download the source, import the HDF file... etc.). These steps can be combined and run as a single 'devicetree' recipe in PetaLinux.

The recipes are built using Bitbake. It will check if the recipes are dependent on each other/other tasks and distribute the build tasks appropriately. Users can pass information to Bitbake via the local.conf file in the conf folder.

PetaLinux recipes are also organised into Layers

A number of standard recipes are used to create an image in PetaLinux. However, if you want to customise an image, you cannot directly modify a recipe or a PetaLinux build directory.

This is because, due to the tools-flow, the recipes and directories are overwritten every time you rebuild the project, so any changes will be lost. Instead, you must create something called a ‘recipe append’. This is simply a file which contains all requested modifications to the standard recipes. The system checks the ‘recipe appends’ at build time and uses them to modify the image, as shown in the diagram below:




Now that you understand the background, let's try and modify a part of our image, the First Stage Bootloader (FSBL).

  1. Create the file structure below. The folders project-spec, meta-user and recipies-bsp should already have been created in your root folder after you built the PetaLinux project in the previous step.Step3_22.png

    Note: The meta-user layer is a place holder for all user-specific changes. You can add your own bbappend and configuration files in this layer.

2. Copy the fsbl_%.bbappend append file (located in <ptlx-proj-root>\project-spec\meta-plnx-generated\recipes-bsp\fsbl) in the newly created ‘fsbl’ folder. The 'fsbl' folder will now contain a files folder and the fsbl_%.bbappend file as shown below. 


Note: The meta-plnx-generated layer which contained the original fsbl_%.bbappend file holds all bbappends and configuration fragment (cgf) for all components. All files in this layer are generated by the tool based on HDF and user configuration. As all files in this folder are over-written every time we build, we cannot make any changes to this layer directly. This is why we move the .bbappend file to the meta-user layer.

3. Update the fsbl_%.bbappend file with the content below. 

Note: You will need to tell the fsbl_%.bbappend to use the patch file by adding the patch file name to the SRC_URI_append variable. The location of the patch file is given by the FILESEXTRAPATH_prepend variable. You can turn on debugging by updating the YAML_COMPILER_FLAGS_append variable with the value below. 

#Force to use embeddedsw repo 
#Patch FSBL 
SRC_URI_append += " file://0001_fsbl_patch.patch" 
FILESEXTRAPATHS_prepend := "${THISDIR}/files:" 


4. Add the 0001_fsbl_patch.patch from the fsbl_patch folder (from the zip file attached to this blog), into the 'files' folder, so that it is one layer down from the fsbl_%.bbappend file. It will update the source code with a “Hello Linux PDC” printf statement. 


5. When the FSBL is created, the content in the bbappend file will be used to modify the FSBL recipe in the build directory. To create the FSBL and apply the modification, you can use the command below:

petalinux-config -c bootloader


6. To verify that the patch has been applied correctly:

In 2018.3 and above:

The changes will be made to a file in the tmp folder. This is your Build Directory. To find the location of your tmp folder open the configuration window: 


When the Menu tab opens, go to Yocto Settings -> TMPDIR Location. Copy the location shown. 


Exit out of the settings. You will need to search for a file called xfsbl_hooks.c in your TMPDIR, and open it:

find /tmp/<TMPDIR> -name xfsbl_hooks.c

Copy the location shown in the terminal. You can open the file using the 'gedit' command:

gedit /tmp/<TMPDIR>/<xfsbl_hooks.c Location>


Then on line 96, you should see a print statement.




In 2018.2 and earlier versions:

Open the <plnx-projroot>/components/plnx_workspace/fsbl/src/xfsbl_hooks.c. This is the Build Directory for the FSBL for the 2018.2 version and earlier. Then on line 96 in xfsbl_hooks.c, you should see the print statement.



If you do, then well done, you have successfully created a recipe append for the FSBL!


Note: If making further changes to the FSBL, it is recommended that you clean the existing FSBL in the build directory first (if it exists) using the commands below.

Only with the 2018.2 version and earlier will you need to use the rm command to remove the plnx_workspace directory first.  

rm -rf components/plnx_workspace
petalinux-build -x mrproper