Getting Started with the Arty Z7 in PetaLinux 2020.2

For this project tutorial, I will be walking through the process of creating an embedded Linux image for the Arty Z7 board using PetaLinux v2020.2

Create PetaLinux Project

Start by sourcing the PetaLinux tools to your environment:

~$ source /<PetaLinux install directory>/2020.2/settings.sh

Create/change directories into the desired path for the PetaLinux project, then run the following command to create the PetaLinux project:

~$ petalinux-create --type project --template zynq --name artyz7_os

Of course the type we're creating is a project, and the template is zynq since the Arty Z7 is based on a Zynq-7000 series FPGA. The name of the project can be whatever you want within the character restrictions (such as no slashes, special characters, etc.).

After the PetaLinux project is generated, it is placed in a folder titled the name you passed in the petalinux-create command, so you'll need to change directories into it to start configuring it.

~$ cd ./artyz7_os

Configure Hardware

First, the PetaLinux project must be initialized with the hardware design created in Vivado for the Arty Z7 board. The hardware design is contained in the XSA file generated by selecting File > Export > Export Hardware... and selecting the option to Include bitstream in Vivado.

To initialize the PetaLinux project with the Vivado hardware design, use the --get-hw-description option and specify the directory that the XSA file is located in (pass only the directory, not the XSA file itself).

~$ petalinux-config --get-hw-description /<directory of .XSA file>/

This command pulls the hardware design into the PetaLinux project and launches the System configuration GUI for you to specify hardware configurations such as the target UART port to be used, the root filesystem type and where it will be stored, the target ARM core processor within the Zynq chip, and so on.

If you make any changes to the hardware design in Vivado, you'll need to re-export it and run the same command as above to import the changes into the PetaLinux project. Otherwise, if you only need to make system configuration changes within the PetaLinux project and the XSA file has not been modified, you can simply access the System configuration GUI with the following command:

~$ petalinux-config

Since the hardware was imported from a Vivado project configured for the Arty Z7 specifically, most of the settings are already configured by default such as the Image Packaging Configuration. This section controls which physical medium the Linux image expects to boot from. In the case of the Arty Z7, the embedded Linux image will live

Configure Kernel

The Linux kernel is the set of drivers responsible for managing the hardware resources for the root filesystem. For example, if multiple applications need to access the UART port, the kernel plays a huge role in controlling and coordinating specifically when each of the applications access that UART port.

By default, a new PetaLinux project is configured with the bare minimum kernel drivers required to boot up and perform very basic functions. If your project requires any extra drivers for something like a Wi-Fi dongle, you can enable/add those drivers through the ASCII GUI for the kernel which is accessible via the following command:

~$ petalinux-config -c kernel

Configure Root Filesystem

Just like with the kernel, the root filesystem is configured with the bare minimum packages and applications for booting and performing basic functionalities. If any other packages are needed for your applications, they can be added via the ASCII GUI for the root filesystem accessible via the following command:

~$ petalinux-config -c rootfs

Build PetaLinux Project

Once the root filesystem, kernel, and system are configured as desired, build the PetaLinux project which will take all of these Yocto settings/configurations to build the embedded Linux image for the Arty Z7:

~$ petalinux-build

If you made any changes to the kernel (or even just opened the kernel configuration GUI), you might need a warning about the kernel being tainted from a forced run. For the most part, this warning is benign and can be ignored.

Patch (if needed)

If the build fails with some sort of error such as NO_BB_NETWORK, networking error, or mirror error, add the following line to /<PetaLinux project directory>/project-spec/meta-user/conf/petalinuxbsp.conf after line 3:

PREMIRRORS_prepend = "gitsm://.*/.* file:///opt/petalinux/data/downloads_2020.2 \n "

