xbmgmt Utility

TIP: The next generation of the xbmgmt command-line tool is in preview mode for the 2020.2 release of XRT. This version will replace the current xbmgmt in a future release of XRT. Refer to https://xilinx.github.io/XRT/2020.2/html/xbmgmt2.html for information about the new utility.

Xilinx® Board Management (xbmgmt) utility is a standalone command line tool that is included with the Xilinx Runtime (XRT) installation package. The xbmgmt command supports both Alveo Data Center accelerator cards, and embedded processor-based platforms.

Accelerator cards are partitioned into a user function and a management function to provide different levels of card access. The user function allows end users to load and run their applications, while the management function is for system administrators to manage the card. The xbutil utility interacts with the user function. The xbmgmt utility, which requires root privilege, is for interacting with the management function. The reason for splitting the function access between the two utilities is to provide some security for the management features of the tool.

IMPORTANT: The xbmgmt utility only works with Alveo cards that have Xilinx provided shells/platforms. XRT does not work on custom Vivado® designs.

This utility is used for card installation and administration, and requires sudo privileges when running it. The xbmgmt supported tasks include flashing the card firmware, and scanning the current device configuration.

The xbmgmt command line format is:

xbmgmt <command> [options]

The supported sub-commands are given below.

config
Parse or update daemon/device configuration
flash
Update SC firmware or shell on the device
help
Print out help message for a sub-command
partition
Show and download partition onto the device
scan
List all detected mgmt PCIe® functions
version
Print out XRT build version
TIP: You can use the help command to list the available xbmgmt commands and options, and access help for individual commands by using the following:
xbmgmt help <command>
For detailed help of each sub-command, use the following:
xbmgmt help <subcommand>

Set up the xbmgmt command using the following scripts:

  • For csh shell:
    $ source /opt/xilinx/xrt/setup.csh
  • For bash shell:
    $ source /opt/xilinx/xrt/setup.sh

config

The xbmgmt config command lets you configure memory retention capability of the Alveo accelerator card.

Table 1. xbmgmt config Sub-commands
Sub-command Description
--enable_retention This feature preserves the contents of the DDR data during XCLBIN swapping in DFX-2RP target platforms.
--disable_retention This feature disables the retention of the contents of the DDR data during XCLBIN swapping in DFX-2RP target platforms.

The config command has the following command line options.

sudo xbmgmt config --enable_retention --ddr [--card <bdf>]
Table 2. xbmgmt config Sub-Command Options
Option Description Required
--ddr Enable or disable retention of the contents of the DDR memory. Y
--card <bdf> Specifies the accelerator card to be configured as identified by its Bus:Device:Function (BDF) tag.
TIP: Use the xbmgmt flash --scan to obtain the card BDF.
If the BDF is not found, you will receive the following message where <bdf> is the BDF value entered:
ERROR: No mgmt PF found for <bdf>
N

flash

IMPORTANT: This option cannot be used with embedded processor platforms.

The flash command has three sub-commands which are described in the following table.

The xbmgmt flash --scan command will report if a platform base is loaded. You will need to use xbmgmt partition --scan to see if the shell is loaded. Refer to Alveo Platform Loading Overview for more information on the platform base and shell.

Table 3. xbmgmt flash Sub-commands
Sub-command Description
--scan Query the card's flashable partition running on FPGA and installed on the host system
--update Flash a target platform (flashable partition) to the card
--factory_reset Reset the card to factory condition

Each of the sub-commands are detailed below.

--scan

The --scan sub-command returns details of the flashable partition installed on each card along with the flashable partitions installed on the host system. In addition, it also returns additional information including SC version, BDF, Serial number, and MAC addresses.

It has the following command line format.

xbmgmt flash --scan [--verbose | --json]
Table 4. xbmgmt flash --scan Sub-command Options
Option Description Required
--verbose Returns verbose output which includes additional fields.

The --verbose and --json options are mutually exclusive.

