ZCU104_MPSoC Development - Petalinux 2024.2 Basic Tutorial

About Project

The ZCU104 MPSoC Development Platform: PetaLinux 2024.2 Basic Tutorial is a step-by-step guide to setting up, configuring, and deploying PetaLinux 2024.2 on the Zynq UltraScale+ MPSoC (ZCU104). This tutorial covers everything from generating a hardware design in Vivado 2024.2, exporting hardware file (.xsa), and building a customized embedded Linux system with PetaLinux 2024.2.

The project aims to simplify the learning curve for FPGA developers and embedded engineers working with ZCU104, demonstrating how to boot Linux and develop real-world applications on this powerful platform.

AMD's FPGA tools have evolved significantly, with updates like Vitis Unified IDE and enhancements in PetaLinux 2024.2. With these changes, a structured and updated guide is essential to help developers transition smoothly to the latest tools. Unlike older guides focused on Zynq-7000 SoC, this project is tailored for Zynq UltraScale+ MPSoC (ZCU104).

This tutorial is designed for FPGA designers, embedded software developers, and Linux enthusiasts looking to leverage PetaLinux on ZCU104 for custom embedded applications

Setting Up Environment

1. Installation Requirement

The PetaLinux tools installation requirements are:

a. Minimum workstation requirements:

• 8 GB RAM (recommended minimum for AMD tools)
• 2 GHz CPU clock or equivalent (minimum of eight cores)
• 100 GB free HDD space

b. Supported OS

• Completely removed CENTOS to align with upstream Yocto.
• Ubuntu Desktop/Server 20.04.5 LTS(64-bit), 20.04.6 LTS, 22.04.1 LTS, 22.04.2 LTS, 22.04.3 LTS, 22.04.4 LTS and 24.04 LTS
• OpenSuse Leap 15.4- Redhat 9.4
• AlmaLinux 8.7, 8.10, 9.1, and 9.

2. Tools Required

Followings are the tools required to build petalinux 2024.2

• Xilinx Vivado 2024.2 (https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools.html)
• PetaLinux Installer (https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html)
• Required Board Support Package BSP (https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html)

3. Petalinux Installation Steps

Open the linux terminal

• Command to check Ubuntu Linux Version: lsb_release -a

• First, We need to update our Linux by the command: sudo apt update
• After updating the linux, make a folder where we want to Install petalinux by using the command: $sudo mkdir -p /home/username/petalinux_sdkk/
• Now, Install the petalinux by using the commands: chmod +x petalinux-v2024.2-11062026-installer.run and then sudo ./petalinux-v2024.2-11062026-installer.run /home/inam/petalinux_sdk
• First time we get error while Installing Petalinux because of some dependencies required to Install Petalinux i.e., ncurses-dev, libtool etc. We first Install these dependencies by using the command: sudo apt install -y xterm autoconf libtool texinfo build-essential ncurses-dev
• Then we again install the Petalinux by using above mentioned command.

Petalinux Working Environment Setup

After the successfull Installation of Petalinux, We need to setup the working environment.

• Sourcing the appropriate petalinux setting script by using the command: source ./settings.sh

• Now, Verify the working environment has been set by using the command: echo $PETALINUX. This will output the Installted Petalinux path.

Creating a Project

Creating a Project Using BSP

• Change the directory where we have our downloaded BSP.
• Run the petalinux-create command on the command console to create a new project like: petalinux-create -t project -s /home/inam/BSPs/xilinx-zcu104-v2024.2-11110212.bsp

• Now, we need to go to the project path created by petalinux tool.
• After this we need to configure the hardware platform but for this we first need to export the hardware platform with Vivado to petalinux project.

Configuring a Hardware Platform with Vivado Design Suite

This section describes how to make a hardware platform ready for PetaLinux using Vivado tool.

• Open Vivado and load your hardware project.

• Ensure that your Processing System (PS) configuration and peripherals are correctly set up.

• Click File → Export → Export Hardware
• In the Export Hardware Platform window:
• Select Include bitstream if you want to package it.
• Choose the desired output directory.
• Click OK.

• The .xsa file will be generated in the selected directory.

After configuring your hardware project, the PetaLinux project requires a hardware description file (.xsa file) with information about the processing system.

Importinga Hardware Configuration

• Go to the petalinux project directory

• Import the Hardware description with "petalinux-config" command i.e., petalinux-config --get-hw-description /home/inam/Vivado_Proj/
• /home/inam/Vivado_Proj/ means the path of your.xsa file but here you may see issues if you use xsa flow.

([ERROR] This Project was configured with "sdt", you may see issues if you use the same project for "xsa" flow)

• In PetaLinux 2022.1 and later, Xilinx introduced a new System Device Tree (SDT) flow instead of the traditional XSA-based flow.
• If your project was created using the sdt (System Device Tree) method, then switching to the older xsa-based flow may cause issues.
• The ZCU104 BSP (Board Support Package) utilized in this setup follows the SDT flow, This can be confirmed by checking the project configuration file: cat project-spec/configs/config | grep DT_FLAVOR.
• If the output is: DT_FLAVOR="sdt", It indicates that the project is using the System Device Tree (SDT) flow.
• Whereas the default ZynqMP template in PetaLinux follows the XSA flow.
• SDT flow in PetaLinux is supported only for, AMD Zynq™MP, SOM and Zynq 7000 BSPs only; MicroBlaze™ are excluded.
• Compared to the Traditional XSCT-based build flow (by providing xsa file as input to petalinux-config.), the SDT (System Device Tree) project build takes more time due to the multi-configuration support in the SDT flow. The number of sstate checks and the number of parsed recipes are also higher.

