This page provides usage and release notes for the xlnx-config snap. The xlnx-config snap can be found in the Canonical Snap Store at https://snapcraft.io/xlnx-config.

In Ubuntu 22.04, a xlnx-config has been updated with 22.04-specific changes. Therefore, it’s required to have two different versions of xlnx-config for use 20.04 and 22.04.

For 22.04, users should install the 2.x “track” (--channel=2.x) from the snap store. This is now set to the default version if no channel is specified.
For 20.04, users should install the 1.x track (--channel=1.x)

A key difference between the two versions is that the 2.x version does not include the xmutil or dfx-mgr utilities. These are provided as pre-installed debian packages in 22.04.

1 Introduction
- 1.1 Platform Management
- 1.2 Xclbin Access for Snaps
- 1.3 Xilinx-specific System Initialization
  - 1.3.1 Ubuntu 20.04 - 1.x Track
  - 1.3.2 Ubuntu 22.04 - 2.x Track
2 Installation
3 Supported Options
- 3.1 xmutil Sub-Commands
4 Platform Assets Container
- 4.1 ZCU10x PAC
- 4.2 Kria SOM PAC
- 4.3 Format of the manifest file
- 4.4 Assets Directory
- 4.5 ZCU10x Assets
- 4.6 KV260 Assets
5 Run-Time Asset Management
6 Snap Details
- 6.1 Snap Install Hook
- 6.2 One-Shot Daemon
- 6.3 xlnx-configd
7 ZCU10x Usage Example
- 7.1 Custom PAC Installation
  - 7.1.1 Manual Installation
  - 7.1.2 Snap Installation
- 7.2 Manifest Files
- 7.3 Boot Assets
- 7.4 Bootgen BIF File
- 7.5 Activating the Platform
- 7.6 Deactivating the Platform
8 KV260 Usage Example
9 Important Files and Directories
10 Creating PACs for Vitis Accelerated Platforms
11 Snap Release Notes

Introduction

Xlnx-config is command line tool used to manage and manipulate the hardware platform for Xilinx ZCU102/4/6 and KV260 boards running Certified Ubuntu 20.04 LTS for Xilinx Devices. Xlnx-config provides three main functions as detailed below.

A beta version is available that supports the VCK190 - Please add --beta to the install command to use this version.

Platform Management

The main purpose of the xlnx-config is to load custom hardware platforms (Targeted reference designs (TRDs), Vitis accelerated platforms, etc) for the Zynq UltraScale+ boards other than the standard standard platforms delivered as part of the Certified Ubuntu for Xilinx Devices Image.

For ZCU10x, xlnx-config manages the installing of the custom boot assets (bitstream, firmware, and xclbin) while maintaining the “golden” boot assets delivered with the Certified Ubuntu image. For detailed information about the ZCU10x boot process, please refer to Booting Certified Ubuntu for Xilinx Devices.

For the KV260, which does not include a bitstream in the official image, xlnx-config manages the installation of “Accelerated Application” (AA) firmware by integrating a subset of the “xmutil” set of sub-utilities.

Xclbin Access for Snaps

Xlnx-config provides a way for strictly confined applications snaps to access the xclbin currently present in the system. Since snap applications are strictly confined, they don’t access to many system resources. However, xlnx-config is a “classic” snap which means it has more access to the system than a typical snap. We use the concept of a “content plug” to provide the xclbin (and possibly other system resources) to “consumer snaps” from the xlnx-config “producer” snap.

When application snaps that need access to the xclbin are installed (e.g. xlnx-vai-lib-samples, or xlnx-nlp-smartvision), they automatically connect to the xlnx-config assets directory through the content interface as specified in the snapcraft build file for the application snap. This allows files (ex: dpu.xclbin) to be shared through the interface.

Xilinx-specific System Initialization

Ubuntu 20.04 - 1.x Track

The sysinit sub application is used to install Xilinx Gstreamer and Video packages to facilitate the use of the advanced multi-media features of the Zynq UltraScale+ MPSoC device. This sub app should be executed after first boot of the system.

With xlnx-config installed in the system, you can view the sysinit script at /snap/xlnx-config/current/bin/sysinit.sh

Ubuntu 22.04 - 2.x Track

For 22.04, sysinit performs the following functions - no additional packages are installed:

add ubuntu-xilinx/sdk PPA to the repository list
add xilinx-apps/ppa PPA to the repository list
run apt udpate
run apt upgrade

Installation

To install xlnx-config, you must include the --classic option since this is a classic confined snap:

sudo snap install xlnx-config --classic --channel=<1.x or 2.x>

If no channel is specified, 2.x will be used

Supported Options

Option	Description	ZCU10x	KV260	sudo req’d

Option	Description	ZCU10x	KV260	sudo req’d
`--version, -v`	returns current version of xlnx-config
`--query, -q`	Checks for currently available HW configurations, by searching for manifest files. The locations where it searches are: Platform Snap: /snap//current/hwconfig//manifest.yaml Manual Install /usr/local/share/xlnx-config//hwconfig//manifest.yaml /boot/firmware/xlnx-config//hwconfig//manifest.yaml
`--activate, -a <config_name>`	Activates a configuration by using its name or, directly, the path to the manifest. It checks the system compatibility by looking at the manifest and then applies the configuration (for instance, it builds and installs the boot and FPGA assets).
`--deactivate, -d`	Deactivates the currently active configuration, uninstalling its assets. After a reboot, the default boot assets for the board will be loaded.
`--xmutil, -x <sub command>`	This option specifies that the following arguments will be passed on to the xmutil sub-application. 20.04/1.x track only
`-s,--snap <snap install options>`	Specify that that the platform name used with the --install argument is a snap
`--i,--install <config name>`	Copy a PAC configuration into the /lib/firmware/xilinx directory so it can be loaded with xmutil
`--get-board, -b:`	returns the system's board model (currently, one of zcu102, zcu104, zcu106, zcu111, kv260).
`--force, -f`	Use jointly with `-a` or `-d` to force activation/deactivation even if the configuration seems already correct.
`--is-active, -c`	<hwconfig_name_or_manifest>: Check whether a HW configuration (given by name or by manifest path) is currently active.
`--update, -u`	Update the assets directory to match /usr/lib/dpu.xclbin and deactivate any platform not matching the current board. This is executed one time every boot as a one-shot daemon. See One-Shot Daemon for more details.
`xlnx-config.sysinit`	Sub-application that installs Xilinx-specific gstreamer and video packages

xmutil Sub-Commands

20.04/1.x track only

xlnx-config provides a sub-set of the xmutil sub-commands. The following table lists those commands and their options. All xmutil sub-commands require sudo.

xmutil sub-command

xmutil sub-command
`boardid`	Reads all board EEPROM contents. Prints information summary in human readable structure to CLI
`listapps`	Queries on target HW resource manager daemon of firmware/bitstream available on the platform and provides summary to CLI
`loadapp`	Loads selected firmware/bitstream
`unloadapp`	Unloads currently loaded firmware/bitstream
`bootfw_status`	Reads primary boot device information. Prints A/B status information, image IDs, and checksums to CLI
`bootfw_update`	Updates the primary boot device with a new boot.bin in the inactive partition (either A or B)
`platformstats`	Reads and prints a summary of the following performance related information: CPU frequency & utilization statistics for each physical coreRAM utilization DDR controller bandwidth & operational frequency Temperature(s) reported by SysMon SOM overall current & power utilization reported by SOM current monitor IC SOM power supply data summary reported by PMICs & ZU+ SysMon sources
`ddrqos`	Utility for changing configuration of PS DDR quality of service (QoS) settings
`axiqos`	Utility for changing configuration of PS/PL AXI interface quality of service (QoS) settings

The following sub-commands are not currently supported: pwrctl, getpkgs

Platform Assets Container

A Platform Assets Container (PAC) is used to package one or more sets of custom boot assets. The boot assets and manifests will always be under a directory called hwconfig in the installed package or snap. The hwconfig directory contains at least one “configuration” directory (the names of the configuration directories are user-defined) which defines a unique reference design in the package that could have support for multiple boards. Under the configuration directory, there is a manifest.yaml, and at least one board-specific “assets directory” that contains the boot assets for that configuration/board combination.

The [data] directory shown below is optional, and can be used to store software, data, config files, etc. It can have any name, and xlnx-config does not parse it.

ZCU10x PAC

The diagram below shows what a ZCU10x PAC directory structure would look like with three unique configurations with assets for all three boards:

<PAC Name>
 | 
 |--[data]
 |
 └--hwconfig 
          |---- <config_1> ---- manifest.yaml
          |               |-- zcu102 ---- 
          |               |            |-- bootgen.bif
          |               |            |-- [dpu.xclbin]
          |               |            |-- <fsbl>
          |               |            |-- <bitstream>
          |               |            |   .
          |               |            |   .
          |               |            └-- <other_boot_assets>
          |               |-- zcu104
          .               .        └--<zcu104 assets>
          .               .
          |               └-- zcu106
          |-- <config_2>        └--<zcu106 assets>
          .
          .
          └-- <config_N>

Kria SOM PAC

The diagram below shows what a KV260 directory structure would look like with two configurations for the KV260:

<PAC Name>
 | 
 |--[data]
 |
 └--hwconfig 
          |---- <config_1> ---- manifest.yaml
          |               |-- kv260 ---- 
          |                            |-- <.xclbin>
          |                            |-- <.bit.bin>
          |                            |-- <.dtbo>
          |                            |-- shell.json
          |
          |---- <config_2> ---- manifest.yaml
          |               |-- kv260 ---- 
          |                            |-- <.xclbin>
          |                            |-- <.bit.bin>
          |                            |-- <.dtbo>
          |                            |-- shell.json

Format of the manifest file

Manifest files will contain meta-information for a hardware configuration, usually tied to capabilities needed by an application. It’s a yaml file describing compatibility information and the location of the boot assets. For example:

name: <configuration>
description: <full description>
revision: <number>
assets:
    <asset key>: <assets directory>

Field details:

