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 .
Xlnx-config is command line tool used to manage and manipulate the hardware platform for Xilinx ZCU102/4/6 boards running Certified Ubuntu 20.04 LTS for Xilinx Devices. Xlnx-config provides two main functions as detailed below.
The main purpose of the xlnx-config is to load custom hardware platforms (Targeted reference designs (TRDs), Vitis accelerated platforms, etc) for the ZC10x boards other than the standard standard platforms delivered as part of the Certified Ubuntu for Xilinx Devices Image. 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.
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, 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.
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 boo.
To install xlnx-config, you must include the --classic option since this is a classic confined snap:
|
Option | Description |
---|---|
--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:
|
--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). |
--get-board, -b: | returns the system's board model (currently, one of zcu102, zcu104 or zcu106). |
--force, -f | Use jointly with `-a` or `-d` to force activation/deactivation even if the configuration seems already correct. |
--deactivate, -d | Deactivates the currently active configuration, uninstalling its assets. After a reboot, the default boot assets for the board will be loaded. |
--is-active, -i | <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 |
xlnx-config.sysinit | Sub-application that installs Xilinx-specific gstreamer and video packages |
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 (config_1..N) in example below 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 diagram below shows what the platform directory structure would look like for a package with three unique configurations with assets for all three boards:
|
Manifest files will contain meta-information for a concrete 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:
|
Field details:
name: configuration name, usually the same as the application that needs it
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, and zcu216. The “assets directory” is typically named the same, but it can be unique.
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 config file used by xlnx-config to package new boot.bin |
| Zynq UltraScale+ First Stage Boot Loader (FSBL) |
| ARM Trusted Firmware (ATF) |
| Platform Management Unit (PMU) Firmware |
| The Programmable Logic bitstream |
| The Linux Device tree that matches the contents of the bitstream |
| The xclbin file that matches system.bit |
The |
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.
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.
Each of the three 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 platform has been activated, and the standard dpu.xclbin has been updated, the dpu-config.sh will not overwrite it. Upon deactivation of the platform, 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 three scenarios where xlnx-config
needs to make sure that the dpu.xclbin
in its assets directory is up to date:
Scenario | Action Taken |
---|---|
Initial snap install | The |
Reboot with Golden image |
|
Activation of new platform that includes |
|
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:
|
Before running an application that requires the DPU, the following env is set to point to the dpu.xclbin
being shared by the xlnx-config
snap:
|
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
:
|
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 platform in the system. If so, it will check /var/lib/xlnx-config/active_board
file to see if the platform was activated on a different board than we’re currently running on. If the boards are different, then the current platform will be deactivated.
In this example, we’ll examine the makeup of a platform, then walk through the process of activating and deactivating a simple test platform.
Custom platforms can be installed in two ways:
Manually install in the filesystem
Install as a platform snap
When using the manual install method, the platform archive must be copied into one of two places:
/boot/firmware/xlnx-config/<platform name>
/usr/local/share/xlnx-config/<platform name>
/boot/firmware is the mount point for the FAT partition of the SD card |
In this example, the platform name is "test platform". After copying the platform archive to the target board, it has been extracted into the /boot/firmware/xlnx-config/test_platform
directory. The platform 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_platform/ └── 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 |
When installing the platform as a platform snap using "sudo snap install <platform snap name>
," the contents of the platform will be found at the following location:
/snap/<platform snap name>/current/
The hwconfig
directory must, for example, be in the following location:
/snap/test_plaform/current/hwconfig
The manifest.yaml is parsed by xlnx-config to find out platform information. 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 |
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.
Typically, each platform 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]
Now that the platform is installed, xlnx-config -q
can be used to query the system and report any platforms available for the current boards:
ubuntu@zynqmp:~$ xlnx-config -q Hardware Platforms Present in the System: | Platform |Act| zcu102 Assets Directory --------------------------------------------------------------------------------------------------------------- | test_platform-hello_world | | /boot/firmware/xlnx-config/test_platform/hwconfig/hello_world/zcu102 | test_platform-foo | | /boot/firmware/xlnx-config/test_platform/hwconfig/foo/zcu102 --------------------------------------------------------------------------------------------------------------- * No configuration is currently activated * |
Since we're running on the ZCU102, only the ZCU102 platforms and 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: | Platform |Act| zcu102 Assets Directory --------------------------------------------------------------------------------------------------------------- | test_platform-hello_world | * | /boot/firmware/xlnx-config/test_platform/hwconfig/hello_world/zcu102 | test_platform-foo | | /boot/firmware/xlnx-config/test_platform/hwconfig/foo/zcu102 --------------------------------------------------------------------------------------------------------------- |
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.
File | Description |
|
|
| System |
| Golden boot assets for each ZCU10x board. |
| Script run during each boot to make sure |
| Directories where manually installed custom hardware platforms are searched for |
| The manifest file for the currently activated hardware platform |
| Stores the board and assets directory of the currently activated hardware platform |
| Contents of the FAT boot partition |
Date | Revision | Version | Notes |
---|---|---|---|
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 |