flash - 2021.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2022-03-29
Version
2021.2 English
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 1. 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 2. 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 3. 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 4. 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 5. 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 6. 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]