name: configuration name, usually the same as the parent directory
description: a detailed description. Details on how to run the application can be described here.
revision: a number used to version the boot assets
assets: information about assets for a given board. This is a dictionary where keys are the board name as returned by the --get-board option
- Valid keys are zcu102, zcu104, zcu106, zcu111, zcu208, zcu216, and kv260. The “assets directory” is typically named the same, but it can be unique.

Assets Directory

ZCU10x Assets

The directory will contain .bif file describing how to build boot*.bin files and the boot assets necessary for that. Additionally, an xclbin file called dpu.xclbin might be present for DPU-enabled systems. There will be an directory for every compatible board (zcu102, zcu104, zcu106).

The names expected for the files are:

Filename	Description
`bootgen.bif`	Bootgen config file used by xlnx-config to package new boot.bin
`fsbl.elf`	Zynq UltraScale+ First Stage Boot Loader (FSBL)
`bl31.elf`	ARM Trusted Firmware (ATF)
`pmufw.elf`	Platform Management Unit (PMU) Firmware
`system.bit`	The Programmable Logic bitstream
`system.dtb`	The Linux Device tree that matches the contents of the bitstream
`dpu.xclbin`	The xclbin file that matches system.bit (optional)

The bootgen.bif must reference a U-Boot binary. For Certified Ubuntu on Xilinx Devices, this should be the u-boot.elf provided by Canonical at /usr/lib/u-boot/xilinx_zynqmp_virt/u-boot.elf)

After activation, the manifest for the currently active configuration is stored by xlnx-config. If we try to activate the same configuration again, xlnx-config will detect that and will not re-apply the changes. The revision field can be increased to signal that assets have changed so they are updated even when the configuration is already active.

KV260 Assets

For KV260, the assets directory contains the accelerated application firmware as shown in the following table.

Filename	Description
`<Accelerated app name>.bit.bin`	The Programmable Logic bitstream in .bin format
`<Accelerated app name>.xclbin`	The xclbin file that matches the bitstream (optional)
`<Accelerated app name>.dtbo`	Binary Linux device tree overlay blob that matches the contents of the bitstream
`shell.json`	json file required by dfx-mgr

In this release, shell.json should be a text file with the following contents:

{
"shell_type" : "XRT_FLAT",
"num_slots": "1"
}

Run-Time Asset Management

Handling of the ZCU10x boot assets

When an configuration is activated, if the assets directory for the board contains a bootgen.bif file, new boot assets will be generated by xlnx-config by following these steps:

