The Xilinx Certified Ubuntu 22.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, ZCU111 evaluation boards as well as the Kria KR260 and KV260 Starter Kits. Xilinx Ubuntu images can be download at Ubuntu.com.

Ubuntu 22.04 Certification has been achieved for ZCU102/4/6, KV260 and KR260. You can read more and download the certified Ubuntu hardware here.

Table of Contents

Hardware and Software Requirements

Installing the Image

Once you have downloaded the Certified Ubuntu for Xilinx Devices image fromhttps://ubuntu.com/download/amd-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.

Open

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:

• Power Adapter

• USB UART cable

• (Micro) SD Card

For the best experience, additionally connect the following:

• DisplayPort or HDMI (though DP->HDMI Adapter) 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:

• ZCU102: PetaLinux 2022.1 BSP

• ZCU104: PetaLinux 2022.1 BSP

• ZCU106: PetaLinux 2022.1 BSP

• ZCU111: PetaLinux 2022.1 BSP

• VCK190: Versal Base TRD 2022.1

• Kria KV260 Starter Kit: http://www.xilinx.com/KV260-Start

• Kria KR260 Starter Kit: http://www.xilinx.com/KR260-Start

For general information about how the boot process works for the ZCU10x image, please refer to Booting Certified Ubuntu 20.04 LTS for Xilinx Devices. For information on how the boot process works for the Kria KV/KR260 Starter Kits, please refer to the Kria K26 SOM wiki page.

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. Please note that the console output is split between the UART and the DisplayPort interface. Once you see the kria/zynqmp login: prompt you can log into the system.

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.

Logging in via the Graphical Desktop

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

Network Setup

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

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

Kria Firmware Updates

The KV260 and KR260 require updated firmware in order to use the full functionality of the boards. Please see the following links for more info:

• Kria SOMs & Starter Kits | Ubuntu 22.04 LTS

• Kria SOMs & Starter Kits | Boot Firmware Updates

