Create a Desktop Environment for the TE0802 Using PetaLinux

One of the main things that attracted me to the idea of installing Ubuntu on my Zynq FPGAs was the option of a desktop environment and the GUIs that could make my life easier for development on new projects. However, after fighting with attempting to install Ubuntu desktop on the ZynqMP of my TE0802 for longer than I'd like to admit (getting the drivers for the ZynqMP Mail GPU graphics installed/integrated into Ubuntu turned out to be beyond my capabilities), I discovered that there is a sneaky desktop environment option available in PetaLinux that can be configured. This desktop environment is akin to a bare bones Fedora distribution in that it is an RPM-based distribution that uses the DNF package manager.

In one of my previous project posts, I detailed exactly how to build and configure the base Linux image for the TE0802 in PetaLinux and the base hardware project that Linux image is built on top of in Vivado for the TE0802. This project starts with the Linux image in the PetaLinux project created by that project post: Running Linux on the TE0802. Again, I'm using PetaLinux version 2019.2 (which uses Linux kernel version 4.19) since the latest version of the board preset files for the TE0802 provided by Trenz are version 2019.2 at the time I am writing this tutorial.

Overall, I am starting with this basic Linux image for the TE0802 and adding the necessary kernel, device-tree, and root filesystem configurations for the resultant Linux image to boot up into a desktop environment accessible via the DisplayPort to a monitor, and also has keyboard and mouse support.

Update the Kernel

To get started with building this desktop Linux image in PetaLinux, start by editing the kernel to support a desktop environment:

~$ petalinux-config -c kernel

Most of the necessary kernel modules will be enabled by default, to verify them you can simply search for each by pressing the / key at any time when the kernel configuration ASCII GUI is open:

CONFIG_INPUT_EVDEV
CONFIG_INPUT_KEYBOARD
CONFIG_INPUT_MOUSE
CONFIG_INPUT_MOUSEDEV
CONFIG_USB_VIDEO_CLASS
CONFIG_MEDIA_CAMERA_SUPPORT
CONFIG_V4L_PLATFORM_DRIVERS
CONFIG_USB_STORAGE
CONFIG_USB_GADGET
CONFIG_HID_GENERIC
CONFIG_USB_HID
CONFIG_XILINX_DPDMA
CONFIG_SOUND
CONFIG_SND
CONFIG_SND_SOC
CONFIG_SND_SOC_XILINX_DP
CONFIG_CMA
CONFIG_DMA_CMA
CONFIG_CMA_SIZE_MBYTES=256
CONFIG_DRM_XLNX
CONFIG_DRM_XLNX_BRIDGE
CONFIG_DRM_XLNX_BRIDGE_DEBUG_FS
CONFIG_DRM_ZYNQMP_DPSU

I also added the resolution of my Dell D2520U monitor (2560x1440) to the Mouse interface section under Horizontal screen resolution and Vertical screen resolution to ensure the mouse cursor would be able to access my entire monitor's real-estate (under Device Drivers > Input device support).

Add Device Tree Node for DisplayPort

The default device tree provided by Trenz for the TE0802 does not include a node to make the ZynqMP DisplayPort subsystem visible to the kernel (but the DisplayPort is enabled in the hardware via the block design in Vivado). So after some trial and error, this is the device tree node that worked for me that I added to system-user.dtsi in the/<PetaLinux project directory>/project-spec/meta-user/recipes-bsp/device-tree/files/directory:

/* DisplayPort */
&zynqmp_dpsub {
	status = "okay";
	xlnx,vid-clk-pl;
	
	xlnx_dp_sub: zynqmp_dpsub@fd4a0000 {
		compatible = "xlnx,zynqmp-dpsub-1.7";
		reg = <0xfd4a0000 0x1000>, 
                      <0xfd4aa000 0x1000>, 
                      <0xfd4ab000 0x1000>, 
                      <0xfd4ac000 0x1000>;
		reg-names = "dp", "blend", "av_buf", "aud";
		xlnx,output-fmt = "rgb";

		xilinx_drm {
			compatible = "xlnx,drm";
			clocks = <&zynqmp_clk 16>;
			xlnx,connector-type = "DisplayPort";
			
			planes {
				xlnx,pixel-format = "rgb565";
				gfx-layer {
					dmas = <&xlnx_dpdma 3>;
					dma-names = "gfx0";
				};
				vid-layer {
					dmas = <&xlnx_dpdma 0>, 
                                               <&xlnx_dpdma 1>, 
                                               <&xlnx_dpdma 2>;
					dma-names = "vid0", "vid1", "vid2";
				};
			};
		};

		ports {
			port@0 {
				reg = <0>;

				dp_out: endpoint {
					remote-endpoint = <&dp_out>;
				};
			};
		};

	};
};

Configure Root Filesystem for Desktop Environment

Launch the root filesystem configuration editor to add the appropriate filesystem packages to the Linux image for a desktop environment:

~$ petalinux-config -c rootfs

