Running Linux on the TE0802

In my previous project using the TE0802, I covered how to set up the base hardware design in Vivado and simple Hello World bare-metal application in a Vitis project. However in order to take full advantage of the power behind the TE0802 via its Zynq UltraScale+ MPSoC FPGA and peripherals such as Displayport and Gigabit Ethernet port, running Linux is an ideal option.

As mentioned in the previous project, the latest source files currently available for the TE0802 from Trenz are for Vivado/Vitis/PetaLinux version 2019.2. Since I've already covered the hardware design, this project will jump straight into building the embedded Linux image for the board using PetaLinux.

I've also attached the 2019.2 Trenz source file zip folder for the TE0802 to this project as I did in the previous project post.

New PetaLinux Project

To start, source the PetaLinux tools on your host PC:

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

Within the desired project directory (I like to do so within the top level Vivado project directory where I exported the XSA hardware file the PetaLinux project will be based on), create new a PetaLinux project. The template will be zynqMP since the TE0802 has a Zynq UltraScale+ MPSoC FPGA. Then also specify the desired name for the PetaLinux project. After the PetaLinux project has been generated, change directories into the project:

~$ petalinux-create --type project --template zynqMP --name te0802_os
~$ cd ./te0802_os/

Linux System Configuration

Once inside the new PetaLinux project, the XSA hardware file needs to be imported such that PetaLinux is aware of what hardware hooks are available to be built upon. The following command imports the XSA hardware file, reads it into the project, then launches the hardware system configuration ASCII GUI for the PetaLinux project:

~$ petalinux-config --get-hw-description ./<directory of .XSA exported from Vivado>

Edit the hardware system configuration in the Image Packaging Configuration tab to look for an external root filesystem stored in external memory, the rest of the settings can be left as their default parameters.

• Image Packaging Configuration --> Root filesystem type --> select EXT (SD/eMMC/QSPI/SATA/USB)

Linux Kernel

A few tweaks need to be made to the kernel for the TE0802, including adding NVMe support for the M.2 M-keyed PCIe slot and the device drivers for supporting communication with any SSDs you might plug into that PCIe slot.

Launch the kernel configuration ASCII GUI to edit it:

~$ petalinux-config -c kernel

And make the following changes:

• CPU Power Management --> CPU Idle --> disable CPU idle PM support
• CPU Power Management --> CPU Frequencyscaling --> disable CPU Frequencyscaling
• DeviceDrivers --> NVME Support --> enable NVM Express block device and NVMe Target Support
• DeviceDrivers --> enable Open-Channel SSD target support
• DeviceDrivers --> Open-Channel SSD target support --> enable Physical Block Device Open-Channel SSD target and PBlk Debug Support

After making all of the needed changes, build the kernel:

~$ petalinux-build -c kernel

Linux Device Tree

The device tree by default in a PetaLinux project really only contains the minimum required to boot-up and perform basic functionality. In order for the Linux kernel (and therefore root filesystem) to be able to see the rest of the peripherals available on the TE0802 board, their respective nodes each need to be added to the device tree in the PetaLinux project in system-user.dtsi file located in /<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/device-tree/files/

The already completed system-user.dtsi for the TE0802 is available in the source file zip folder from Trenz so I simply copied it overtop of the blank default system-user.dtsi in the PetaLinux project:

~$ cp /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi /<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/device-tree/files/

Linux Boot Loader

The default configuration of the Linux boot loader, u-boot, in a new PetaLinux project does need to be modified for the TE0802. You can either access the configuration ASCII GUI for it with the following command and make all of the modifications to it by hand:

~$ petalinux-config -c u-boot

Or you can simply include the new configuration by adding the devtool-fragment.cfg file from Trenz to the u-boot recipe in your PetaLinux project, which is what I chose to do.

The default platform-top.h file (located in /<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/u-boot/files/) is fine for the TE0802. But to add the devtool-fragment.cfg file and the modified bitbake to include it in the recipe for the next build, I again simply copied each file from the Trenz zip file overtop of the existing ones in my PetaLinux project:

~$ cp /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-bsp/u-boot/u-boot-xlnx_%.bbappend /<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/u-boot/