Copy files from the assets directory to a temporary directory.
Run bootgen using bootgen.bif as input. This file can reference not only the files coming from the assets directory, but also the default boot assets installed in the system like /usr/lib/u-boot/xilinx_zynqmp_virt/u-boot.elf or /usr/share/xlnx-firmware/zcu10*/*, so there is no need to include all binaries in the application package.
Copy the resulting boot10?0.bin file to /boot/firmware/. This file has precedence over the default boot assets named boot10?1.bin, so if present, they are loaded by the image selector.
The manifest.yaml file for the configuration will be copied to /var/lib/xlnx-config. This way the snap will know if it has been activated and if that is the case, which configuration has been activated.
A file named active_board is created in the same directory that includes the active board name and the location of the activated assets directory.
Once the activation is complete, the user must manually reboot the system in order for the new boot assets to take effect.

When a configuration is deactivated, the following steps will be taken:

The /boot/firmware/boot10?0.bin file will be removed if present, and the user will be asked to reboot the system for the changes to take effect.
The manifest.yaml and active_board files will be removed from /var/lib/xlnx-config.

Note that when a new configuration is activated, the steps to deactivate any previously activated configuration are applied as first step.

Handling of dpu.xclbin for ZCU10x

20.04/1.x track only

Each of the three ZCU10x platforms provided with the Certified Ubuntu on Xilinx Devices images includes the Xilinx® Deep Learning Processor Unit (DPU) in the PL. On Ubuntu, there is a symbolic link with path /usr/lib/dpu.xclbin that points to the correct dpu.xclbin file for the board. Each time the system boots, a script runs (dpu-config.sh, see table below) to make sure the link is pointing to the correct dpu.xclbin for the current evaluation board. In the case that a custom set of boot assets (provided by a PAC) has been activated, and the standard dpu.xclbin has been updated, the dpu-config.sh will not overwrite it. Upon deactivation of the custom boot assets, xlnx-config will restore the link back to the the proper board-specific dpu.xclbin.

For example after the zcu102 is booted the first time, the following link will be configured:

/usr/lib/dpu.xclbin -> /usr/share/xlnx-firmware/zcu102/dpu.xclbin

If the SD card is moved to a ZCU104, the link will be updated:

/usr/lib/dpu.xclbin -> /usr/share/xlnx-firmware/zcu104/dpu.xclbin

There are three scenarios where xlnx-config needs to make sure that the dpu.xclbin in its assets directory is up to date:

Scenario	Action Taken

Scenario	Action Taken
Initial snap install	The `xlnx-config` install hook copies `/usr/lib/dpu.xclbin` to the `xlnx-config` assets directory
Reboot with Golden image	`xlnx-config --update` is called by the one-shot daemon at boot to make sure the assets directory is in sync with `/usr/lib/dpu.xclbin`.
Activation of new PAC boot assets that includes `dpu.xclbin`	`xlnx-config` copies the new `dpu.xclbin` to the assets directory as part of the activation process.

Handling of the .xclbin for KV260

For accelerated applications that include a .xclbin in their firmware package, the dfx-mgrd daemon will udpate /etc/vart.conf with a link to the .xclbin when the accelerated application firmware is loaded. When /etc/vart.conf is updated, the xlnx-configd daemon will see that, and automatically copy the .xclbin into the xlnx-config assets directory so it can be accessed by application snaps that need it. See the xlnx-configd section below for more details.

Snap Details

Snap Install Hook

When xlnx-config is installed, the "install hook" will look in the firmware directory of the current board (e.g. /usr/share/xlnx-firmware/zcu106 ) and, if present, copy the dpu.xclbin to the $SNAP_DATA/assets directory (/var/snap/xlnx-config/current/assets). This assets directory is made available as a read-only "content interface" to all other xlnx- snaps. For other snaps to access this assets directory, their snapcraft.yaml should include the following plug definition:

plugs:
    assets:
        interface: content
        target: $SNAP_DATA/assets

Before running an application that requires the DPU, the following environment variable is set to point to the dpu.xclbin being shared by the xlnx-config snap:

export XLNX_VART_FIRMWARE=$SNAP_DATA/assets/dpu.xclbin

This can be either be set in the wrapper script that calls the DPU app, or set in the apps/environment property in snapcraft.yaml:

test-app:
   command: bin/test_app.sh
   plugs: [opengl, home]
   environment:
       XLNX_VART_FIRMWARE: $SNAP_DATA/assets/dpu.xclbin

One-Shot Daemon

20.04/1.x track only

Each time the system boots after xlnx-config has been installed, a “one-shot daemon” will run and execute the following command: xlnx-config --update

The update option causes xlnx-config to go and copy the existing /usr/lib/dpu.xclbin, to the xlnx-config assets directory. This is necessary in the case that user switches an SD Card from one evaluation board type to another. It also checks to see if there is a currently activated set of custom PAC boot assets in the system. If so, it will check /var/lib/xlnx-config/active_board file to see if the assets were activated on a different board than we’re currently running on. If the boards are different, then the current set of boot assets will be deactivated.

xlnx-configd

When the xlnx-config snap is started, a “simple daemon” called xlnx-configd is started. This daemon is responsible for the following tasks.

Determine the Board Type

xlnc-configd will check the value in /proc/device-tree/model to determine the board type. For zcu10x boards, it will write the board type to $SNAP_DATA/board.txt (i.e. /var/snap/xlnx-config/current/board.txt). If a Kria SOM is detected, then xlnx-configd will access the EEPROM data on the board to determined which carrier card is present. It will then write this data to $SNAP_DATA/board.txt

Create a Xilinx Firmware Directory

xlnx-configd will create /lib/firmware/xilinx if it doesn’t already exist

Monitor for changes to /etc/vart.conf

Finally, xlnx-configd will enter a loop and, using inotify, watch for changes to /etc/vart.conf. If a change is detected, then the referenced xclbin is copied to the xlnx-config assets directory, and link called dpu.xclbin is created, linking to the .xclbin.

ZCU10x Usage Example

In this example, we’ll examine the makeup of a ZCU10x PAC, then walk through the process of activating and deactivating a simple set of PAC boot assets.

Custom PAC Installation

Custom PACs can be installed in two ways:

Manually install in the filesystem
Install as a PAC snap

Manual Installation

When using the manual install method, the PAC archive must be copied/extracted into one of two places:

/boot/firmware/xlnx-config/<pac name>
/usr/local/share/xlnx-config/<pac name>

/boot/firmware is the mount point for the FAT partition of the SD card

In this example, the PAC name is "test_pac". After copying the PAC archive to the target board, it has been extracted into the /boot/firmware/xlnx-config/test_pac directory. The PAC includes two unique configurations: foo and hello world. Each of the configurations includes boot assets for both the ZCU102 and ZCU104. The directory structure is shown below:

test_pac/
└── hwconfig
    ├── foo
    │   ├── manifest.yaml
    │   ├── zcu102
    │   │   ├── bl31.elf
    │   │   ├── bootgen.bif
    │   │   ├── fsbl.elf
    │   │   ├── pmufw.elf
    │   │   ├── system.bit
    │   │   └── system.dtb
    │   └── zcu104
    │       ├── bl31.elf
    │       ├── bootgen.bif
    │       ├── fsbl.elf
    │       ├── pmufw.elf
    │       ├── system.bit
    │       └── system.dtb
    └── hello_world
        ├── manifest.yaml
        ├── zcu102
        │   ├── bl31.elf
        │   ├── bootgen.bif
        │   ├── fsbl.elf
        │   ├── pmufw.elf
        │   ├── system.bit
        │   └── system.dtb
        └── zcu104
            ├── bl31.elf
            ├── bootgen.bif
            ├── fsbl.elf
            ├── pmufw.elf
            ├── system.bit
            └── system.dtb

Snap Installation

When installing the PAC as a PAC snap using "sudo snap install <PAC snap name>," the contents of the PAC will be found at the following location:

/snap/<PAC snap name>/current/

The hwconfig directory must, for example, be in the following location:

/snap/test_pac/current/hwconfig

Manifest Files

The manifest.yaml is parsed by xlnx-config to discover details about the available board-specific boot assets. For this test, the manifests for the two configurations are shown below:

hello_world configuration manifest:

name: test_platform-foo
desscription: Boot assets for the 2020.2 foo design
revision: 1
assets:
        zcu102: zcu102
        zcu104: zcu104

hello_world configuration manifest:

name: test_platform-hello_world
desscription: Boot assets for the 2020.2 hello_world design
revision: 1
assets:
        zcu102: zcu102
        zcu104: zcu104

Boot Assets

The board specific boot assets folder (typically named the same as the board) contains the set of files needed to create a new boot.bin. In the case of dpu-enabled platforms, it also includes a dpu.xclbin. See the Assets Directory section above for more information.

Bootgen BIF File

Typically, each configuration will include all of the boot assets needed to generate a boot.bin. The one exception is u-boot.elf, which should come from the currently installed u-boot.elf provided by the u-boot debian package. A typical bootgen.bif is shown below:

the_ROM_image:
{
        [bootloader, destination_cpu=a53-0] fsbl.elf
        [pmufw_image] pmufw.elf
        [destination_device=pl] system.bit
        [destination_cpu=a53-0, exception_level=el-3, trustzone] bl31.elf
        [destination_cpu=a53-0, load=0x00100000] system.dtb
        [destination_cpu=a53-0, exception_level=el-2] /usr/lib/u-boot/xilinx_zynqmp_virt/u-boot.elf
}

It's also possible to refer to the golden boot assets for a particular board by referring to the files at /usr/share/xlnx-firmware/zcu10[x]

Activating the Platform

Now that the PAC is installed, xlnx-config -q can be used to query the system and report any boot assets available for the current boards:

ubuntu@zynqmp:~$ xlnx-config -q

Hardware Platforms Present in the System: 

| PAC Cfg                       |Act| zcu102 Assets Directory
---------------------------------------------------------------------------------------------------------------
| test_platform-hello_world     |   | /boot/firmware/xlnx-config/test_pac/hwconfig/hello_world/zcu102
| test_platform-foo             |   | /boot/firmware/xlnx-config/test_pac/hwconfig/foo/zcu102
---------------------------------------------------------------------------------------------------------------

* No configuration is currently activated *

Since we're running on the ZCU102, only the ZCU102 boot assets are listed. The "Platform" column will report the name field from the manifest, and the "Assets Directory" will display the directory where the boot assets are located. The "Act" column will indicated if any of the listed platforms are active.

Now, we can activate the platform we want to use:

ubuntu@zynqmp:~$ sudo xlnx-config -a test_platform-hello_world

ubuntu@zynqmp:~$ sudo xlnx-config -a test_platform-hello_world
Activating assets for test_platform-hello_world on the zcu102
* Generating boot binary...
* Updating Multi-boot register
* Updating /var/lib/xlnx-config/active_board with zcu102

IMPORTANT: Please reboot the system for the changes to take effect.

As noted in the output, we must now reboot the board for the changes to take effect. Run the following command to reboot:

sudo reboot now

Once rebooted, we can query the system again and see that the test_platform-hello_world platform configuration is active:

ubuntu@zynqmp:~$ xlnx-config -q

Hardware Platforms Present in the System: 

| PAC Cfg                       |Act| zcu102 Assets Directory
---------------------------------------------------------------------------------------------------------------
| test_platform-hello_world     | * | /boot/firmware/xlnx-config/test_pac/hwconfig/hello_world/zcu102
| test_platform-foo             |   | /boot/firmware/xlnx-config/test_pac/hwconfig/foo/zcu102
---------------------------------------------------------------------------------------------------------------

Deactivating the Platform

To return to the golden image for the ZCU102, we can deactivate the current platform:

ubuntu@zynqmp:/boot/firmware/xlnx-config$ sudo xlnx-config -d

Deactivating test_platform-hello_world
* Reference /usr/lib/dpu.xclbin restored for zcu102
* Removed /boot/firmware/boot1020.bin
* Updating Multi-boot register

* IMPORTANT: Please reboot the system for the changes to take effect.

Again, for the changes to take effect, the system must be rebooted.

KV260 Usage Example

20.04/1.x track only

Please see Snaps - xlnx-nlp-smartvision Snap for Certified Ubuntu on Xilinx Devices for an example of using xlnx-config to load a snap-based accelerated application.

Important Files and Directories

File	Description
`/var/snap/xlnx-config/current/assets`	`xlnx-config` assets directory used to provide access to xclbin or other data files to consumer snaps
`/var/snap/xlnx-config/current/`	xlnx-config data directory where boards.txt is stored on each boot.
`/usr/lib/dpu.xclbin`	System `dpu.xclbin` for non-snap applications
`/usr/share/xlnx-firmware/zcu10[x]`	Golden boot assets for each ZCU10x board.
`/usr/share/xlnx-firmware/dpu-config.sh`	Script run during each boot to make sure `/usr/lib/dpu.xclbin` is linked to the right board specific dpu.xclbin in the zcu10x directory based on which board we're currently running on.
`/usr/local/share/xlnx-config/` `/boot/firmware/xlnx-config/`	Directories where manually installed custom PACs are searched for
`/var/lib/xlnx-config/manifest.yaml`	The manifest file for the currently activated boot assets
`/var/lib/xlnx-config/active_board`	Stores the board and assets directory of the currently activated boot assets
`/boot/firmware/`	Contents of the FAT boot partition
`/lib/firmware/xilinx/<aa name>`	Location of installed accelerated applications for KV260

Creating PACs for Vitis Accelerated Platforms

The PAC scheme can also be used to collect and deploy collateral related to a Vitis Accelerated Platform. Since the required contents can be dispersed in various places in the filesystem, the script below can automate collecting all of the contents into a properly formed PAC directory structure. The create_vitis_pac.sh script has been developed and tested against the 2020.2 tag of the Vitis Accel Examples repository.

NOTE: The create_vitis_pac.sh script is provided as-is.

#!/bin/bash

#functions and globals
VERSION='0.5' # current script version
REDTEXT='\e[31m'
BLUETEXT='\e[34m'
NCTEXT='\e[0m' # No Color

#the files that need to be copied from the Vitis platform into the container
bootFiles=("fsbl.elf" "bl31.elf" "pmufw.elf");
#the valid boards that work with this flow
validBoards=("zcu102" "zcu104" "zcu106" "zcu111" "zcu208" "zcu216");

bifFileName="bootgen.bif"
dtbFileName="system.dtb"
bitstreamFileName="system.bit"

#declare an array to contain all data files
#this is an array because the user can specify
#more than one item
DATAFILES=()

function print_version () {
	echo "Vitis Platform Assets Container (PAC) creation script, version $VERSION";
	exit 0;
}

function print_help () {
	echo -e "usage: $0 [options] \n \
	-c,--container	- Path to directory where the PAC is to be created, including name \n \
	-p,--platform	- Path to Vitis .xpfm file \n \
	-v,--vitis	- Path to the directory containing the Vitis application project (eg, contains build_dir.hw.<platform name>) \n \
	-n,--configname	- The configuration name inside the container \n \
	-b,--board	- Name of the board targer for this configuration \n \
	-d,--data	- (Optional) The complete path (including filename) of an item to include in the data directory \n \
	-x,--xclbin	- (Optional) The complete path (including filename) of an additional .xclbin file to include in the hwconfig directory \n \
	--version - (Optional) Echo the current script version";
}

if [[ $# -eq 0 ]]; then
	print_help;
	exit 0;
fi

while [[ $# -gt 0 ]]; do
  key="$1"

  case $key in
    -p|--platform)
      PLATFILEPATH="$2"
      shift # past argument
      shift # past value
      ;;
	-c|--container)
	  CONTAINERDIR="$2"
      shift # past argument
      shift # past value
      ;;
	-n|--configname)
	  CONFIGNAME="$2"
      shift # past argument
      shift # past value
      ;;	  
	-b|--board)
	  BOARDNAME="$2"
      shift # past argument
      shift # past value
      ;;	 
	-d|--data)	  
	  DATAFILES+=("$2")
      shift # past argument
      shift # past value
      ;;	
	-x|--xclbin)	  
	  XCLBIN+=("$2")
      shift # past argument
      shift # past value
      ;;
	-v|--vitis)	  
	  VITISPATH+=("$2")
      shift # past argument
      shift # past value
      ;;
    -h|--help)
      print_help;
	  exit 0;
	  ;;
    --version)
      print_version;
	  exit 0;
	  ;;
    *)    # unknown option
      echo "ERROR: Invalid argument specified"
	  exit 1;
      ;;
  esac
done

#check if the specified board is in the whitelist
validBoard=0;
for board in ${validBoards[@]}; do
	if [ "$board" == "$BOARDNAME" ]
	then
		validBoard=1;
	fi
done

# Check for missing/invalid required arguments
ERRORLEVEL=0;
if [ ! -v BOARDNAME ]
then
	echo "ERROR: No board name specified."
	ERRORLEVEL=$(expr $ERRORLEVEL + 1);
fi
if [ "$validBoard" -lt "1" ]
then
	echo "ERROR: Unsupported board $BOARDNAME"
	ERRORLEVEL=$(expr $ERRORLEVEL + 1);
fi
if [ ! -v CONTAINERDIR ]
then
	echo "ERROR: No PAC path specified."
	ERRORLEVEL=$(expr $ERRORLEVEL + 1);
fi
if [ ! -v PLATFILEPATH ]
then
	echo "ERROR: No Vitis hardware platform file specified."
	ERRORLEVEL=$(expr $ERRORLEVEL + 1);
fi
if [ ! -v CONFIGNAME ]
then
	echo "ERROR: Configuration name not specified."
	ERRORLEVEL=$(expr $ERRORLEVEL + 1);
fi
if [ ! -v VITISPATH ]
then
	echo "ERROR: Accelerated application location not specified."
	ERRORLEVEL=$(expr $ERRORLEVEL + 1);
fi
if [ "$ERRORLEVEL" -gt "0" ]
then
	exit 1;
fi

echo "Checking for Vitis platform collateral..."

echo "Checking for XPFM file..."
if [ ! -f $PLATFILEPATH ]
then
	echo "ERROR! XPFM not found at $PLATFILEPATH"
	exit 1;
else
	echo "FOUND at $PLATFILEPATH"
fi

echo "Checking for Vitis accelerated application directory..."
if [ ! -d $VITISPATH ]
then
	echo "ERROR! Vitis accelerated application not found at $VITISPATH"
	exit 1;
else
	echo "FOUND at $VITISPATH"
fi

# once the platform path location is confirmed, build the various paths
# for later use
PLATBASEPATH=$(echo ${PLATFILEPATH%/*})
PLATFILENAME=$(echo ${PLATFILEPATH##*/})
PLATNAME=$(echo ${PLATFILENAME%.*})

