Setting Up the PetaLinux Environment

Introduction to PetaLinux

PetaLinux is an embedded Linux development toolkit launched by Xilinx (now under AMD), specifically designed for its FPGAs (such as Zynq, Zynq UltraScale+ MPSoC, MicroBlaze, etc.) and adaptive SoCs. It is built based on the Yocto Project and provides a complete toolchain that simplifies the development, customization, and deployment process of embedded Linux systems. PetaLinux is not a special Linux kernel but rather a set of tools for configuring the development environment, reducing the workload of configuring U-Boot, the kernel, and the root filesystem. It can automatically configure related software based on the hardware information exported from Vivado.

PetaLinux Installation Steps

Here, we choose to install PetaLinux on Ubuntu 20.04.6. Since the host machine uses Windows, we opt to install a Ubuntu 20.04.6 virtual machine after installing VirtualBox. You can also install Ubuntu via VMware. For specific instructions on how to install Ubuntu on VirtualBox or VMware, please search for relevant information online.

After installing the Ubuntu system, the following operations need to be performed.

• Install dependency libraries

​x
sudo apt-get install -y python tofrodos iproute2 gawk xvfb gcc git make net-tools libncurses5-dev tftpd zlib1g-dev libssl-dev flex bison libselinux1 gnupg wget diffstat chrpath socat xterm autoconf libtool tar unzip texinfo zlib1g-dev gcc-multilib build-essential libsdl1.2-dev libglib2.0-dev zlib1g:i386 screen pax gzip

• PetaLinux uses the bash interpreter by default. Check the Ubuntu interpreter:

xxxxxxxxxx
ls -l /bin/sh

If the interpreter type matches, proceed. If not, use the following command to change dash to bash:

xxxxxxxxxx
sudo dpkg-reconfigure dash

In the pop-up dialog box, click "NO".

• The /opt directory can only create folders under the root account, so an additional line of code is needed to switch to administrator identity:

xxxxxxxxxx
su
sudo chown -R user:user /opt
Replace user:user with the ordinary Ubuntu account name, which is "mind" in my case.

• Create a folder for downloading PetaLinux. Here, it is created under /opt/pkg/petalinux. Modify the folder permissions:

xxxxxxxxxx
root@Ubuntu20:/media/sf_vmshare# mkdir -p /opt/pkg/petalinux/2021.1
root@Ubuntu20:/media/sf_vmshare# sudo chown -R mind:mind /opt

• Since PetaLinux cannot be installed under the root account and must be installed under an ordinary user account, exit administrator mode and enter ordinary user mode to download (for the 2021 version, you must include -d in the command):

xxxxxxxxxx
mind@Ubuntu20:/media/sf_vmshare$ ./petalinux-v2021.1-final-installer.run -d /opt/pkg/petalinux/2021.1

After this, the system will start installing PetaLinux. When you see the message "Press Enter to display the license agreements", press Enter to continue. Then, three license agreements will appear. Press Q to exit, then press Y and Enter to continue. The system will then begin installing PetaLinux.

• Enter the following command to load the PetaLinux environment. This command only applies to the current terminal.

xxxxxxxxxx
source /opt/pkg/petalinux/2021.1/settings.sh

The following output will appear:

xxxxxxxxxx
PetaLinux environment set to '/opt/pkg/petalinux/2021.1'
WARNING: This is not a supported OS
INFO: Checking free disk space
INFO: Checking installed tools
INFO: Checking installed development libraries
INFO: Checking network and other services

You can write this to the system environment variables:

xxxxxxxxxx
vi ~/.bashrc

#Method 1: Write the following content into .bashrc. However, this method will output a message every time a terminal is opened.
source source /opt/pkg/petalinux/2021.1/settings.sh
#Method 2: Write the following content into .bashrc. If you need to enable the environment variables when opening a new terminal, you can directly enter "speta".
alias speta='source /opt/pkg/petalinux/2021.1/settings.sh'

• Then press echo $PETALINUX:

xxxxxxxxxx
echo $PETALINUX

If the PetaLinux installation directory is displayed, it indicates that the working environment has been set up and is running properly.

Configuring the Petalinux Project

Exporting Hardware Project Information from Vivado to Obtain .xsa File

• Create a Vivado project

• Compile the project

• Export hardware to obtain .xsa

• If the xsa file is generated in a Windows system, it can be copied to the Ubuntu system via a shared folder in VirtualBox or VMware

