xbmgmt Utility - Legacy

TIP: This describes the legacy version of the xbmgmt command that can be accessed by calling the xbmgmt --legacy command.

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

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