N
--json Returns all fields given with --verbose option in JSON format.

The --verbose and --json options are mutually exclusive.

N

Using the flash --scan sub-command without any options, as shown below, will return the fields listed in the following table.

xbmgmt flash --scan
Table 5. xbmgmt flash --scan Field Definition
Field Description
Card Provides the enumerated card Bus Device Function (BDF) for the card in the following format:

[Bus : Device : Function]

TIP: The xbmgmt command returns a BDF which includes the management function on the card. The xbutil scan command returns a BDF which includes the user function on the card.
Card type Xilinx card type
Flash type Returns the flash type physically installed on the card. The flash type can be:
  • Dual QSPI: Two x4 SPI
  • SPI: One x4 SPI
  • OSPI: One x8 SPI
Flashable partition running on FPGA Returns details on the flashable partition installed on the card:
  • Name of the target platform running on the FPGA
  • ID unique identification of the platform bitstream
  • Satellite Controller (SC) version number
IMPORTANT: Flashable partition running on FPGA's ID must match the flashable partitions installed in system or the stack will not operate correctly.
Flashable partitions installed in system Returns details on the flashable partition installed on the host system:
  • Name of the target platform running installed on the host system
  • ID which represents the timestamp of the target platform
  • SC version number
Below is an example output of xbmgmt flash --scan for a system with two different cards installed:
Card [0000:a6:00.0]
    Card type:          u280
    Flash type:         SPI
    Flashable partition running on FPGA:
        xilinx_u280_xdma_201920_1,[ID=0x5da8da6e],[SC=4.3.4]
    Flashable partitions installed in system:
        xilinx_u280_xdma_201920_1,[ID=0x5da8da6e],[SC=4.3.4]
 
Card [0000:73:00.0]
    Card type:          u250
    Flash type:         SPI
    Flashable partition running on FPGA:
        xilinx_u250_xdma_201830_2,[ID=0x5d14fbe6],[SC=4.3.7]
    Flashable partitions installed in system:
        xilinx_u250_xdma_201830_2,[ID=0x5d14fbe6],[SC=4.3.7]

If a card has been installed for the first time and not previously been flashed, or if the card has been factory reset the flashable partition running on FPGA will indicate this with the word GOLDEN within its name as shown in --factory_reset.

Using the --verbose option, as shown in the following example, returns additional fields specified in the following table.

Note: A platform has to be installed on the system to obtain the full card information.
xbmgmt flash --scan --verbose
Table 6. xbmgmt flash --scan --verbose Field Definition
Field Description
Card Name Xilinx provided card name
Card serial number (S/N) Unique card serial number
Configuration mode Returns the configuration mode in which FPGA boots up from a cold reset. The configuration modes can be:
  • Dual QSPI: Two x4 SPI
  • QSPI: One x4 SPI
  • OSPI: One x8 SPI
Fan presence Represents the presence of a fan on the card.

A – Active cooling. Fan is present on card.

P – Passive cooling. Fan is not present on the card and must be cooled by host server.

Max power level Maximum available card power (Watts) supplied from PCIe and connected AUX power port. Not all cards have an AUX power port.
MAC address Returns a list of Xilinx assigned MAC addresses for the card.

You are free to use Xilinx assigned MAC address or provide your own.

An address of FF:FF:FF:FF:FF:FF implies this MAC slot has not been assigned an address.

An example of the xbmgmt flash --scan --verbose output for a system with one card is given below:

Card [0000:a6:00.0]
    Card type:          u280
    Flash type:         SPI
    Flashable partition running on FPGA:
        xilinx_u280_xdma_201920_1,[ID=0x5da8da6e],[SC=4.3.4]
    Flashable partitions installed in system:
        xilinx_u280_xdma_201920_1,[ID=0x5da8da6e],[SC=4.3.4]
    Card name                   ALVEO U280 PQ
    Card S/N:                   21760394R01L
    Config mode:                7
    Fan presence:               A
    Max power level:            225W
    MAC address0:               00:0A:35:06:00:0A
    MAC address1:               00:0A:35:06:00:0B
    MAC address2:               FF:FF:FF:FF:FF:FF
    MAC address3:               FF:FF:FF:FF:FF:FF