~$ cp /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-bsp/u-boot/files/devtool-fragment.cfg /<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/u-boot/files/

Root Filesystem

The root filesystem only needs a few packages added to it for the TE0802 to support audio, I2C, and a simple little web server application. Access the root filesystem configuration editor GUI with the following command:

~$ petalinux-config -c rootfs

And enable to the following packages:

Filesystem Packages:

• base --> i2c-tools --> enable i2c-tools
• base --> busybox --> enable busybox-httpd
• console --> utils --> alsa-utils --> enable alsa-utils and alsa-utils-aplay

PetaLinux Package Groups:

• Enable packagegroup-petalinux-utils

After enabling the above filesystem packages along with any other desired filesystem packages, you can also add two simple custom applications Trenz has developed for the TE0802.

The first of which is a simple webserver application that provides basic controls of the TE0802 board via a webpage (called webfwu), and the second application will look for and load an init.sh file from the SD card if one is available. Which means you can write your own startup script to be run at startup of the TE0802.

Create each of the applications and enable them in the PetaLinux project:

~$ petalinux-create -t apps --template c --name startup --enable
~$ petalinux-create -t apps --template c --name webfwu --enable

Copy over the bitbake file and source files from the Trenz source folder (test_board) for the webfwu application:

~$ cp /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-apps/webfwu/webfwu.bb /<PetaLinux project directory>/project-spec/meta-user/recipes-apps/webfwu/

~$ cp -R /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-apps/webfwu/files/* /<PetaLinux project directory>/project-spec/meta-user/recipes-apps/webfwu/files/

And build the app:

~$ petalinux-build -c webfwu

Then do the same for the startup application, copying over source files from the Trenz source folder (test_board):

~$ cp /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-apps/startup/startup.bb /<PetaLinux project directory>/project-spec/meta-user/recipes-apps/startup/

~$ cp -R /<extracted directory>/test_board/os/petalinux/project-spec/meta-user/recipes-apps/startup/files/* /<PetaLinux project directory>/project-spec/meta-user/recipes-apps/startup/files/

And then build it:

~$ petalinux-build -c startup

Finally, build the whole root filesystem:

~$ petalinux-build -c rootfs

Build PetaLinux Project

With all of the necessary files added and modifications made to the PetaLinux project for the TE0802, build the whole PetaLinux project:

~$ petalinux-build

Then package the boot binary image for it including the MPSoC first stage bootloader (FSBL), FPGA bitsteam, and Linux second stage bootloader (u-boot):

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

SD Card

Prepare a MircoSD card (at least an 8GB, class 10) by partitioning it with a FAT32 partition 500MB in size with 4MB of free space preceding it. Then make the rest of the SD card an EXT4 partition:

Creating mounting point folders on your host PC for each of the partitions on the SD card and mount them respectively. The first partition, the FAT32 partition, is where the boot up components of the Linux image will live, while the second partition, the EXT4 partition is where the root filesystem will live.

Copy over BOOT.BIN (the boot binary), image.ub (kernel image), and system.dtb (device tree) to the first partition and unzip rootfs.tar.gz into the second partition. Make sure everything has completed being transferred to the MicroSD card using the sync command before unmounting each partition:

~$ 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/system.dtb /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/

After unmounting the SD card from your host PC, install it into the TE0802 on the bottom side of the board.

Set TE0802 Boot Mode

The TE0802 has its boot mode set using a DIP switch (S1 on the board located next to the VGA port). To set the TE0802 to boot from the SD card, switches 1 and 2 need to be set to the ON position:

TE0802 First Linux Boot

O in a MicroUSB into the JTAG/UART of the TE0802 (J8), an ethernet cable into the Gigabit Ethernet port for a network connection, and finally plug in the wall wart barrel jack power supply:

Open the serial terminal application of your choice with a baudrate of 115200 to see the output of the boot process of the TE0802 and log into the command line:

The default username and password is the PetaLinux default of:

• username: root
• password: root

Once logged in, run the ifconfig command to see the IP address assigned to the TE0802. Type the local IP address into the browser of a host PC connected to the same network to see the webserver application running on the TE0802.

And that's it it for the base Linux image for the TE0802!