PetaLinux 2019.2 on Ultra96 Using BSP + Recipe Patch

Since my last project where I detailed how to create a hardware project and PetaLinux image for the Ultra96 V2 from scratch in Vivado/PetaLinux 2019.2, Avnet has released their 2019.2 version of the board support package (BSP) for the Ultra96. Since creating the entire hardware and software design for a board like the Ultra96 is not a trivial thing to do, especial for those just getting into the FPGA world, I figured it would be good to walk through the project creation for the Ultra96 using the BSP.

Note: The steps in this project are very specific to PetaLinux version 2019.2, if you are using a different version be aware that you will need the BSP specific to your version of PetaLinux and the project creation steps may also differ depending on the version of PetaLinux. The step involving updating the recipe file (.bb) for the Arduino toolchain package download is also only applicable to PetaLinux 2019.2.

To get started, download the BSP from Avnet here and extract the.bsp file from the.zip to a desired directory. Since BSPs include a bitstream for the hardware design, there is no need to do anything in Vivado. This is another reason it is a good for those who are new to the FPGA and/or Xilinx world to start with a BSP when creating new projects.

After the BSP is downloaded and extracted, run the script to source the PetaLinux environment and create a new project using the Ultra96 BSP. PetaLinux will create a new folder titled the same as the BSP file to populate the project in. Change directories into this folder after PetaLinux has generated the project.

source /<PetaLinux installation directory>/2019.2/settings.sh
petalinux-create -t project -s /<path to BSP file>/ultra96v2_oob_2019_2.bsp
cd ./ultra96v2_oob_2019_2

At this point the next step is to build the project using the following command:

petalinux-build

However, I ran into a build error that is an issue specific to PetaLinux version 2019.2. The recipe file (bitbake file -.bb) that tells PetaLinux where to download the Arduino toolchain from, was still pointing to the previous version of the Debian package for the toolchain which is no longer available. A ticket is currently open for this issue in Xilinx's GitHub repository for PetaLinux that you can read about here. Luckily though, I found that the fix was fairly straightforward. The error log output from PetaLinux told me which file had the outdated package link:

<PetaLinux_installation_directory>/2019.2/components/yocto/source/aarch64/layers/meta-petalinux/recipes-utils/arduino-toolchain/arduino-toolchain_1.0.bb

I looked up what the current Debian package version is at the same link from the recipe file:

http://http.us.debian.org/debian/pool/main/e/elfutils/

I found that the revision was very minor so the package name in the URL just needed a slight tweak and the hash values for the new package be updated in arduino-toolchain_1.0.bb.

Update line 10 of arduino-toolchain_1.0.bb to the following:

http://http.us.debian.org/debian/pool/main/e/elfutils/libelf1_0.176-1.1_arm64.deb;subdir=avrgcc;unpack=false;name=libelf1 \

Then update the hashes for the Debian package in lines 29 and 30:

SRC_URI[libelf1.md5sum] = "a9244703eec4735e54108001cee4c408" 
SRC_URI[libelf1.sha256sum] = "7c550a5eb057ec5c38f37e79eba476785e3a84097f7b740866db39012b99470f"

Once you've updated the arduino-toolchain_1.0.bb file, you're set. It's important to note that this is not a normal step in the PetaLinux project flow and is a one-time patch specific to PetaLinux version 2019.2.

With the arduino-toolchain_1.0.bb file patched, the project can be successfully built and the Ultra96 PetaLinux project folder will look like the following:

The kernel image, device tree blob, first stage boot loader (FSBL), and root file system for the Ultra96 are output to the <PetaLinux_project_directory>/images/linux folder.

The only thing that hasn't been generated is the boot image (BOOT.BIN). PetaLinux does not automatically generate the boot image since it does not always contain the same files within it depending on factors such as if the target FPGA board is being booted from an SD card or on board flash memory. For this particular configuration of the Ultra96 package the FSBL, kernel image, PMU firmware, and FPGA bitstream into the boot image:

petalinux-package --boot --fsbl ./images/linux/zynqmp_fsbl.elf --fpga ./images/linux/system.bit --pmufw ./images/linux/pmufw.elf --u-boot

Prepare an SD card that is at least 8GB by partitioning it with two main partitions: one 500MB fat32 with 4MB of free space proceeding it, and the rest of the SD card partitioned as an ext4 partition.

If you haven't previously, create mounting point folders for the different partitions of the SD card. One for the boot partition (fat32) and a second for the root filesystem partition (ext4):

sudo mkdir /media/BOOT/
sudo mkdir /media/rootfs/

Mount the SD card partitions to the appropriate mounting point folder:

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

Extract the root file system image to the ext4 partition and copy the kernel image, device tree, and boot image to the fat32 partition:

sudo tar -xvf /<petalinux project dir>/images/linux/rootfs.tar.gz -C /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/system.dtb /media/BOOT/

Finally, unmount the partitions of the SD card before unplugging it from your PC:

sudo umount /media/BOOT/
sudo umount /media/rootfs/

Plug in the Ultra96 USB-to-JTAG/UART pod and open your preferred serial terminal application. Two ports will show up, the second one is the UART console for the Ultra96 that you can use to log into the command line interface of the board.

Watch the boot process of the Ultra96 in the serial terminal and login with the username 'root' and password 'root'. At this point, the access point network will appear as an open Wi-Fi network that can be connected to.

Once connected to the Ultra96's wireless access point, open a browser window and type 192.168.2.1 in the address field. This will connect to the Ultra96's Python web server application. Click on the 'Wifi Setup' link to select a Wi-Fi network to connect the Ultra96 to the internet. The drivers for the Ultra96's Wi-Fi chip (the Microchip ATWILC3000 Wi-Fi+Bluetooth radio module) currently do not support connecting to a wireless network with a space in the SSID. It's not good practice to have spaces in the name of your Wi-Fi network anyways, so this is a good time to change it if necessary.

Once the Ultra96 has been connected to an external network, the wireless access point at 192.168.2.1 will no longer work. Return to the serial terminal to check what IP address the wireless network's router has assigned to the Ultra96 via DHCP. I personally still use ifconfig to assign a static IP for stability purposes:

ifconfig wlan0 192.168.1.19 netmask 255.255.255.0

Use this new IP address while connected to same network as the Ultra96 to reconnect to its web application:

I have updated the project repository from my previous Ultra96 project that I built from scratch to include the BSP and this project built from the BSP.