Getting Started with Certified Ubuntu 20.04 LTS for Xilinx Devices

The Xilinx Certified Ubuntu 20.04 LTS for Xilinx Devices image is an official Ubuntu image with certified hardware support for select Xilinx evaluation boards. This page details how to boot and use the official desktop environment image released by Canonical for Xilinx ZCU102, ZCU104, and ZCU106 evaluation boards. You can read more about certified Ubuntu hardware here.

Table of Contents

Hardware and Software Requirements

 

SD Card

Networking

USB Peripherals

Miscellaneous

 

SD Card

Networking

USB Peripherals

Miscellaneous

ZCU102 (Rev 1.0+)

8GB+ SD Card

Wired Ethernet cable (100Mbps+) required to download updates and additional reference designs

Micro USB-A to USB-A Adapter, (Optional) USB hub for peripherals (ex: keyboard, mouse)

A DisplayPort cable and monitor may be used for a graphical desktop experience. Else, connect via USB UART terminal or SSH.

If DisplayPort Monitor is not available, please see the DisplayPort to HDMI Adapters section below for compatible adapters.

ZCU104 (Rev 1.0+)

8GB+ Micro SD Card

(Optional) USB hub for peripherals (ex: keyboard, mouse)

ZCU106 (Rev 1.0+)

8GB+ SD Card

(Optional) USB hub for peripherals (ex: keyboard, mouse)

Note: The ZCU104 & ZCU106 VCU ROI TRD demonstrations additionally require the following accessories: HDMI monitor, HDMI source device (ex: DVD player), and HDMI cables. HDMI is not used on the ZCU102 design.

Installing the Image

Once you have downloaded the Certified Ubuntu for Xilinx Devices image fromhttp://ubuntu.com/download/xilinx , you can write it to your SD card using any disk writing tool such as Balena Etcher, Win32 Disk Imager, or dd.

The screenshots below show how to write the disk image with Win32 Disk Imager.

For Linux & Mac Users, you can follow the instructions here: https://ubuntu.com/download/iot/installation-media

After opening Win32 Disk Imager, ensure the correct SD card drive is selected in (1) and then used the folder button (2) to locate the disk image.

The final disk image name may be different for you. Make sure that you are using the disk image that you downloaded.

After selecting the disk image, click the Write button to write the disk image to the SD card. The process will take approximately 10 minutes depending on the speed of your SD card and card reader.

First Boot and Getting Started

Before powering on the board, make sure all of the cables and peripherals are attached. At a minimum, attach the following:

  • ZCU10x Power Adapter

  • USB UART cable

  • (Micro) SD Card

For the best experience, additionally connect the following:

  • DisplayPort Monitor

  • USB Keyboard & Mouse (may be attached via USB hub)

  • Ethernet networking (with Internet access)

For detailed information about preparing each of three evaluation boards for booting from the SD card, please refer to the following links:

For general information about how the boot process works for this image, please refer to https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2036826124

NOTE: There are important differences for using the Certified Ubuntu on Xilinx Devices release on the ZCU104 board. Please see the Special Considerations for the ZCU104 Evaluation Board section.

Logging in via the Terminal

If you choose to boot without the optional accessories, you can monitor the boot process via the USB UART terminal output. Once you see the zynqmp login: prompt you can log into the system.

The default Ubuntu 20.04 LTS terminal login prompt

The default login credentials are:

username: ubuntu

password: ubuntu

The standard system policy requires you to change the password after the first time you log in with the default credentials.

If you login very quickly the first boot, you may find that the password does not have to be changed. In this case, you will be required to update it the next time you login or use sudo.

The default Ubuntu 20.04 LTS terminal

 

Logging in via the Graphical Desktop

If you are using the graphical interface via a monitor, the login process is similar:

the default Ubuntu 20.04 LTS login greeter screen
the default Ubuntu 20.04 LTS GNOME 3 desktop