Related Commands Required for the Petalinux Project

• Under the user directory, create a folder:

xxxxxxxxxx
mkdir petalinux_projects

• Enter this folder and create a project directory:

xxxxxxxxxx
cd petalinux_projects
#Create a Petalinux project
petalinux-create -t project --template zynq --name petalinux-mind

• Copy the xsa file to the project directory:

• Before configuring, load the Petalinux environment. If the Petalinux environment is automatically loaded, this step can be skipped:

xxxxxxxxxx
source /opt/pkg/petalinux/2021.1/settings.sh
#If environment variables are already set, directly enter speta
speta

• Enter the working directory and import hardware information for configuration:

xxxxxxxxxx
cd petalinux-mind
# petalinux-config --get-hw-description <xsa file directory>
petalinux-config --get-hw-description=./system_wrapper.xsa

This will pop up a character-based graphical interface for related configurations, which will be explained later.

• If you want to separately configure the device tree, u-boot, kernel, rootfs, or busybox later, you can use the following corresponding commands:

xxxxxxxxxx
petalinux-config -c device-tree
petalinux-config -c u-boot
petalinux-config -c kernel
petalinux-config -c rootfs
petalinux-config -c busybox

• Compilation and clean operations

xxxxxxxxxx
# Method 1: Compile the entire project (u-boot/kernel/device-tree/rootfs/fsbl/bitfile)
#Compile device tree, kernel, u-boot, etc., all at once
petalinux-build
# Method 2: Compile as needed
petalinux-build -c u-boot
petalinux-build -c kernel
petalinux-build -c rootfs
# If it is not the first time compiling the device tree, even if the device tree is modified, executing petalinux-build -c device-tree will not generate a dtb file. In this case, first execute petalinux-build -c device-tree -x cleansstate to clean the compilation state, then compile the device tree.


# clean
# remove the <PROJECT>/build/linux/u-boot/ directory
petalinux-build -c u-boot -x distclean 
# remove the <PROJECT>/build/ directory
petalinux-build -x distclean
#remove <PROJECT>/images/ and <PROJECT>/build/ directories
petalinux-build -x mrproper

• Packaging: Generate BOOT.BIN file

xxxxxxxxxx
# --fsbl: If not specified, defaults to images/linux/zynq_fsbl.elf 
# --u-boot: If not specified, defaults to images/linux/u-boot.elf
# --fpga: If not specified, defaults to images/linux/system.bit   "--fpga" means synthesizing the bit file into BOOT.bin

# Only package u-boot/fsbl/bit files into the BOOT.bin file
petalinux-package --boot --fsbl ./images/linux/zynq_fsbl.elf --u-boot --fpga --force

# Also package the kernel into BOOT.bin
petalinux-package --boot --fsbl ./images/linux/zynq_fsbl.elf --u-boot --fpga --kernel --force

Petalinux Project Configuration Interface

Executing the petalinux-config --get-hw-description command will pop up a window where you can configure the Petalinux project. If it has already been configured and you want to configure it again later, you can run the command "petalinux-config" to configure it.

Use the "↑" and "↓" keys on the keyboard to select the menu to configure, and press the "Enter" key to enter the submenu. The blue highlighted first letter in the menu is the hotkey for that menu; pressing the key corresponding to that highlighted letter on the keyboard will quickly select the corresponding menu. After selecting a submenu, pressing the "Y" key will write the corresponding configuration option to the configuration file, and the menu prefix will change to "< * >". Pressing the "N" key will not compile the corresponding code, and pressing the "M" key will compile the corresponding code as a module, with the menu prefix changing to "< M >". Press the "Esc" key twice to exit, i.e., return to the previous level. Press the "?" key to view help information for this menu. Press the "/" key to open the search box, where you can enter the content to search for. At the bottom of the configuration interface, there are five buttons. The functions of these five buttons are as follows:

xxxxxxxxxx
<Select>: Select button, same function as the "Enter" key, responsible for selecting and entering a menu.
<Exit>: Exit button, same function as pressing the "Esc" key twice, exits the current menu and returns to the previous level.
<Help>: Help button, views help information for the selected menu.
<Save>: Save button, saves the modified configuration file.
<Load>: Load button, loads the specified configuration file.

A brief introduction to these menus from top to bottom:

• "Linux Components Selection":

  The submenu content is as shown below:

  

  The "*" in the brackets indicates that the configuration is enabled. The second and third items indicate that the fsbl.elf file used in the experiment will be automatically generated and ps_init will be automatically updated. The following two options are used to configure the source of u-boot and linux-kernel.

• "Auto Config Settings":

  Mainly involves choosing whether to enable automatic configuration for Device tree, Kernel, and u-boot. The default configuration is used here, and no changes are needed.

• "Subsystem AUTO Hardware Settings":

  The content of the submenu is as shown below:

  

  Entering the various peripheral submenus in this interface, you can find that the default configurations have already been set. These default configurations are automatically configured based on the information in the xsa file and basically do not require manual configuration. The "Serial Settings" configuration item is used to configure the debug serial port and baud rate parameters of the development board.

  Change the default "ps7_uart_1" used in both "FSBL Serial stdin/stdout" and "DTG Serial stdin/stdout" to "ps7_uart_0", which is the USB serial port. This is because uart1 is an interface on the PL side. After making the changes, press the ESC key twice to return to the previous menu.

• "DTG Settings", the FSBL configuration menu "FSBL Configuration", the FPGA manager menu "FPGA Manager", the u-boot configuration menu "u-boot Configuration", and the linux configuration menu "Linux Configuration" can generally be left at their defaults.

• "Image Packaging Configuration":

  The submenu is as follows:

  

  The first option is the configuration of the root filesystem type, which defaults to INITRD and can generally be left as default. If we need to run Ubuntu or Debian root filesystems, it needs to be configured as EXT4 (SD/eMMC/SATA/USB). For NFS mount boot, it needs to be configured as NFS.

• "Firmware Version Configuration":

  Can be used to modify the hostname and product name of the customized linux system. It defaults to the same name as the Petalinux project and can be modified if needed.

• "Yocto Settings":

  Performs settings related to Yocto, which will not be introduced here. It can generally be left at its default.

u-boot and Linux Kernel

In the Linux Components Selection option, you can configure the source of u-boot and the Linux kernel. Press the Enter key to enter the next selection interface. u-boot and the Linux kernel are downloaded from GitHub by default, requiring the Linux host to be connected to the internet to download. This experiment has downloaded the corresponding resources locally. Download links: linux-xlnx, uboot-xlnx

Note: ① Be sure to use the version corresponding to petalinux; we are using petalinux2021.1 version. ② If multiple petalinux projects need to use local source code, each petalinux project must have its own corresponding kernel source code and u-boot source code. Otherwise, if one petalinux project modifies the source code, it will affect other projects.

Copy the kernel source code to the virtual machine and extract it. Here we choose to extract it to /home/mind/petalinux_downloads (you need to create the petalinux_downloads folder first).

Change the source of the Linux kernel/u-boot to local acquisition and configure the address of the downloaded offline package after extraction:

Select Linnux Components Selection --> u-boot --> ext-local-src

Linnux Components Selection --> linux-kernel --> ext-local-src

After selection, two additional options will appear: External u-boot local source settings --->

External u-boot local source settings --->

Select these two items, fill in the corresponding addresses, save, and exit.

Setting Up Offline Compilation

The Petalinux compilation project requires downloading some resources online by default. If the network is poor, compilation can be very slow or even fail. To solve this problem, we can pre-download two offline resource packages and then set up Petalinux for offline compilation. At this point, the u-boot and Linux resource packages have been downloaded from GitHub. We still need to download downloads, ssate:

Note: Be sure to download the files corresponding to the Petalinux version. We are using Petalinux version 2021.1, so we need to find these two files under the 2021.1 label to download.

Select the Petalinux tool arm- sstate-cache:

Copy the downloaded compressed packages to the virtual machine and extract them. Here we choose to extract them to /home/mind/petalinux-downloads:

Select the bottom option "Yocto Settings —>":

In the "Yocto Settings —>" interface, deselect "Enable Network sstate feeds" and select "Enable BB NO NETWORK". Because we have already downloaded the required packages locally, there is no need to connect to the internet during compilation, which can shorten the compilation time.

Note: Even if offline compilation is set up, the Ubuntu system must be able to connect to the network when building the project, as Petalinux needs to download some source code from GitHub.

Set the path for the "sstate_aarch64" package. Select the "Local sstate feeds settings —>" option on this page and configure the path where the corresponding extracted files are located.

