Getting Started with Certified Ubuntu 22.04 LTS for Xilinx Devices

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.

Please see the note below regarding Kria Firmware updates required for using the Ubuntu 22.04 image.

Table of Contents

Hardware and Software Requirements

 

SD Card

Networking

USB Peripherals

Miscellaneous

 

SD Card

Networking

USB Peripherals

Miscellaneous

ZCU102 (Rev 1.0+)

16GB+ 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+)

16GB+ Micro SD Card

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

ZCU106 (Rev 1.0+)

16GB+ SD Card

Kria KR260 Starter Kit

16GB+ Micro SD Card

Kria KV260 Starter Kit

16GB+ Micro SD Card

The KV260 desktop is mirrored on both the DisplayPort and HDMI interfaces.

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.

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:

  • 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:

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.

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. 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.

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.

Logging in via the Graphical Desktop

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

Default Ubuntu 22.04 LTS GNOME 42 Greeter Screen
Default Ubuntu 22.04 LTS GNOME 42 Desktop

All systems using the Certified Ubuntu for Xilinx Devices image will initially boot with the graphical resolution of 1920x1080

  • 4K (3840x2160) resolution is possible for the KV260, ZCU106, and ZCU104 (not recommended for ZCU104, see note below)

  • 1080p (1920x1080) is the maximum resolution for the KR260 and ZCU102 due to only one DP lane being allocated (ZCU102 HW supports 4k with custom firmware)

  • Xilinx recommends using the 1920x1080 resolution for the most robust desktop experience.

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 22.04 root filesystem. To install them, you can use the following command:
$sudo apt install net-tools

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

GNOME 42 Network Settings Dialog

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:

If your Ubuntu 22.04 image is not booting due to firmware mismatch, you will need to load a working Petalinux or Ubuntu image to update the firmware. If using Ubuntu 20.04, the xlnx-config --xmutil command should be used instead of xmutil as indicated on the K26 wiki page. Alternatively, you can use the Stand Alone Firmware Update and Recovery Utility.

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: 

$ sudo snap install xlnx-config --classic --channel=2.x

For Kria users who are familiar with the xmutil command, there is now a xmutil debian package pre-installed in the images. It is no longer a requirement to use xlnx-config for xmutil functionality.

 

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

At the end of the sysinit process, you will see a dialog box come up asking what daemons should be restarted. Please hit “enter” to proceed.

In some cases when immediately running sysinit after the first boot, users have reported running into “waiting for cache lock” issues when the sysinit script attempts to install packages. This is due to the standard Ubuntu “unattended upgrades” process starting up before sysinit. If this happens, the systinit script will take much longer than usual while it waits for permission to begin installing packages. In certain situations, you may have to run xlnx-config.sysinit again. For more information about this issue, you can refer to the following page:

https://unix.stackexchange.com/questions/374748/ubuntu-update-error-waiting-for-unattended-upgr-to-exit

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: 

Evaluation Board

Reference Hardware Platform

Evaluation Board

Reference Hardware Platform

ZCU102

2022.1 Petalinux BSP

ZCU104

2022.1 Petalinux BSP

ZCU106

2022.1 Petalinux BSP

VCK190

VCK190: Versal Base TRD 2022.1 ( Platform 1 VCK190 Single Sensor design vck190_mipiRxSingle_hdmiTx version v1.4)

Kria KV260 Starter Kit

2022.1 Vitis Platforms

Kria KR260 Starter Kit

2022.1 Vitis Platforms

Running the ZCU10x DPU Demos

Running the Vitis AI Library Samples Snap

Coming soon for 22.04

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.

When posting on the Xilinx forums, please use the “Add Topic” feature to tag your post with the “EMBEDDED UBUNTU” topic (no underscore)

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

It is very important to update the boot firmware on your Kria boards before using the 22.04 image

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:

LINUX_KERNEL_CMDLINE="<args added to end of default bootargs from u-boot env>" LINUX_KERNEL_CMDLINE_DEFAULTS="<args before the default bootargs from u-boot env>"

Example bootargs Updates

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

LINUX_KERNEL_CMDLINE="cma=256M"

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

LINUX_KERNEL_CMDLINE="quiet splash cma=256M"

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.

ubuntu@kria:~$ sudo flash-kernel

Verifying the bootargs

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

ubuntu@kria:~$ cat /proc/cmdline earlycon root=LABEL=writable rootwait console=ttyPS1,115200 console=tty1 clk_ignore_unused uio_pdrv_genirq.of_id=generic-uio xilinx_tsn_ep.st_pcp=4 cma=1000M quiet splash cma=256m

Installing & Using the Xilinx PPAs

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

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:

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

sudo add-apt-repository ppa:xilinx-apps/ppa 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:

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

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.

Unless otherwise noted, the Xilinx version for any Xilinx-specific packages is 2022.1

This table is currently being updated ahead of the Certified Ubuntu releases for Ubuntu 22.04.

Package Name

Description & Notes

KR/V260

ZCU10x

Package Name

Description & Notes

KR/V260

ZCU10x

dfx-mgr

 

Y

Y

libdfx-mgr1

 

Y

Y

xilinx-bootgen

Xilinx BootGen tool used for creating bootable images

N

Y

fpga-manager-xlnx

fpgautil

Y

Y

libegl-mali-xlnx

libEGL libraries for the Mali GPU

Y

Y

u-boot-zynqmp

Xilinx U-Boot bootloader - u-boot-zynqmp

N

Y

vitis-ai

Vitis AI libraries & Vitis AI DNNDK legacy libraries

N

TBD

xserver-xorg-video-armsoc-endlessm

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

Y

Y

xilinx-vcu-ctrl

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

Y

Y

xilinx-vcu-omx

OMX decoder and encoder tools (omx_decoder and omx_encoder)

Y

Y

xlnx-firmware

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

N

Y

xrt

Libraries required to support XRT on Arm platforms

Y

Y

oem-limerick-kria-meta

Ubuntu meta-package for support of the Certified Ubuntu on Xilinx Devices image on Kria platforms

Y

N

xmutil

 

Y

Y

fru-print

 

Y

Y

libxilinx-vcu-dev

 

Y

Y

libxilinx-vcu0

 

Y

Y

libxilinx-vcu-omx-dev

 

Y

Y

libxilinx-vcu-omx1

 

Y

Y

xilinx-vcu-omx-utils

 

Y

Y

linux-firmware-xilinx-vcu

Firmware required for the VCU operation

Y

Y

xlnx-default-bitstreams

 

Y

N

linux-firmware-xilinx-ap1302

 

Y

Y

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:

$ 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:

    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:

    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

 

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy