MLXBF-BOOTCTL(8)

NAME
mlxbf-bootctl - control Mellanox BlueField boot partitions

SYNOPSIS
mlxbf-bootctl [-h|--help] [options]

DESCRIPTION
mlxbf-bootctl is used to control the two boot firmware partitions present on most Mellanox BlueField devices.

  Boot Partitions
Most Bluefield devices obtain their boot firmware (ATF, UEFI, etc) from an on-board Embedded Multi-Media Card (eMMC). The eMMC has two partitions that are treated separately from the others: boot0 and boot1, one of which acts as the primary, the other acting as a backup. In addition, there is a watchdog timer present on the chip, which when activated, will automatically swap which boot partition is active if it is not deactivated in time. These two features, taken together, allow for safe BlueField firmware upgrades that may rolled back in case of failure. mlxbf-bootctl controls these features. If mlxbf-bootctl is run without options, it will print the current state of the boot partitions.

OPTIONS

--device|-d MMCFILE
    Use a device other than the default /dev/mmcblk0

--bootstream|-b BFBFILE
    Write the specified bootstream to the alternate partition of the device. This queries the base device (e.g. /dev/mmcblk0 ) for the alternate partition, and uses that information to open the appropriate boot partition device, e.g. the /dev/mmcblk0boot0 file. BFB files that can be installed in the boot partitions are typically named "default.bfb" in BlueField software distributions.

--overwrite-current
    Used with "--bootstream" to overwrite the current boot partition instead of the alternate one. This is not recommended as there is no easy way to recover if the new boot code does not bring the system up.

--output|-o OUTPUT
    Used with "--bootstream" to specify a file to write the boot partition data to (creating it if necessary), rather than using an existing master device and deriving the boot partition device.

--read|-r INPUT
    Read a bootstream and convert it back to a BFBFILE specified by "--bootstream". For example use
    mlxbf-bootctl --read /dev/mmcblk0boot0

    --bootstream current.bfb

    to read the current bfb installed on boot partition zero.

--watchdog-swap SECONDS
    Arrange to start the ARM watchdog with a countdown of the specified number of seconds until it firms; also, set the boot software so that it will swap the primary and alternate partitions at the next reset. Mutually exclusive with "--nowatchdog-swap".

--nowatchdog-swap
    Ensure that after the next reset, no watchdog will be started, and no swapping of boot partitions will happen.

--swap|-s
    Set the boot software so that will swap the primary and alternate partitions at the next reset.

--version|-v
    Override automatic image version filtering. By default, when -v is not specifed, image versions contained in the bootstream will not be installed to the boot partition if they are incompatible with the current BlueField platform. -v allows you to manually specify the target version. Version 0 corresponds to BF-1, version 1 to BF-2, and so on. Version -1, or any version less than zero, will turn off image filtering entirely.

EXAMPLES
To update to new firmware as safely as possible:

    mlxbf-bootctl --bootstream new.bfb --watchdog-swap 90

Once the new firmware is confirmed to be good, turn off watchdog swapping with

    mlxbf-bootctl --nowatchdog-swap

COMMON ISSUES
When the watchdog timer is activated through the "--watchdog-swap" option, entering the UEFI menu for long enough will trigger a reboot and partition swap. To avoid this, run "--nowatchdog-swap" before entering the UEFI menu.