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
- 1 Hardware and Software Requirements
- 2 Installing the Image
- 3 First Boot and Getting Started
- 4 Kria Firmware Updates
- 5 Set up the Xilinx Development & Demonstration Environment for Ubuntu 22.04 LTS
- 6 Using xmutil
- 7 Overview of the Out-of-the-Box Demos
- 8 Creating a Custom Hardware Platform
- 9 Getting Help
- 10 Resources & References
- 10.1 Known Issues and Limitations
- 10.1.1 Kria Boards
- 10.1.2 ZCU10x Boards
- 10.1.3 Versal Boards
- 10.2 Changing the Kernel bootargs Used By U-Boot
- 10.2.1 Example bootargs Updates
- 10.2.2 Completing the Update
- 10.2.3 Verifying the bootargs
- 10.3 Installing & Using the Xilinx PPAs
- 10.4 Pre-Installed Packages
- 10.4.1 xilinx-bootgen
- 10.5 Checking the Xilinx Kernel Configuration
- 10.6 Special Considerations for the ZCU104 Evaluation Board
- 10.7 DisplayPort to HDMI Adapters
- 10.1 Known Issues and Limitations
- 11 Related Links
Hardware and Software Requirements
| 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 fromInstall Ubuntu on AMD | Ubuntu , 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:
Kria KV260 Starter Kit: Introduction
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.
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.
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 Configuring networks | Ubuntu
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:
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 |
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
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 |
---|---|
ZCU102 | 2022.1 Petalinux BSP |
ZCU104 | 2022.1 Petalinux BSP |
ZCU106 | 2022.1 Petalinux BSP |
VCK190 | |
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
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:
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):
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:
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.
Package Name | Description & Notes | KR/V260 | ZCU10x |
---|---|---|---|
dfx-mgr |
| Y | Y |
libdfx-mgr1 |
| Y | Y |
| Xilinx BootGen tool used for creating bootable images | N | Y |
| fpgautil | Y | Y |
| libEGL libraries for the Mali GPU | Y | Y |
| Xilinx U-Boot bootloader - u-boot-zynqmp | N | Y |
| Vitis AI libraries & Vitis AI DNNDK legacy libraries | N | TBD |
| Open source driver for Arm GPU from the Endless OS Foundation xf86-video-armsoc repository. | Y | Y |
| Applications for encoding & decoding video streams ( | Y | Y |
| OMX decoder and encoder tools ( | Y | Y |
| Boot assets (bitstream, firmware, bootloaders, dtb, etc.) | N | Y |
| Libraries required to support XRT on Arm platforms | Y | Y |
| Ubuntu meta-package for support of the Certified Ubuntu on Xilinx Devices image on Kria platforms | Y | N |
xmutil |