Linux on Zynq: Arty-Z7 Linux Design in PetaLinux 2022.1

In my previous project post I walked through how to create a basic hardware design for the Arty-Z7, a Zynq-7000 FPGA development board. The Arty-Z7 is one of my favorite Zynq FPGA development boards as it is on the lower end of the price scale and the common peripheral headers such as the Arduino and PMOD connectors make it easy to develop hardware with.

This project walks through how to generate an embedded Linux image for the Arty-Z7 using the hardware design from my previous post using PetaLinux 2022.1 running on an Ubuntu 20.04 host machine.

Note: the following steps should also work in any PetaLinux version 2020.1 or later.

Create PetaLinux Project

For the sake of my future self, I like to create my PetaLinux projects in the top level directory of the corresponding Vivado project of the target hardware design. This keeps everything organized for me when my folder/project names don't make any sense to me like they did when I created them (please tell me I'm not the only one this happens to).

After navigating to the desired directory location to create the PetaLinux project in, source the PetaLinux tools to the environment.

~$ cd ./artyZ7_prj/
~/artyZ7_prj$ source /tools/Xilinx/PetaLinux/2022.1/settings.sh

Use the petalinux-create command to create a project, specifying the architecture (Zynq) and project name:

~/artyZ7_prj$ petalinux-create --type project --template zynq --name artyZ7_os
~/artyZ7_prj$ cd ./artyZ7_os

Once the project generates (the command line returns back), change directories into it.

Import Hardware from Vivado

Even though PetaLinux knows that the project is targeting the Zynq FPGA, it still needs the specific details of the target hardware. This is where the XSA exported from Vivado comes back into play. Use the petalinux-config command with the --get-hw-description flag pointed to the directory where the XSA file is located to import it into the project:

~/artyZ7_prj/artyZ7_os$ petalinux-config --get-hw-description ../

The petalinux-config command also launches the system configuration ASCII GUI. This is where hardware-related settings are specified such as which processor in the dual core ARM of the Zynq to target, where the root filesystem is located and type (in this case it's an EXT4 root filesystem on an SD card), etc.

Make the following changes in the menus (you can leave tftpboot enabled if you're going to use it, but I won't so I disabled it):

• Image Packaging Configuration -> Root filesystem type = EXT4 (SD/eMMC/SATA/USB)
• Image Packaging Configuration -> disable Copy final images to tftpboot

Exit the system configuration GUI, opting to save any changes.

Configure Kernel

To make changes to the kernel such as adding modules for hardware in the design, launch the kernel configuration GUI using the following command.

~/artyZ7_prj/artyZ7_os$ petalinux-config -c kernel

The default kernel configuration is all that's needed in my case just to create a base Linux image for the Arty-Z7 so I didn't make any changes to the kernel here.

Configure Root Filesystem

There is also a root filesystem configuration GUI that allows users to specify extra packages and libraries to be built into the root filesystem of the Linux image PetaLinux builds.

~/artyZ7_prj/artyZ7_os$ petalinux-config -c rootfs

In the root filesystem configuration GUI, there is the option to enable individual packages/libraries or enable package groups. The package groups enable a series of related packages/libraries to save the user some time (ie a Python package group enables Python, pip, etc.)

I like to enable the following package groups as I find that I use them the most.

• Petalinux Package Groups > packagegroup-petalinux > [*] packagegroup-petalinux
• Petalinux Package Groups > packagegroup-petalinux-audio > [*] packagegroup-petalinux-audio
• Petalinux Package Groups > packagegroup-petalinux-networking-stack > [*] packagegroup-petalinux-networking-stack
• Petalinux Package Groups > packagegroup-petalinux-python-modules > [*] packagegroup-petalinux-python-modules
• Petalinux Package Groups > packagegroup-petalinux-utils > [*] packagegroup-petalinux-utils
• Petalinux Package Groups > packagegroup-petalinux > [*] packagegroup-petalinux

Configure Device Tree

The device tree may or may not require a user to specify custom hardware nodes. This is done in the system-user.dtsi device tree source file located in /<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/device-tree/files. Editing other device tree files in the PetaLinux project may not work as some are auto-generated so and changes to them by a user would be overwritten.

Typically (but not always), peripherals connected to the Zynq MIO will have their device tree nodes automatically generated by PetaLinux. Anything connected to the Zynq via EMIO or AXI will require a user to write a device tree node for it in system-user.dtsi. Since everything I'm using is connected to the Zynq MIO in this case, I didn't need to add any custom nodes.

Configure U-Boot

While PetaLinux will mostly take care of the U-Boot configuration based on the settings specified in the system configuration editor, there still may be a need/desire to make further changes.

There is also an ASCII configuration GUI for U-Boot accessed in a similar way:

~/artyZ7_prj/artyZ7_os$ petalinux-config -c u-boot

This project will not cover any special U-Boot configuration however.

Build PetaLinux Project

With all desired modifications completed to the system, kernel, device tree, root filesystem, and U-Boot, it's time to build the project as a whole:

~/artyZ7_prj/artyZ7_os$ petalinux-build

There is also the option to build each component of the Linux image a la cart using the component flag and specifying the component:

~/artyZ7_prj/artyZ7_os$ petalinux-build -c u-boot
~/artyZ7_prj/artyZ7_os$ petalinux-build -c kernel
~/artyZ7_prj/artyZ7_os$ petalinux-build -c device-tree
~/artyZ7_prj/artyZ7_os$ petalinux-build -c rootfs

Note: by default, PetaLinux requires a stable internet connection to build a project. Users must manually configure the projectmanuallyto be built offline and point them to local repositories.

Package Boot Binary & WIC

Once the project is built, package boot binary (BOOT.BIN) file:

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

PetaLinux starting with version 2020.1 added a handy feature to package.wic image files to be able to flash SD cards with using programs like balenaEtcher.

Use the petalinux-package command with the --wic flag and specify the boot files to be placed in the FAT32 boot partition of the SD card, and the root filesystem to be placed in the EXT4 partition of the SD card:

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

The output boot files and root filesystem from the PetaLinux build are located in /<PetaLinux project directory>/images/linux. This is also where PetaLinux will place the generated.wic image file (titled petalinux-sdimage.wic).

Flash SD Card

Flash the SD card with imaging tool of choice:

Boot Linux on Arty-Z7

Place the SD card in the slot on the bottom site of the Arty-Z7, plug in an Ethernet cable with internet connection (either directly to your router or to a host PC configured for internet sharing), plug in a microUSB from your host PC (to get the serial terminal output from the Arty-Z7), and a barrel jack power supply.

It is worth noting that the Arty-Z7 only needs the external power supply for some peripherals and most Linux images. I got lucky and the Linux image I built with with project was able to run using the 5V power from the USB connection of the serial port. But just know that won't always be the case so it's worth having the barrel jack power supply for the Arty on hand.

The default settings requiring the password change at first boot can be changed to specify a custom one in the PetaLinux root filesystem configuration.

Double-check the internet connection with commands such as ifconfig and ping:

And that's it for getting a basic Linux image up and running on the Arty-Z7.