The root filesystem configuration is the main focus of how a desktop environment is added to a Linux image. Specifically, the main elements that need to be added for a minimally functional desktop image is a package management system to allow for any necessary libraries/packages to be installed in the future, and the X window system - X11 with Matchbox windows manager which is the actual framework to support the desktop windows and subsequent application GUIs.

In Petalinux Package Groups, enable the following package groups:

• packagegroup-petalinux
• packagegroup-petalinux-audio
• packagegroup-petalinux-display-debug
• packagegroup-petalinux-matchbox
• packagegroup-petalinux-utils
• packagegroup-petalinux-v4lutils
• packagegroup-petalinux-x11
• packagegroup-petalinux-x11-dev

These package groups cover enabling the drivers for the X11 windows framework, along with the Matchbox windows manager, the Video4Linux drivers, display drivers, and base Linux image packages.

Then navigate to Filesystem Packages > libs and enable the following:

• libmali-xlnx
• libmali-xlnx-dev (mali-backend-defaults = x11)
• libx11
• libxdamage
• libxext
• libxfixes

These individual packages cover the drivers that are needed for the Mali GPU of the ZynqMP chip. The libmali-xlnx packages are the Mali GPU drivers themselves and the rest are the extra X11 supporting packages the Mali GPU drivers need that aren't included in packagegroup-petalinux-x11.

Finally, package management needs to be enabled for the Linux image, which is based on. Navigate to Image Features from the main menu in the root filesystem configuration editor and enable package-management. A new field will appear below it for package-feed-urls. This is where the links to the repositories for the DNF package manager commands to pull from are specified. In this case, since the TE0802 is a ZynqMP-based board, the best feed to use is http://petalinux.xilinx.com/sswreleases/rel-v2019/feeds/ultra96-zynqmp/ but if you want to implement this on a different board, check if a different feed makes more sense for you: http://petalinux.xilinx.com/sswreleases/rel-v2019/feeds/ (just be sure to match the right feed version to the version of PetaLinux you're using - I'm using the v2019 feed since I'm compiling this in PetaLinux 2019.2).

Build PetaLinux Project & Package Boot Binary

After making all of the necessary changes to the root filesystem, exit the configuration editor and select the option to save your changes. Then build PetaLinux project.

~$ petalinux-build

After a successful build, package a new boot binary for the Linux image. Note that I have to use the force flag since I've created boot binary images from past builds of this project.

~$ petalinux-package --boot --fsbl /<petalinux project dir>/images/linux/zynqmp_fsbl.elf --fpga /<petalinux project dir>/images/linux/system.bit --u-boot --force

Prep SD Card

This section entailing how to prep and load an SD card, I've covered quite a bit in the past, but I put it here for the sake of ease of reference:

If you haven't already, 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:

Create a mounting point for each of the partitions on the SD card (if you haven't done so in the past) and mount them respectively:

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

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

Copy over BOOT.BIN (the boot binary), image.ub (kernel image), and system.dtb (device tree) to the FAT32 partition:

~$ 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/

Extract the root filesystem tarball onto the EXT4 partition of the SD card:

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

Run the sync command to again ensure all file transfers to the SD card are complete and unmount both partitions:

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

Set TE0802 Boot Mode

As I've mentioned in previous projects using the TE0802, ensure the boot mode is set to boot from an SD card using the 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:

Insert the SD card into the slot on the bottom side of the TE0802, connect a MicroUSB to the JTAG/UART port (J8), and connect an Ethernet cable to the Gigabit Ethernet port for a network connection (either directly from a router or through Internet sharing from a PC). Also connect a DisplayPort cable between the DisplayPort on the TE0802 and the DisplayPort on a monitor. Try to stay away from using any adapters to covert to/from HDMI as they may not be compatible with the drivers for the ZynqMP DisplayPort subsystem. Finally, plug in the 5V/4A wall plug power supply to boot up the TE0802 board.

Verify Desktop Image

The UART will still print out the boot sequence that can be monitored using a serial terminal application (baud rate = 11520) and you can still log into the system from the command line.

However, now towards the end of the boot sequence, you'll see the desktop environment appear on the monitor. The super basic desktop environment includes a text editor, touchscreen calibration application, file manager GUI, a couple of audio control applications, a simple appearance theme changer application, and a terminal emulator.

To test the package manager, open either the terminal emulator from the desktop using a keyboard and mouse, or connect to the UART via a serial terminal from a host PC and run the DNF command to install something:

root@te0802_os:~# dnf install git

I installed git since I didn't include it in the original root file system configuration when I built the PetaLinux project. The repo I included in the PetaLinux project build is the same repo that the PetaLinux tools have access to, so you can install any filesystem packages now without having to rebuild your PetaLinux project and re-image the SD card.

However, you must keep in mind that if a package is not available in the root filesystem configuration editor, it also won't be available to the DNF command here. You'll need to add and configure external repositories to the DNF command the standard way you would on any other Linux distribution