SystemDeviceTreeFlowto Build Images

Before proceeding, place the system device-tree files provided by the hardware developer in a location accessible by the user running the PetaLinux builds.

Generate the system device-tree files using the steps mentioned:

• First make a New Folder or directory for the System Device-Tree files.

• Now, In SDT Flow, XSCT is only used to run the SDTGen tool, which extracts hardware information from the XSA file and generates System Device Tree (SDT) files. For this go the path of XSCT binary from the installed Vitis tool i.e., (say: /home/abc/Xilinx/Vitis/2024.1/bin/xsct)

• Now, Put these commands,
• set outdir [lindex $argv 1]
• set xsa [lindex $argv 0]
• exec rm -rf $outdir
• sdtgen set_dt_param -xsa /home/inam/Vivado_Proj/design_1_wrapper.xsa -dir /home/inam/sdt_out/
• sdtgen generate_sdt

• Reference related to above sdt flow commands system-device-tree-xlnx/README.md at master · Xilinx/system-device-tree-xlnx · GitHub
• Output files for sdt based flow generated like this

• Now, Import the hardware description with petalinux-config command: petalinux-config --get-hw-description /home/inam/sdt_out/

This launches the top system configuration menu.

Then Goto Image Packaging Configuration and select EXT4 (SD/eMMC/USB).

and I also am not utilizing TFTPboot for my ZCU104 (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.

We can do Ethernet Settings under Subsystem Hardware Settings.

If you want your ZCU104 board to obtain an IP from a router/network, enable "Obtain IP address automatically"

• If you need a fixed IP, leave the DHCP option disabled and configure the static IP, netmask, and gateway. by pressing Y.

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

After this, Run the petalinux command to configure rootfs :

petalinux-config -c rootfs.

This will pop up the roof system configuration GUI

• Now, It is recommedned to add packagegroup-core-buildessential under Filesystem Packages -> misc -> packagegrouo-core-buildessential.

The packagegroup-core-buildessential package is a collection of essential development tools, such as gcc, make, and other compilers/utilities needed for compiling software on the target system.

• Here you can add user package examples under userpackages, like I've added basic gpio-demo basic example.

Once all of the desired configurations have been updated, exit the root configuration and save the changes.

Build a System Image

This section assumes that we have the petaLinux tools software platform ready to build a Linux system to our hardware platform.

Now, we runpetalinux-build tol build the system image.

This step generates a device tree DTB file, a first stage boot loader (for Zynq 7000 devices, Zynq UltraScale+ MPSoC, and MicroBlaze), PLM (for Versal adaptive SoC), PSM (for Versal adaptive SoC) and TF-A (for Zynq UltraScale+ MPSoC and Versal adaptive SoC), U-Boot, the Linux kernel, a root file system image, and the U-Boot boot script (boot.scr). Finally, it generates the necessary boot images.

First time, we get this error in petalinux build process due to a missing or unbuildable dependency: libvcu-omxil.

This error will be only for the hardwares that supports VCU (e.g., ZCU104, ZCU106, ZCU216, etc.)

We need to enable it by going to project directory and then project-spec/meta-user/conf/petalinuxbsp.conf

# Enable VCU feature for ZCU104

MACHINE_FEATURES:append = " vcu"

SOC_VARIANT = "ev"

Silentconfig

After doing this, now we need to silentconfig the petalinux project by using the command

The --silentconfig option allows you to reuse a prior configuration. Old configurations have the file name CONFIG.old within the directory containing the specified component for unattended updates. You can change the configurations without opening system level configuration menu. You can directly edit

/project-spec/configs/config file and issue petalinux-config --silentconfig.

Now, Finally again we build the image by using the command petalinux-build.

Now, our Petalinux project is successfully built.

Petalinux-Package

• The petalinux-package tool packages a PetaLinux project into a format suitable for deployment.
• The tool provides several workflows whose operations vary depending on the target package format.
• The supported formats/workflows are boot, bsp, sysroot, wicand prebuilt.
• The petalinux-package tool is executed using the package type name to specify a specific workflow in the format petalinux-package PACKAGETYPE

The most common use case is generating a BOOT.BIN file, which contains:

• FSBL (First Stage Boot Loader)
• FPGA bitstream (if applicable)
• U-Boot bootloader

So, we need to package our petalinux project by using the command: petalinux-package --boot --fsbl ./images/linux/zynqmp_fsbl.elf --fpga ./images/linux/system.bit --u-boot

PackageSD Card Image

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 ZCU104 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 by using the comand: 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 we need to 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.

SDCard

The SD card having two partitions one if for root files and one is for boot files and will look like,

ZCU-104MPSoC DeviceBoardSettings

• Zynq UltraScale+ XCZU7EV MPSoC devices use a multi-stage boot process as described in the “Boot and Configuration” chapter of the Zynq UltraScale+ MPSoC Technical Reference.
• Switch SW6 configuration option settings are listed in table below.

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