I'm running Ubuntu 18.04.5, which is technically not a supported OS by PetaLinux version 2020.2 (officially supported versions of Ubuntu are 18.04.1, 18.04.2, 18.04.3, and 18.04.4) so I'm sure that's why I got this error. However, I did notice on Xilinx's forum that others where getting this error when trying to build a PetaLinux 2020.2 project with no internet connection, so I thought this patch was worth mentioning in this write-up.

Rebuild the PetaLinux project after saving the modifications to this file.

Package Boot Binary

Once the PetaLinux project is successfully built, the u-boot bootloader needs to be compiled into the binary package BOOT.BIN which is the instruction set that tells the device how to boot the kernel for the embedded Linux operating system. For this particular PetaLinux project, and for the majority of PetaLinux projects, all's that is needed to be packaged into the boot binary is the Zynq's first stage bootloader, the bitstream for configuring the programmable logic of the Zynq FPGA, and the general Linux u-boot bootloader (which is the secondary bootloader in this particular context).

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

Load SD Card

To prepare the SD card for loading the embedded Linux onto it, it needs to have two main partitions on it. A FAT32 partition that is at least 500MB with 4MB of free space preceding it is the first partition needed. This is the partition where all of the files related to the boot process will live such as the boot binary image and the kernel. The second partition needed is a EXT4 partition at least 4GB in size, as you can probably guess from the initial steps from the system configuration GUI, this is the partition where the root filesystem will live. I usually just configure the rest of the free space after the FAT32 partition on the SD card as the EXT4 partition. This allows for me to install new packages with the Linux package manager once it is connected to the internet.

I like using Gparted for configuring the partitions on SD cards, but you can also do everything from the command line.

After the SD card is properly partitioned, load it with the Linux image created by the PetaLinux project.

If you haven't already, start by making a mounting point folder for each of the two partitions then mount each of the partitions to their respective mounting folders.

All of the Linux image files from the PetaLinux project needed for the SD card, are located in the /<PetaLinux project directory>/images/linux/ directory, which appears after a successful build of the project is executed.

The boot files can simply be copied to the FAT32 partition, but the root filesystem needs to be extracted using a command like tar onto the EXT4 partition. Once all of the files are placed in the proper partitions, use the sync command to ensure the transfers are properly completed and the SD card can be safely unmounted from the host machine.

After the sync command has completed, unmount each of the two partitions before removing the SD card.

~$ mkdir /media/BOOT
~$ mkdir /media/rootfs

~$ sudo mount /dev/sdc1 /media/BOOT
~$ sudo mount /dev/sdc2 /media/rootfs

~$ sudo cp /<petalinux project dir>/images/linux/BOOT.BIN /media/BOOT/
~$ sudo cp /<petalinux project dir>/images/linux/image.ub /media/BOOT/
~$ sudo cp /<petalinux project dir>/images/linux/boot.scr /media/BOOT/

~$ sudo tar xvf /<petalinux project dir>/images/linux/rootfs.tar.gz -C /media/rootfs/

~$ sync

~$ sudo umount /media/BOOT/
~$ sudo umount /media/rootfs/

If you are re-imaging the SD card, be sure to remove the previous files from each partition prior to copying over the new ones. I've found that simply overwriting the files can cause weird things to happen, especially on the EXT4 partition with the root filesystem.

~$ sudo rm -rfv /media/BOOT/
~$ sudo rm -rfv /media/rootfs/

Boot Arty Board

To boot the Arty Z7, some hardware configuration needs to be done. Start by switching the jumper JP4 to SD to tell the Zynq chip to look to the SD card for the bootloaders, kernel, filesystem, etc.:

Install the SD card into its slot (J9) on the bottom side of the Arty board:

Plug the 12V power adapter for the Arty into the barrel jack port J18, and a micro-USB cable to the JTAG/UART USB host port J14:

Open your serial terminal application of choice with a baud rate setting of 115200, and watch the boot process. Once the login option appears, the username login is root and the password is also root, unless it was changed in the root filesystem configuration GUI from the previous steps.

And that's it for the basics of building an embedded Linux image in PetaLinux 2020.2!