• Kria SOMs & Starter Kits | Boot FW Update Process

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

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 snap and which is available from the Canonical Snap store (http://snapcraft.io).

For more information about using xlnx-config, please refer to the xlnx-config wiki page.

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

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 creating and installing custom platforms via xlnx-config, see the Usage Example section on the xlnx-config developer page.

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:

xlnx-config.sysinit takes care of the following items, depending on the system it's run on:

Add Xilinx-specific PPAs to the Package Repository List

Two repositories need to access Xilinx-specific packages will be added using add-apt-repository:

• ubuntu-xilinx/updates

• xilinx-apps/ppa

After the repositories are added, and “apt update” is run to ensure the latest updates are available.

Upgrade the System

It’s important to upgrade the system packages to the latest versions to pick up any bug fixes, security patches, or package updates. The script will prompt the user to run “apt upgrade” - this process can take quite a while depending on the number of updates that are available, but it’s a required step to make sure the system will operate properly. f

Using xmutil

In 22.04, the xmutil tools is provided as a pre-installed debian package on Kria platforms.

Overview of the Out-of-the-Box Demos

Each ZCU10x evaluation board boot image contains a default bitstream & device tree combination that is configured during the first boot.  Each ZCU10x 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.  The Kria KV260 Starter Kit includes a series of Vitis platforms to support various accelerated applications (AAs). All of the out-of-the-box images are based on Xilinx 2020.2 (2020.2.2 for Kria) tools, IP, drivers, and firmware.

The default platforms for the three boards are: 

Running the ZCU10x DPU Demos

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. Using the xlnx-vai-lib-samples snap requires a compatible bitstream (Coming Soon).

For more information regarding using the xlnx-vai-lib-samples snap, please visit the xlnx-vai-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 Building Vitis-AI Sample Applications on Certified Ubuntu 20.04 LTS for Xilinx Devices page for detailed steps.

Running the Kria Demos

Pre-built accelerated applications are available for download and installation in the Kria App Store

Creating a Custom Hardware Platform

For ZCU10x boards, please refer to the xlnx-config snap page for more information regarding creating and installation of custom platforms.

For Kria kits, please refer to the Kria Applications Documentation.

Getting Help

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

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.

Known Issues and Limitations

Kria Boards

The Certified Kria Ubuntu 22.04 LTS Production image has the following known issues and limitations:

The Kria Ubuntu 22.04 LTS Pre-Production (-78) image has the following known issues and limitations:

• Suspend/resume functionality is not supported including Ethernet wake-on-LAN (WOL)

• via-lab chipset based USB hubs will cause boot failure. Recommendation to use USB devices without a hub.

• Install of Xilinx application packages causes dfx-mgr to crash. Recommendation to reboot platform or restart dfx-mgr service.

• xmutil pwrctrl utility functional but does not print status to console

• Audio playback on DisplayPort occasionally produces a “clicking” noise in concert with actual audio playback

• KV260: Legacy boot FW (2021.1) will not boot the Ubuntu 22.04 image. Upgrade to 2022.1 Boot FW prior to loading Ubuntu 22.04 image.

• KR260: KR260 USB2.0 devices not functional on U46 interfaces. Upgrade to 2022.1 Boot FW.

• Portrait mode is unsupported

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

• KR260: KR260 only supports a single lane of DisplayPort with a maximum resolution of 1080p. Some monitors are not able to negotiate the maximum link speed to support 1080p, so a lower maximum resolution may be reported.

• KD240: A longer boot time may be seen on KD240. This is under investigation for resolution in a future release. Ref#2034604

• KD240: KASLR is currently disabled on Kria images. This is under investigation for resolution in a future release.  Ref#2030907

• KD240: On revB boards the Machine Name may be incorrectly printed as ZynqMP KD240 revA.  This is being investigated for resolution in the next release.  Ref#2033477

• KD240: The RS485 component on KD240 boards may fail to send and receive messages.   This is being investigated for resolution in the next release.  Ref#2021573

• KD240: On KD240 boards the CAN0 interface may fail to come online when enabled with "ip link set can0 up2" with either  "Invalid argument" returned or "kria kernel: xilinx_can ff060000.can can0: bit-timing not yet defined" printed to the Journal log.    To resolve this issue ensure the bitrate is set before enabling the CAN device:    "ip link set can0 type can bitrate 100000 loopback on // CAN node configure with 100Kbps speed."  This is being investigated for resolution in the next release.  Ref #2025450

• KD240: On KD240 boards errors relating to sdhci0 (sdhci-arasan)  may be seen during boot and in dmsg logs.    This is being investigated for resolution in the next release.  Internal reference #2034924

ZCU10x Boards

TBD

Versal Boards

The Ubuntu 22.04 LTS release for Versal boards is a DEVELOPER PREVIEW. It is not intended for use in a production environment.

Versal board support in Ubuntu 22.04 LTS currently has the following known issues/limitations.

• Versal board support is currently limited to only the VCK190 Evaluation Platform

• The default bitstream configuration does not properly support the video camera pipeline

  • This will be fixed in a post-release package update

• Suspend/resume is currently unsupported

  • Filesystem corruption is possible on the ext4 partition of the SD card during suspend/resume operations

  • Ethernet may fail to renegotiate an IP address during suspend/resume operations

  • HDMI may display a blank screen during suspend/resume operations

  • Warm restart (rebooting without a power cycle) is currently unsupported

Changing the Kernel bootargs Used By U-Boot

If your application or configuration requires specific arguments you can configure U-Boot to pass these arguments automatically. You can use the flash-kernel utility and update the bootargs in /etc/default/flash-kernel. There are two variables you can set in this file to custom the kernel command line:

Example bootargs Updates

To override the CMA value (256M in this case):

To use the “quiet splash” argument to reduce console output:

Completing the Update

After updating the Linux kernel boot arguments, run the flash-kernel utility to update the bootargs passed the Linux kernel on the next reboot.

Verifying the bootargs

To verify that the bootargs are set they way you want them, you can use the following command after the reboot:

Installing & Using the Xilinx PPAs

Xilinx has a two Personal Package Archives (PPAs) hosted by Canonical Launchpad:

• https://launchpad.net/~ubuntu-xilinx/+archive/ubuntu/updates

• https://launchpad.net/~xilinx-apps/+archive/ubuntu/ppa
  
  

These PPAs contain 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:

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:

Pre-Installed Packages

The Certified Ubuntu on Xilinx Devices release contains some pre-installed packages to enable the Xilinx software stack. The list of packages is described in the table below.

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:

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:

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

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. 

Related Links

• Booting Certified Ubuntu for Xilinx Devices

• Building Vitis-AI Sample Applications on Certified Ubuntu 20.04 LTS for Xilinx Devices

• Running the VCU ROI Demo on Certified Ubuntu 20.04 LTS for Xilinx Devices

• Tips & Tricks for Certified Ubuntu AMD-Xilinx Devices

• Rebuilding the Certified Ubuntu for AMD ARM Devices Linux Kernel from Source

• Using the Certified Ubuntu on Xilinx Devices image with a SATA hard disk

• Snaps for Certified Ubuntu on Xilinx Devices

  • Snaps - xlnx-config Snap for Certified Ubuntu on Xilinx Devices

  • Snaps - xlnx-vai-lib-samples Snap for Certified Ubuntu on Xilinx Devices

  • Snaps - xlnx-nlp-smartvision Snap for Certified Ubuntu on Xilinx Devices