Note: All systems using the Certified Ubuntu for Xilinx Devices image will initially boot with the graphical resolution of 1920x1080. 4K (3840x2160 or higher) resolutions are possible but Xilinx recommends using the 1920x1080 resolution for the most robust desktop experience.

The Ubuntu Desktop configuration used for this image is ubuntu-desktop-minimal. This configuration does not include Ubuntu Software by default. While you can always install Debian packages and snaps from the command line, if you would like to install the Ubuntu Software application, you can run the following command in a terminal:

1 sudo snap install snap-store

Network Setup

The instructions below assume the system is connected to the Internet. If your system is not connected to the Internet please connect the Ethernet cable and configure the system for Internet access before continuing.

If your network is configured with a DHCP server, the Certified Ubuntu for Xilinx Devices system will automatically obtain an IP address. If a static address is required,  you can use the ip command from the command line to configure the network interface. For more information, please see https://ubuntu.com/server/docs/network-configuration

For those users that prefer to use the ifconfig tools to configure your network interface, you can install the net-tools package. These tools are no longer included as part of the standard Ubuntu 20.04 root filesystem. To install them, you can use the following command:
$sudo apt install net-tools

If you are using the Gnome 3 graphical interface, you can configure networking via the Network Settings options in the GUI.

The GNOME 3 Network Settings GUI

Set up the Xilinx Development & Demonstration Environment for Ubuntu 20.04 LTS

This step requires Internet access. If you haven’t already set up Internet access, please follow the instructions in the Network Setup section above

Before diving into the demos, the Certified Ubuntu on Xilinx Devices environment needs to have some additional resources downloaded and installed. The primary utility for switching between configurations and managing the system is called xlnx-config. The xlnx-config utility is deployed as a Snapcraft-compatible snap.

  • Install the custom Xilinx gstreamer

  • Downloads a Vitis AI Model

To install the xlnx-config snap, execute the following command from a terminal: 

1 $ sudo snap install xlnx-config --classic

After installing the xlnx-config snap, you can use it to set up the remainder of the system by executing the following command in a terminal:

1 $ xlnx-config.sysinit

NOTE: The Xilinx team updates the xlnx-config snap with new features over time. It is important to keep it up-to-date.

The heart of the Xilinx demonstrations is the Xilinx Deep Learning Processing Unit (DPU). In addition to setting up the system, the xlnx-config snap provides the DPU via dpu.xclbin to other snaps that depend on it. The xlnx-config snap also provides infrastructure which allows users to package up other hardware platforms to enable other custom development and demonstration workflows.  For more information about installing custom demonstration platforms via xlnx-config, see the Overview of the Out-of-the-Box Demos section.

Install the Custom Xilinx gstreamer

By default, the Ubuntu 20.04 LTS root filesystem includes the open source upstream version of gstreamer that is packaged with Ubuntu 20.04 LTS. In order to take advantage of the unique features provided by Xilinx multimedia IP, xlnx-config.sysinit installs a customized Xilinx-specific version of gstreamer with specialized extensions and plugins. 

Download a Vitis AI Model

During xlnx-config.sysinit, the densebox_640_360 model is downloaded from the Xilinx Model Zoo to facilitate running of the VCU ROI TRD Demo.  

Overview of the Out-of-the-Box Demos

Each evaluation board boot image contains a default bitstream & device tree combination that is configured during the first boot.  Each platform includes the Xilinx Deep Learning Processing Unit (DPU) in the Zynq UltraScale+ Programmable Logic (PL). These platforms also include a software stack  (XRT + Vitis AI) required to take advantage of it.  All of the out-of-the-box images are based on Xilinx 2020.2 tools, IP, drivers, and firmware. The default platforms for the three boards are: 

Evaluation Board

Reference Hardware Platform

Evaluation Board

Reference Hardware Platform

ZCU102

Vitis AI v1.3 MPSoC DPU TRD

ZCU104

2020.2 VCU HDMI ROI TRD

ZCU106

2020.2 VCU HDMI ROI TRD

Running the ZCU10x DPU Demos

