Fixed Platform Design on Zynq-7000 in PetaLinux 2024.1

In my last two project posts, I've been covering the workflow for or fixed platform designs on Zynq-7000 based FPGA boards using the 2024.1 of the AMD FPGA design tools Vivado, Vitis Unified, and PetaLinux. As a quick reminder, there are two main workflows for AMD-based FPGAs: fixed platforms where the design in the programmable logic of the Zynq chips is set and does not change, and extensible platforms where the design in the programmable logic of the Zynq chips is updated/reconfigurable from the software running on the ARM-core processor of the Zynq chip.

So far, I've covered the hardware design in Vivado here, and the application software development in the Vitis Unified IDE here. In the Vitis Unified IDE workflow for Linux-based applications, I referenced that it requires components from the Linux image that will be running on the Zynq such as the boot components and sysroot SDK. That Linux image is built with the Yocto-based AMD toolset, PetaLinux.

And also like I mentioned, PetaLinux can only be installed on a Linux host PC. So Windows users will need some sort of virtual machine or emulation option like WSL, although it's worth noting that AMD only provides official support for native Linux installs on host develpment systems. However from personal experience, I highly recommend using a Linux host PC in general for the entire workflow as I've generally found less bugs/issues with the AMD tools as compared to Windows (although that may just be due to the fact that I'm not as knowledgeable with Windows as I am with Linux).

Download BSP (If Applicable)

The same way that Vivado has board definition files (BDFs) to "pre-configure" a project for settings specific to an FPGA development board (versus a project targeting just an FPGA chip itself that's on a custom PCB), PetaLinux has board support packages (BSPs) to apply the relevant settings for a target FPGA development board such as boot mode, available peripherals, etc.

AMD provides PetaLinux BSPs for their own boards in the same downloads page where the PetaLinux installer itself lives.

If using a 3rd party Zynq FPGA development board like I am with the Zybo Z7 from Digilent, check the company's website and/or Github repository to see if they provide a PetaLinux BSP.

Create PetaLinux Project

To create a project, either a blank Zynq-based project can be created or a BSP can be used.

To create a blank project, the --template flag must be used to specify that the target architecture is Zynq, and the --name flag must also be used to name the PetaLinux project (while Diligent does offer BSPs for their boards, they were not available for the 2024.1 version of PetaLinux at the time of writing so I just created a blank project):

~$ petalinux-create project --template zynq --name linux_os

Creating a project from a BSP is a bit simple as the path to the.bsp file is the only required argument since the rest of the required settings such as the target architecture is specified within the BSP.

~$ petalinux-create project -s <path to .bsp file>

The PetaLinux project name will default to the same name as the.bsp file, but if desired, the --name flag can still be used to specify a different name for the project.

Import Hardware Design from XSA

The first thing to do after creating a PetaLinux project is to pull in the hardware design in the XSA file that was exported from Vivado.

If the project was created from a BSP, then a bare-bones hardware design does exist in the project so a basic image can be build for the FPGA development board without creating a design in Vivado. However, if any modifications or custom HDL was added in Vivado, the XSA still needs to be pulled into the project for those changes to appear.

After creating the project, change directories into it and use the --get-hw-description flag with the petalinux-config command to point to the location of the XSA:

~$ cd ./linux_os/
~/linux_os$ petalinux-config --get-hw-description ../

After reading in the hardware details from the XSA file, the hardware system configuration editor will then open in the form of an ASCII GUI:

Most settings are configured automatically based on the hardware design details specified in the XSA. The main hardware configuration settings that I find myself updating in the majority of my PetaLinux projects is under the Image Packaging Configuration tab. This is where the root filesystem type and relevant boot settings are configured.

Especially for Zynq-based designs, my root filesystem lives on an SD card. And I also want it to be persistent (ie - it keeps changes made between power cycling). So under Root Filesystem type, change it to EXT4 (SD/eMMC/SATA/USB).

I also am not utilizing TFTPboot for my Zybo (ie - the root filesystem is loaded from a network location versus local storage like an SD card), and I found starting with PetaLinux version 2024.1 that if TFTPboot is not fully configured in the PetaLinux project then it will cause the project build to fail.

So if not using TFTPboot, be sure to disable it here in the Image Packaging Configuration by disabling the copy final images to tftpboot option:

Once all of the desired configurations have been updated, exit the hardware system configuration and save the changes when prompted:

Then wait for PetaLinux to finish applying all of the new settings:

If any hardware configuration settings need to be updated in the future, the petalinux-config command with no arguments will reopen the the hardware system configuration editor.

~/linux_os$ petalinux-config

However, if the hardware design is updated in Vivado and the XSA is re-exported (even if the XSA is in the same place with the same name) then the XSA needs to be re-imported for the hardware changes to be detected.

~/linux_os$ petalinux-config --get-hw-description ../

This is because PetaLinux only reads the XSA this one time when the --get-hw-description flag is used and at no other time.

Configure Root Filesystem

While a PetaLinux project will automatically enable the absolute bare minimum filesystem libraries to boot, you'll generally need to enable basic tools for regular use like git, ping, etc.

To configure the root filesystem itself, use the --rootfs flag with the petalinux-config command:

~/linux_os$ petalinux-config -c rootfs

This will launch the root filesystem configuration editor:

Each individual libraries/commands can be enabled al-a-cart under the Filesystem Packages tab. But PetaLinux has a handy option with where similar, commonly used libraries/commands are grouped together and can be enabled all at once with Petalinux Package Groups.

The PetaLinux package groups that I use in almost every project are:

• packagegroup-petalinux
• packagegroup-petalinux-networking-stack
• packagegroup-petalinux-python-modules
• packagegroup-petalinux-utils

To see what libraries/commands are in a PetaLinux package group, highlight the specific packagegroup and select Help:

Then exit the root filesystem configuration and save the changes when prompted:

Again, wait for PetaLinux to finish applying all of the new settings:

Configure Kernel

When it comes to the kernel, again PetaLinux will automatically enable everything required for the Zynq architecture based on the settings selected in the hardware configuration editor and the filesystem packages enabled in the root filesystem configuration editor. However in some instances, extra modules may be needed for peripherals such as USB WiFi dongles.

To enable/modify the kernel modules in a project, the configuration editor can be brought up by passing the kernel argument to the petalinux-config command:

~/linux_os$ petalinux-config -c kernel

Configure U-Boot

For the most part, the settings specified in the hardware system configuration settings (specifically the selections made under the Image Packaging Configuration tab) will automatically set everything needed in the Linux secondary bootloader (U-BOOT) settings.

However, if further custom modifications are needed, the configuration editor can be brought up by passing the u-boot argument to the petalinux-config command:

~/linux_os$ petalinux-config -c u-boot

Add Custom Application Developed in Vitis Unified IDE

As I mentioned in the Vitis Unified project tutorial, to make the developed Linux application a permanent fixture on the target hardware, that must be done in the corresponding PetaLinux project.

To create a custom application, use the apps argument for the petalinux-create command with --template flag to specify language (C or C++), --name flag to specify the application name, and the --enable flag to include it in the next project build:

~/linux_os$ petalinux-create apps --template c --name linux-hello-world --enable

This creates an application template in the <PetaLinux project path>/project-spec/meta-user/recipe-apps directory:

Then within the files directory of the application, is the file with the main function:

This main C file is where the main function from the Linux application developed/debugged in Vitis needs to be copy+pasted, and and the files directory is where any other C source or header files need to be copied to.

If any other C source or header files are copied to the files directory, then they need to be specified in the application's bitbake (.bb) file to be included in the build.

Open the bitbake (.bb) file in the application directory and specify the additional sources files for SRC_URI the same way the main source file and Makefile already are:

Be sure to save any changes made to the source files and bitbake file.

Build Project

Once the PetaLinux project has been fully configured as desired, it can be built with the petaliunx-build command:

~/linux_os$ petalinux-build

The first build of a project will take a little while, especially if a lot of filesystem packages and applications have been enabled.

A weird quirk I've found with PetaLinux 2024.1 is that the first time I try to run a build for a new project, it always seems to fail with a weird random mirror error. But immediately attempting to run the build again seems to resolve the issue.

This is probably some weird issue stemming from a mistake I've made setting up my environment, but I haven't been able to track it down yet, and I have zero issues with PetaLinux 2023.2 and 2023.1 on the same machine. So who knows?

Package Boot Binary

Once the project has been successfully built, the boot binary (BOOT.BIN) needs to be packaged for it.

In my case, I am booting my Zybo from the SD card so the boot binary needs to at least contain the Zynq FSBL (first stage bootloader) and FPGA bitstream, all of which can be found in the PetaLinux project output directory <PetaLinux project path>/images/linux:

~/linux_os$ petalinux-package --boot --fsbl ./images/linux/zynq_fsbl.elf --fpga ./images/linux/system.bit --u-boot

If regenerating the boot binary due to rebuilding the project, the --force flag will need to be used to over-write the existing BOOT.BIN file.

Package SD Card Image (If Applicable)

If booting from an SD card (versus booting directly into INITRD/INITRAMFS), PetaLinux has a toolset that will package an image file for an SD card that can used with a tool like balenaEtcher to flash the SD card. This is utilized with the --wic flag with the petalinux-package command.

In my case for the Zybo being booted from the SD card, the boot files required in the boot partition of the SD card are the boot binary, Linux kernel, device tree blob, and boot script (specified with the --bootfiles flag). And the root filesystem placed on the root specified partition of the SD card with the --rootfs-file flag:

~/linux_os$ petalinux-package --wic --bootfiles "BOOT.BIN image.ub system.dtb boot.scr" --rootfs-file ./images/linux/rootfs.tar.gz

PetaLinux will take a couple of minutes to generate the wic image with usually ends up being a little over 6GB in size and needs at least an 8GB SD card.

Then simply use an imaging tool like balenaEtcher to flash the wic image onto an SD card:

This does fully erase and reformat the SD card so be sure there is nothing import on the SD card before flashing it with the wic file.

First Boot

To boot the Linux image on the target FPGA connect to its serial output terminal (which is on the same USB port as the JTAG for the Zybo), install the SD card, set the boot mode to SD (or QSPI if that's what was set in the PetaLinux project instead), and optionally connect the FPGA board to a local area network or your router via Ethernet:

Power on the FPGA development board and connect to it with a serial application such as Putty or TeraTerm.

By default, PetaLinux configures the Linux image to ask for the user password to be set at first boot. This option can be changes in the root filesystem settings under the Petalinux RootFS Settings tab if you want to set the username/password to already be defined in the PetaLinux project.

At this point, with the Linux image successfully running on the Zybo board that demonstrates the overall workflow in PetaLinux for a fixed platform design on the Zynq-7000. Let me know if there are any other use cases you'd like to see.