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

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 (config_1..N) in example below 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] 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.

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

Code Block

<platform<PAC name>Name>
 | 
 |--<data/sw directory>[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>

...

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:

Code Block
name: <configuration/application name><configuration> description: <full description> revision: <number> assets: zcuXXX: <assets directory>

...

name: configuration name, usually the same as the application that needs itparent 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, and zcu216. The “assets directory” is typically named the same, but it can be unique.

...

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)

Info
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`)

...

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 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 platformcustom boot assets, xlnx-config will restore the link back to the the proper board-specific dpu.xclbin.

...

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 platform PAC boot assets that includes `dpu.xclbin`	`xlnx-config` copies the new `dpu.xclbin` to the assets directory as part of the activation process.

...

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

...

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 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 platform was assets were activated on a different board than we’re currently running on. If the boards are different, then the current platform set of boot assets will be deactivated.

Usage Example

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

Custom

...

PAC Installation

Custom platforms PACs can be installed in two ways:

Manually install in the filesystem
Install as a platform PAC snap

Manual Installation

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

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

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

In this example, the platform PAC name is "test platform_pac". After copying the platform PAC archive to the target board, it has been extracted into the /boot/firmware/xlnx-config/test_platformpac directory. The platform 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:

Code Block

test_platformpac/
└── 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 platform PAC as a platform PAC snap using "sudo snap install <platform <PAC snap name>," the contents of the platform PAC will be found at the following location:

/snap/<platform <PAC snap name>/current/

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

/snap/test_plaformpac/current/hwconfig

Manifest Files

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

...

Bootgen BIF File

Typically, each platform 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:

...

Activating the Platform

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

Code Block

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_platformpac/hwconfig/hello_world/zcu102
| test_platform-foo             |   | /boot/firmware/xlnx-config/test_platformpac/hwconfig/foo/zcu102
---------------------------------------------------------------------------------------------------------------

* No configuration is currently activated *

...

Since we're running on the ZCU102, only the ZCU102 platforms and 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.

...

Code Block

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_platformpac/hwconfig/hello_world/zcu102
| test_platform-foo             |   | /boot/firmware/xlnx-config/test_platformpac/hwconfig/foo/zcu102
---------------------------------------------------------------------------------------------------------------

...

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
`/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 hardware platforms PACs are searched for
`/var/lib/xlnx-config/manifest.yaml`	The manifest file for the currently activated hardware platformboot assets
`/var/lib/xlnx-config/active_board`	Stores the board and assets directory of the currently activated hardware platformboot assets
`/boot/firmware/`	Contents of the FAT boot partition

...

Versions Compared

Old Version 25

New Version 26

Key

Platform Assets

Container

Usage Example

Custom

PAC Installation

Manual Installation

Snap Installation

Manifest Files

Bootgen BIF File

Activating the Platform

Page Comparison

Versions Compared

Old Version 25

New Version 26

Key

Platform Assets

Container

Usage Example

Custom

PAC Installation

Manual Installation

Snap Installation

Manifest Files

Bootgen BIF File

Activating the Platform