# determine the container name based on path
CONTAINERNAME=$(echo ${CONTAINERDIR##*/})

# check if some of the subdirectories and files exist
# this is part of the fail early mentality

# check for the sw subdirectory in the platform
echo "Checking for platform firmware directory..."
FIRMWAREDIR="$PLATBASEPATH/sw"
if [ ! -d $FIRMWAREDIR ]
then
	echo "ERROR: platform firmware directory not at $FIRMWAREDIR";
	echo "Is the platform directory structure correct/complete?"
	exit 1;
else
	echo "FOUND at $FIRMWAREDIR"
fi
echo " "
	
# check for the boot directory inside the software directory FIRMWAREDIR="$PLATBASEPATH/sw"
echo "Checking for platform boot collateral..."
BOOTDIR="$FIRMWAREDIR/$PLATNAME/boot"
if [ ! -d $BOOTDIR ]
then
	echo "ERROR: boot collateral directory not at $BOOTDIR";
	echo "Is the platform directory structure correct/complete?"
	exit 1;
else
	echo "FOUND at $BOOTDIR";
fi
echo " "

#check for the hardware configuration inside the accelerated application
echo "Checking for the accelerated application hardware configuration..."
APPHWBUILDDIR=$VITISPATH/build_dir.hw.$PLATNAME/
if [ ! -d $APPHWBUILDDIR ]
then
	echo "ERROR: Hardware build directory missing inside accelerated application $VITISPATH"
	echo "Have you build the hardware for the accelerated application?"
	exit 1;
else
	echo "FOUND at $APPHWBUILDDIR"
fi
echo " "

# start creating the PAC
echo "Building the xlnx-config PAC directory structure...";

# create the full path to the board-specific directory
echo -n "Creating the board directory inside the container..."
if [ ! -d $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME ]
then
	mkdir -p $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME
	echo "DONE"
	echo "Created at $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME"
else
	echo "DIRECTORY EXISTS"
	echo "Found at $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME"
fi
echo "Finished creating container directories"
echo " "

# populate the board-specific directory with files from the Vitis platform
echo "Copying boot files from Vitis platform into the container:"
for file in ${bootFiles[@]}; do
echo -n "Copying file $file..."
if [ -f $PLATBASEPATH/sw/$PLATNAME/boot/$file ]; then
	echo "DONE"
	cp -f $PLATBASEPATH/sw/$PLATNAME/boot/$file $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME
	
else
	echo "ERROR!"
	echo "The file $file does not exist at $PLATBASEPATH/sw/$PLATNAME/boot/"
	
fi
done

echo -n "Copying the device tree dtb file from the Vitis platform into the container..."
if [ -f $PLATBASEPATH/sw/$PLATNAME/xrt/image/$dtbFileName ]; then
	echo "DONE"
	cp -f $PLATBASEPATH/sw/$PLATNAME/xrt/image/$dtbFileName $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME
	
else
	echo "ERROR!"
	echo "The file $dtbFileName does not exist at $PLATBASEPATH/sw/$PLATNAME/xrt/image/"
	
fi
echo " "

echo -n "Copying the XCLBIN file for the Vitis accelerated application..."
shopt -s nullglob
if [[ -e $(echo $APPHWBUILDDIR/*.xclbin) ]]
then
	echo "DONE!"
	cp -f $APPHWBUILDDIR/*.xclbin $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME
else
	echo "ERROR!"
	echo "No XCLBIN file found at $APPHWBUILDDIR."
fi
echo " "

echo -n "Copying the bitstream file ($bitstreamFileName) for the Vitis accelerated application..."
if [ -f $APPHWBUILDDIR/link/int/$bitstreamFileName ]
then
	echo "DONE!"
	cp -f $APPHWBUILDDIR/link/int/$bitstreamFileName $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME
else
	echo "ERROR!"
	echo "No bitstream file found at $APPHWBUILDDIR/link/int/."
fi
echo " " 
####Add the code for copying the system.bit and xclbin from the Accelerated Application area


if [ -v XCLBIN ]
then
	echo -n "Copying additional XCLBIN file $XCLBIN..."
	echo "DONE!"
	
	cp -f $XCLBIN $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME
fi

echo "Finished populating boot files"
echo " "

# create the custom bif file
echo "Creating BootGen .BIF file for $CONFIGNAME/$BOARDNAME..."
echo -n "Checking for existing BIF file at $PLATBASEPATH/sw/$PLATNAME/boot/$bifFileName..."
if [ -f $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName ]; then
	echo "EXISTS!"
	echo "Removing the existing $bifFileName"
	rm -f $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName
else
	echo "NOT FOUND!"
fi
echo "Creating BIF file..."
echo "/* ubuntu boot image*/" > $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "the_ROM_image:" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "{" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "  [bootloader, destination_cpu=a53-0] fsbl.elf" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "  [pmufw_image] pmufw.elf" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "  [destination_device=pl] system.bit" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "  [destination_cpu=a53-0, exception_level=el-3, trustzone] bl31.elf" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "  [destination_cpu=a53-0, load=0x00100000] system.dtb" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "  [destination_cpu=a53-0, exception_level=el-2] /usr/lib/u-boot/xilinx_zynqmp_virt/u-boot.elf" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo "}" >> $CONTAINERDIR/hwconfig/$CONFIGNAME/$BOARDNAME/$bifFileName;
echo " "

# create the data_sw directory
if [ ${#DATAFILES[@]} -gt "0" ]
then

	echo -n "Creating the SW Data directory inside the container..."
	if [ ! -d $CONTAINERDIR/data/$CONFIGNAME/$BOARDNAME ]
	then
		mkdir -p $CONTAINERDIR/data/$CONFIGNAME/$BOARDNAME
		echo "DONE"
		echo "Created at $CONTAINERDIR/data/$CONFIGNAME/$BOARDNAME"
	else
		echo "DIRECTORY EXISTS"
		echo "Found at $CONTAINERDIR/data/$CONFIGNAME/$BOARDNAME"
	fi
	echo "Finished creating SW Data directory"
	
	echo "Copying SW data file $DATAFILES"
	for data in ${DATAFILES[@]}; do
		cp -f $data $CONTAINERDIR/data/$CONFIGNAME/$BOARDNAME
	done

else
	echo "No SW Data specified, skipping..."
fi
echo " "

# fix up the manifest.yaml file
echo "Updating the manifest.yaml file"
echo "Container: $CONTAINERNAME"
readarray -t configDirs < <(find $CONTAINERDIR/hwconfig -maxdepth 1 -type d -printf '%P\n')
for configDir in ${configDirs[@]}; do
echo "Configuration: $configDir"
	if [ -f "$CONTAINERDIR/hwconfig/$configDir/manifest.yaml" ]
	then
		echo "Removing old manifest.yaml file..."
		rm -f $CONTAINERDIR/hwconfig/$configDir/manifest.yaml
	fi
		
	touch $CONTAINERDIR/hwconfig/$configDir/manifest.yaml
	echo "name: $configDir" >> $CONTAINERDIR/hwconfig/$configDir/manifest.yaml;
	echo "description: Boot assets for the $configDir configuration inside the $CONTAINERNAME container" >> $CONTAINERDIR/hwconfig/$configDir/manifest.yaml;
	echo "revision: 1.0" >> $CONTAINERDIR/hwconfig/$configDir/manifest.yaml;
	echo "assets:" >> $CONTAINERDIR/hwconfig/$configDir/manifest.yaml;
		
	readarray -t boardDirs < <(find $CONTAINERDIR/hwconfig/$configDir -maxdepth 1 -type d -printf '%P\n')
	for boardDir in ${boardDirs[@]}; do
		echo "Board: $boardDir"
		echo -e "    $boardDir: $boardDir" >> $CONTAINERDIR/hwconfig/$configDir/manifest.yaml;
	done
	
done
echo " "

echo "########################################################"
echo " "
echo "Manifest updated at $configDir/manifest.yaml"
echo "Please review and update description & revision metadata"

echo " "
echo "All finished!"

Snap Release Notes

Date	Revision	Version	Notes

Date	Revision	Version	Notes
9/30/22	28	2.0	2.x track - 22.04 Updates
12/7/21	15	1.1	Added support for KV260
10/5/21	9	1.0	Added support for zcu111,zcu208, and zcu216
8/26/21	8	1.0	Added support for sysinit script
8/17/21	6	1.0	Initial Public Release

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

Table of Contents

Introduction

Platform Management

Xclbin Access for Snaps

Xilinx-specific System Initialization

Ubuntu 20.04 - 1.x Track

Ubuntu 22.04 - 2.x Track

Installation

Supported Options

xmutil Sub-Commands

Platform Assets Container

ZCU10x PAC

Kria SOM PAC

Format of the manifest file

Assets Directory

ZCU10x Assets

KV260 Assets

Run-Time Asset Management

Handling of the ZCU10x boot assets

Handling of dpu.xclbin for ZCU10x

Handling of the .xclbin for KV260

Snap Details

Snap Install Hook

One-Shot Daemon

xlnx-configd

ZCU10x Usage Example

Custom PAC Installation

Manual Installation

Snap Installation

Manifest Files

Boot Assets

Bootgen BIF File

Activating the Platform

Deactivating the Platform

KV260 Usage Example

Important Files and Directories

Creating PACs for Vitis Accelerated Platforms

Snap Release Notes

Related content