Using the --json sub-option returns similar information as xbmgmt flash --scan, but in JSON format. The following shows an example of the generated JSON output for a system with one card.

{
    "card0": {
        "shellpackage": "xilinx_u280_xdma_201920_1,[ID=0x5da8da6e],[SC=4.3.4]; ",
        "name": "ALVEO U280 PQ",
        "serial": "21760394R01L",
        "config_mode": "7",
        "fan_presence": "A",
        "max_power": "225W",
        "mac0": "00:0A:35:06:00:0A",
        "mac1": "00:0A:35:06:00:0B",
        "mac2": "FF:FF:FF:FF:FF:FF",
        "mac3": "FF:FF:FF:FF:FF:FF"
    }
}

--update

Use the flash --update sub-command to change the flashable partition (target platform) on the card. It does this by flashing the specified target platform and associated satellite controller to the configurable ROM on the card. It has the following command line format:

xbmgmt flash --update [--shell <target_platform_name> 
[--id <target_platform_id>]] [--card <bdf] [–force]

The following table lists the available options.

Table 7. xbmgmt --update Sub-Command Options
Option Description Required
--shell <target_platform_name>

[--id]

Name of the target platform (flashable partition) to be flashed on the card. The target platform must be installed on the host system prior to specifying it via the target platform installation package. See the Alveo™ card installation guide for details on downloading and installing the deployment target platform. Use the xbmgmt flash --scan to list available target platforms installed on the host system.

If neither the --shell and --card options are specified, all cards will be flashed with the compatible target platform if available on the host system.

For instance, if your system has U200 and U250 cards installed and both U200 and U250 target platforms exist on the host system, then both cards will be flashed with their respective target platforms. If a card's target platform does not exist on the system, then the card will not be flashed.

If the --shell option is specified, but the --card option is not, then all cards compatible with the specified target_platform_name will be flashed. For instance, if your system has two U200 cards installed, then both cards will be flashed with the specified target_platform_name. If a card's target platform does not exist on the system, then the card will not be flashed.

If the --shell option is not specified, but the --card option is specified, the specified card will be flashed with the compatible target platform if available on the host system.

If both the --shell and --card options are specified, the specified card will be flashed with the specified target platform if available on the host system.

If the flashable partition on the card matches the flashable partition on the system, a similar message as shown below will be displayed and the card will not be updated. However, you can force the card to be flashed by using the --force option described below.

Card [0000:65:00.0]: 
Status: shell is up-to-date 
Card(s) up-to-date and do not need to be flashed.

If the specified target_platform_name is not installed on the host system, the card will not be updated and you will receive the following message:
Specified shell not found.

This --id sub-option specifies the ID of the target platform.

Use the xbmgmt flash --scan to obtain the ID of the flashable partition.

If the --id option is not specified, the card will be updated with the latest released target platform available on the host system.

N
--card <bdf> Specifies the accelerator card to be updated as identified by its Bus:Device:Function (BDF) tag. Use the xbmgmt flash --scan to obtain the card BDF.

If --card is not specified, then all accelerator cards in the system compatible with the specified target_platform will be updated.

If neither the --shell and --card options are specified, all cards will be flashed with the compatible target platform if available on the host system. For instance, if your system has U200 and U250 cards installed and both U200 and U250 target platforms exist on the host system, then both cards will be flashed with their respective target platforms. If a card's target platform does not exist on the system, then the card will not be flashed.

If the --shell option is specified, but the --card option is not, then all cards compatible with the specified target_platform_name will be flashed.

For instance, if your system has two U200 cards installed, then both cards will be flashed with the specified target_platform_name. If a card's target platform does not exist on the system, then the card will not be flashed.