Set the path for the "downloads" package. First select the < Exit > option to return to the interface shown below, then select the "Add pre-mirror url —>" option: file:/// must be added before this path.

Changing the Filesystem Type

On the initial page, select Image Packaging Configuration ---->

The first option is the configuration of the root filesystem type, which defaults to INITRD and can generally be left as default. If we need to run Ubuntu or Debian root filesystems, it needs to be configured as EXT4 (SD/eMMC/SATA/USB). For NFS mount boot, it needs to be configured as NFS. Here it is set to EXT4.

Note: The INITRD type root filesystem is completely new and unmodified every time the Linux system is restarted. This means that all modifications made after starting the system are lost after power-off, and the system will restart with the previous unmodified root filesystem. Choosing "EXT4" allows the root filesystem to be placed on an ext4 partition of an SD card or eMMC, so all modifications made after starting the system will not be lost after power-off.

"Copy final images to tftpboot" option: When a folder named tftpboot is created in the Ubuntu root directory, the project will automatically copy the relevant files to the /tftpboot directory after generating the image.

Finally, click Save, Exit.

Burning the Image to the TF Card

After configuring the Petalinux project and executing the following commands, the kernel image and file system will be generated:

xxxxxxxxxx
petalinux-build
petalinux-package --boot --fsbl ./images/linux/zynq_fsbl.elf --u-boot --fpga --force

At this point, the following files are generated in the image/linux directory: BOOT.bin, boot.scr, image.ub, and rootfs.tar.gz. Next, the kernel image and file system need to be saved to the TF card.

Insert the TF card. At this time, you can check and select the connection location of the TF card at the bottom right corner of the virtual machine:

• Format the TF card. You can use the Disks software on the Ubuntu system to format the TF card: Two partitions need to be created, one is a FAT32 partition (for storing boot.bin, boot.scr, and image.ub files), and the other is an ext4 partition (for storing the file system).

xxxxxxxxxx
umount /dev/sdb1
sudo fdisk /dev/sdb

• Create the first partition: FAT32 partition

Type "p" to see the current partition status.

Type "d" to delete a partition. If there are multiple partitions, you need to type "d" multiple times.

Type "p" again to see the current partition status. If the current partition is not a DOS partition, type "o" to change it to DOS.

Type "n" to create a partition. Type "p", then enter "1", "2048", and "+200M" in sequence.

Type "t" to set the partition type, then type "c" to set the type to "W95 FAT32 LBA".

Type "a" to set the partition as the boot partition.

• Create the second partition: EXT4 partition

Use the "n" command to allocate all remaining space to the second partition. Just press Enter directly.

• Check the partitions

Type "p" to check if there are two partitions. If everything is correct, type "w" to write the partition table to the TF card.

• Format the partition table

xxxxxxxxxx
# Format the first partition as FAT32 and name it boot
# Format the second partition as ext4 and name it rootfs
sudo mkfs.vfat -F 32 -n boot /dev/sdb1
sudo mkfs.ext4 -L rootfs /dev/sdb2

• Copy BOOT.BIN, boot.scr, and image.ub from the project directory images -> linux to the FAT partition of the SD card.

• Extract the ./image/rootfs.tar.gz file to the second partition

xxxxxxxxxx
sudo tar -xzf ./images/linux/rootfs.tar.gz -C /media/mind/rootfs/
sync

• Unmount the TF card

• Insert the TF card into the board, set the jumper cap to TF card boot mode, connect the board to the serial port, and power on.

Creating and Using BSP Packages

Using Petalinux BSP packages, we can conveniently and quickly provide our verified Petalinux projects to others or use others' verified Petalinux projects. You only need to master two commands for creating and using BSP packages.

• Create a BSP package

Use the following command to create a BSP package for the Petalinux project in the current terminal path:

x
cd petalinux-mind
petalinux-package --bsp -p ./ --output petalinux-mind.bsp

# The path after the -p parameter is the top-level path of the Petalinux project
# The name after the –output parameter is the name of the BSP package

• Use a BSP package

Use the following command to create a Petalinux project using the BSP package in the current terminal path:

x
petalinux-create -t project -n new_project -s ./petalinux-mind.bsp

# The name after the -n parameter is the name of the Petalinux project
# The path after the -s parameter is the path of the BSP package we are using

Note: If the project used to create the BSP package can be compiled successfully, then the project created using the BSP package can also be compiled directly.