Each of the Out-of-the-Box demo designs includes the Xilinx DPU for machine learning inference.  The ZCU104 & ZCU106 designs include a 4096x1 configuration. The ZCU102 includes 4096x3 configuration. Each DPU configuration has an identical feature set and they are compatible with the pre-built models in the Xilinx Model Zoo that target the ZCU10x boards.

Running the Vitis AI Library Samples Snap

The xlnx-vai-lib-samples snap includes a pre-built subset of the Vitis AI Library sample applications available as source in the Vitis AI Github repository.  After installing the snap, users can experiment with twenty-seven different Vitis AI samples and over 90 different pre-built models.

For more information regarding using the xlnx-vai-lib-samples snap, please visit the xlnx-vail-lib-samples developer page.

Building the Vitis AI Library Sample Applications from Source

For users that would like to build the Vitis AI Library sample applications from source on the target, please visit the https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2072838191 page for detailed steps.

Using the ZCU104 & ZCU106  VCU Region of Interest (ROI) TRD Demo

This step requires an HDMI video source, HDMI display, and HDMI cables

The primary goal of the VCU ROI design is to demonstrate the use of the Xilinx Deep learning Processor Unit (DPU) block for extracting the Region of Interest (ROI) data from input video frames.  This information is then used to perform ROI-based encoding using the Video Codec Unit (VCU) encoder hard block present in Zynq UltraScale+ EV devices.

For instruction for running the VCU ROI TRD Demo, please visit the https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2105376824 page for detailed steps.

Creating a Custom Hardware Platform

COMING SOON!

Getting Help

Xilinx recommends posting on the Xilinx Embedded Linux Forum for any questions related to the Certified Ubuntu 20.04 LTS on Xilinx Devices release.

When posting on the Xilinx forums, please be sure to tag your post with the “Embedded_Ubuntu” keyword tag

Resources & References

This section outlines how to begin extending your usage beyond the initial Getting Started instructions.

For even more tips and tricks, see the Tips & Tricks page.

General Unsupported Usage Exceptions

The following configurations and use models are not supported:

  • Portrait mode is unsupported

  • Wake on USB (eg, pressing a key on a keyboard or clicking a button on a mouse) is not supported

Changing the Kernel bootargs Used By U-Boot

This appends options to the kernel command line - the latest value is the one actually used. For this example, we're overriding the default CMA value of 1000M with cma=256M: 

1 2 ubuntu@zynqmp:~$ sudo sh -c 'echo "LINUX_KERNEL_CMDLINE=\"cma=256M\" > /etc/default/u-boot-xlnx'  ubuntu@zynqmp:~$ sudo dpkg-reconfigure u-boot-zynqmp 

Note: Be sure to delimit quotation marks around the LINUX_KERNEL_CMDLINE values. This is so that multiple arguments can be passed at the same time. If only one argument is being specified then they can be omitted.

Note: If command line arguments are being used which include forward slashes ( / ) such as those found in filesystem paths, they must be delimited twice.

Example: sudo sh -c 'echo "LINUX_KERNEL_CMDLINE=\"cma=256M\ root=\\/dev\\/sda1" > /etc/default/u-boot-xlnx'

You must reboot the system for the changes to take place.

Installing & Using the Xilinx PPA

Xilinx has a Personal Package Archive (PPA) hosted by Canonical Launchpad at https://launchpad.net/~ubuntu-xilinx/+archive/ubuntu/updates . This PPA contains packages for some Xilinx-specific binaries that are not available in other upstream repositories. The standard method for installing PPA’s in Ubuntu desktop environment is documented here. To install the PPA via the command line, issue the following commands:

If you used the xlnx-config.sysinit to setup the system after first boot, the PPA has already been installed.

1 2 $ sudo add-apt-repository ppa:ubuntu-xilinx/updates $ sudo apt update

Xilinx updates the packages in the PPA from time to time. You can view the current list of packages in the archive by issuing the following command:

1 $ cat /var/lib/apt/lists/ppa.launchpad.net_ubuntu-xilinx_updates_ubuntu_dists_focal_main_binary-arm64_Packages

Pre-Installed Packages

The Certified Ubuntu on Xilinx Devices release contains some pre-installed packages. The default list of packages (and their versions) is described in the table below.

Package Name

Version

Description & Notes

Package Name

Version

Description & Notes

bootgen-xlnx

2020.2-0ubuntu~20.04.1

Xilinx BootGen tool used for creating bootable images

fpga-manager-xlnx

2020.2ubuntu2~20.04

Libraries and tools required to use the FPGA Manager framework on Xilinx platforms

libegl-mali-xlnx

9p0.01rel0-0ubuntu5~20.04.1

libEGL libraries for the Mali GPU

linux-firmware-xilinx-vcu

2020.2-0ubuntu1~20.04.1

Firmware required for the VCU operation

u-boot-xlnx

2020.2-0ubuntu11~20.04

Xilinx U-Boot bootloader - u-boot-zynqmp

vitis-ai

1.3.2-0ubuntu5~20.04.1

Vitis AI libraries & Vitis AI DNNDK legacy libraries

xf86-video-armsoc-endlessm

1.4.1-0ubuntu6~20.04.1

Open source driver for Arm GPU from the Endless OS Foundation xf86-video-armsoc repository.

xilinx-vcu-ctrl

2020.2-0ubuntu~20.04.1

Applications for encoding & decoding video streams (ctrlsw_decoder and ctrlsw_encoder)

xilinx-vcu-omx

2020.2-0ubuntu4~20.04.1

OMX decoder and encoder tools (omx_decoder and omx_encoder)

xlnx-firmware

0.1ubuntu17~20.04

Boot assets (bitstream, firmware, bootloaders, dtb, etc.)
HDMI Rx firmware

xrt

202020.2.8.726-0ubuntu7~20.04

Libraries required to support XRT on Arm platforms

Checking the Xilinx Kernel Configuration

If you would like to check the configuration of the current Ubuntu kernel, you can find the file in /proc/config.gz. You can output the contents of this file using the zgrep command:

1 $ zgrep /proc/config.gz

Special Considerations for the ZCU104 Evaluation Board

The ZCU104 evaluation board has less physical memory than the other supported boards. This difference means that resolutions higher than 1080p are not supported on the GNOME Desktop. Switching to a resolution lower than 1080p (e.g. 1280x720) can create a more responsive desktop experience. Full-screen video playback on the desktop should also be avoided to reduce the chance of running into out-of-memory performance issues.

Here are some recommendations for using the ZCU104 with this release:

  • Before running xlnx-config.sysinit from the Gnome Desktop:

    • Ensure that nothing else is running in the background.

    • Change the desktop resolution to 1280x720.

  • Do not update the desktop background

  • If you want the best desktop experience but are not interested in using the VCU, you can reduce the amount of contiguous memory(CMA) that is allocated by changing the kernel bootargs. 256M is recommended. Please refer to the Changing the Kernel bootargs Used By U-Boot section.

  • If the desktop gets into an unstable state, you can try restarting it from the console with the following command:

    1 sudo systemctl restart gdm
  • If you’re working from the serial port console or through ssh, you can shutdown the desktop to maximize available memory:

    1 sudo systemctl stop gdm

DisplayPort to HDMI Adapters 

Historically, DisplayPort to HDMI adapters have been problematic when used with the ZCU10x boards. However, there are some that work consistently. The table below lists ones that are known to work as well as some that did not work. 

Adapter Model

Status

Where to Purchase

Adapter Model

Status

Where to Purchase

JSAUX JSESNZ4KDP2HDF

Compatible

Amazon.ca

J5create JDA158

Compatible

J5Create Direct , Amazon.com , Staples , Best Buy , NewEgg.com

IVANKY-DP11

Incompatible

 

ICZI IZEC-A10-IT

Incompatible

 

Snowkids DP to HDMI Cable

Incompatible

 

Related Links