If the --shell option is not specified, but the --card option is specified, the specified card will be flashed with the compatible target platform if available on the host system.

If both the --shell and --card options are specified, the specified card will be flashed with the specified target platform if available on the host system.

If the BDF is not found, you will receive the following message where <bdf> is the BDF value entered. Use the xbmgmt flash --scan to list the BDF values of installed cards.

ERROR: No mgmt PF found for <bdf>
N
--force

The force option means "yes" to any prompt from xbmgmt flash --update command.

For instance, when flashing the card through xbmgmt flash --update, it will confirm that you wish to perform the update with the following prompt:

Are you sure you wish to proceed? [y/n]:

The --force option will automatically set the answer to "y" or yes, and proceed.

N

--factory_reset

Use the flash --factory_reset sub-command to restore the flashable partition running on the FPGA to the original golden image. This command will not change the satellite controller version. It has the following command line format:

xbmgmt flash --factory_reset [--card <bdf>]

There is only one option and is given in the following table.

Table 8. xbmgmt --factory_reset Sub-Command Options
Option Description Required
--card <bdf> Specifies the accelerator card to be factory reset as identified by its Bus:Device:Function (BDF) tag.

Use the xbmgmt flash --scan to obtain the card BDF.

If --card is not specified, then the card ID 0 will be reset. Card ID is not deterministic and can change after a cold or warm reboot.

N

After running the xbmgmt flash --factory_reset command, it is necessary to cold-reboot the system to restore the card to the original golden image.

After a factory reset and cold rebooting, use xbmgmt flash --scan to confirm the flashable partition running on FPGA has been reverted. The partition will include the word GOLDEN within its name as shown below:

Card [0000:a6:00.0]
    Card type:          u280
    Flash type:         SPI
    Flashable partition running on FPGA:
        xilinx_u280_GOLDEN_8,[SC=4.3]
    Flashable partitions installed in system:
        xilinx_u280_xdma_201920_1,[ID=0x5da8da6e],[SC=4.3.4]

partition

The xbmgmt partition command lets you display and program shell partitions to the Alveo card.

The partition command is intended to be used with DFX-2RP platforms. Prior to running an application, including the validation application, it is necessary to first program the shell partition to the card using the following command:
sudo /opt/xilinx/xrt/bin/xbmgmt partition --program --name <shell_name> --
card <card_bdf>

After the shell partition is programmed, you do not need to reprogram the accelerator card unless the system is warm or cold rebooted, or to load a different shell.

TIP: The platform base remains loaded even when the power is cycled on the accelerator card.

The xbmgmt partition --scan command reports if a platform shell has been loaded.

Table 9. xbmgmt partition Sub-commands
Sub-command Description
--scan Scan and displays base and shell partitions running on the FPGA and installed in the system.
--program This command is used to program the shell partition by providing the name of the shell partition. The command also supports the option to program the shell from a given interface-uuid.

Scan

The --scan sub-command returns details of the flashable partition installed on each card along with the flashable partitions installed on the host system. In addition, it also returns additional information including SC version, BDF, Serial number, and MAC addresses.

It has the following command line format.

xbmgmt partition -–scan

The following is an example of the command output:

Card [0000:d8:00.0]
    Partitions running on FPGA:
        xilinx_u200_gen3x16_base_1
            logic-uuid:
            8892e9a0478feaa2699f5df1f696470d
            interface-uuid:
            1641962866f4b5e579cec90a6bdabcbf
    Partitions installed in system:
        xilinx_u200_gen3x16_xdma_shell_1_1
            logic-uuid:
            a21db155d2fbd60ccc95eea0ea8144e1
            interface-uuid:
            9437e0f859a4d9bd9e226d7edf5e6be8

If the partition is programmed, the output will look like the following example output below.

alveo@alveo:~$ sudo /opt/xilinx/xrt/bin/xbmgmt partition --scan
Card [0000:65:00.0]
    Partitions running on FPGA:
        xilinx_u200_gen3x16_base_1
            logic-uuid:
            3d40702f37777396cc82e0df89bafde2
            interface-uuid:
            19f21ba41b9c38dffefc1ee68910b8bb
        xilinx_u200_gen3x16_xdma_shell_1_1
            logic-uuid:
            fd19b2fde5a10b8cb89e35b0be02f274
            interface-uuid:
            995b41d8c729d658d6700a027f412f78
    Partitions installed in system:
        xilinx_u200_gen3x16_xdma_shell_1_1
            logic-uuid:
            fd19b2fde5a10b8cb89e35b0be02f274
            interface-uuid:
            995b41d8c729d658d6700a027f412f78

Program

The --program sub-command lets you program the specified shell partition.

It has the following command line format.

xbmgmt partition --program --name name [--id interface-uuid] [--card bdf]
Table 10. xbmgmt --program Sub-Command Options
Option Description Required
--name <name> Specify the name of the shell partition to program.

Use the xbmgmt partition --scan to display the names of the programmable partitions.

Y
--id The --id sub-option specifies the partition interface-uuid.

Use the xbmgmt partition --scan to obtain the ID of the flashable partition.

N
--card <bdf> Specifies the accelerator card to be programmed as identified by its Bus:Device:Function (BDF) tag.

Use the xbmgmt partition --scan to obtain the card BDF.

If the BDF is not found, you will receive the following message where <bdf> is the BDF value entered:
ERROR: No mgmt PF found for <bdf>
N

scan (xbmgmt)

IMPORTANT: This option cannot be used with embedded processor platforms.

The xbmgmt scan command returns a list of all the detected management PCIe functions. Each item in the list includes the card BDF, target platform name, target platform ID, and management driver instance number.

TIP: If additional details are needed, use the xbmgmt flash --scan --verbose command.

It has the following command line format. There are no options.

xbmgmt scan

The following table lists the fields returned from xbmgmt scan command.

Table 11. xbmgmt scan Field Definition
Field Description
BDF Provides the enumerated Bus:Device:Function (BDF) identifier for the card in the following format:

[Bus:Device:Function]

Flashable partition running on FPGA Details on the flashable partition include:
  • Name of the target platform flashed on the FPGA
  • Unique ID associated with the target platform.
mgmt Returns the assigned management driver instance.

The instance number can easily find the device node for each function.

On a supported Linux distribution, the device node can be found at: /dev/xclmgmt<inst>.

In addition, the instance can be useful when mapping the dmesg information to a specific card.

Below is an example output of xbmgmt scan for a system with two cards installed. Details for each card are on a separate line:

0000:d8:00.0 xilinx_u200_gen3x16_xdma_shell_1_1 mgmt(inst=55296)
 0000:af:00.0 xilinx_u250_gen3x16_base_3 mgmt(inst=44800)

version

IMPORTANT: This option cannot be used with embedded processor platforms.

The version command returns the XRT build version details. It is identical to the xbutil version command. It has the following command line format. There are no options.

xbmgmt version

The following table lists the fields returned from xbmgmt version command.

Table 12. Version Field Definition
Field Description
XRT Build Version XRT build version
Build Version Branch Build version branch
Build Version Hash Build version hash
Build Version Hash Date Build version branch date
Build Version Date Build version date
XOCL XOCL version
XCLMGMT XCLMGMT version

The following is an example output of xbmgmt version.

      XRT Build Version: 2.3.1301
   Build Version Branch: 2019.2
     Build Version Hash: 192e706aea53163a04c574f9b3fe9ed76b6ca471
Build Version Hash Date: Thu, 24 Oct 2019 19:27:30 -0700
     Build Version Date: Thu, 24 Oct 2019 20:04:29 -0700
                   XOCL: 2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471
                XCLMGMT: 2.3.1301,192e706aea53163a04c574f9b3fe9ed76b6ca471