Skip to content

ha-fw-update

ha-fw-update is a tool that writes a new firmware image to the boot flash of a card and hot-resets the card so that it boots with the new firmware. This page defines the install location, arguments and options, pre-flight checks, screen output, exit codes, JSON output, image requirements, and the reset command. When and in what order to use the tool, and how to respond to a failure, are covered in Firmware update.


Install location

ha-fw-update is installed to /usr/bin/ha-fw-update by the hyperdriver-dkms driver package. It is installed together with ha-hotreset (/usr/bin/ha-hotreset) and is removed together with the driver (when the package is removed). The installation procedure is in Installation.

Requirements:

  • root privileges
  • Python 3.7 or later. It uses only the standard library. The tool runs with the python3 on PATH, so if python3 --version reports a version lower than 3.7, run it directly with an interpreter 3.7 or later (for example, sudo python3.9 /usr/bin/ha-fw-update ...)
  • The reset step needs a reset command, and ha-hotreset uses pciutils (lspci, setpci)

Synopsis

1
2
sudo ha-fw-update (-d BDF | -i N) [--scope full|app] [--rewrite] [-y] [--dry-run]
                  [--no-reset] [--force] [--hotreset PATH] [--boot-timeout SEC] [--json] IMAGE

ha-fw-update --help prints the safety notes (SAFETY) and the exit codes (EXIT CODES) along with the options.


Arguments and options

Argument or option Default Meaning
IMAGE Required Path of the image file to write. See Image file
-d BDF, --bdf BDF None PCI address of the card. Use the Bus-Id value of hyperaccel-smi (0000:01:00.0) as is. See Specifying the card
-i N, --index N None The number N of /dev/haN. It can change after a hot reset or after a card is added, so -d is recommended
--scope full, --scope app full Range to write. full writes from the start of the flash for the size of the image, that is, the whole image. app writes only the range of some partitions of the image (firmware application, FIP)
--rewrite Off Erases and rewrites every sector in the range without comparing it with the flash. When off, only the parts whose contents differ from the flash are written, and an identical image finishes almost immediately
-y, --yes Off Skips the confirmation prompt
--dry-run Off Runs only the pre-flight checks and writes nothing
--no-reset Off Writes only the flash and skips the reset and verify steps. The card keeps running the previous firmware until it restarts (hot reset, host reboot, power cycle)
--force Off Proceeds even if another process has /dev/haN open. --no-reset must be given with it (Option combinations)
--hotreset PATH The search order in Reset command Path of the command to run in the reset step
--boot-timeout SEC 60 How long to wait for the card to come back after the reset (seconds, integer). If 0 or less, the tool does not wait, so the verify step ends with exit code 6
--json Off Prints a single result JSON to standard output instead of the screen output
-h, --help None Prints the help and ends

Exactly one of -d and -i must be given.

Specifying the card

  • The value of -d is hexadecimal in the format dddd:bb:dd.f (domain🚌device.function) and is case-insensitive.
  • If only one HyperAccel card across all PCI domains has that bb:dd.f, you can omit the domain and write just bb:dd.f. If cards with the same bb:dd.f exist in several domains, the tool shows the candidates and ends with exit code 2.
  • If the format is wrong, the tool ends with exit code 1. If there is no card at that address, it shows the list of cards that exist and ends with exit code 2.
  • With -i N, the tool checks that /dev/haN and the PCI address of that card exist. If they do not, the exit code is 2.

Option combinations

Combination Result
Both -d and -i given, or neither Command-line syntax error. Exit code 2
--json with neither -y nor --dry-run Exit code 1. This is because the tool cannot show the warning and the prompt
Another process has the card open and --force is not given Exit code 2
Another process has the card open and only --force is given Exit code 2, before the flash is written. This is because ha-hotreset does not reset a card that has an open handle
Another process has the card open and --force --no-reset is given Prints a warning and proceeds. After that process ends, run ha-hotreset --bdf <BDF> yourself
No other process has the card open and --force is given It has no effect
--no-reset together with --hotreset or --boot-timeout --hotreset and --boot-timeout are not used
--scope app with a 16 MiB image Exit code 3

Confirmation prompt

After printing the summary, the tool prints Proceed? [y/N] to standard error and reads the answer from standard input. With -y or --dry-run, it does not ask.

  • y or yes (case-insensitive) proceeds.
  • Any other input, an empty line, or end of input (EOF) prints ERROR: aborted and ends with exit code 1. Nothing is written.
  • The prompt goes to standard error (stderr), so it is visible on the screen even if you redirect standard output (stdout) to a file.

Pre-flight checks

The checks run in the following order, and if any one fails, the tool ends without writing anything to the flash.

Order Check On failure
1 Command-line values: the format of -d, and the combination of --json with -y and --dry-run Exit code 1
2 root privileges Exit code 1
3 The image file can be read Exit code 1
4 The image's format and size, and their combination with the range (Image file). If these pass, the CRC-32 of the whole image is calculated Exit code 3
5 The card exists (that PCI address for -d, /dev/haN for -i) Exit code 2
6 No other ha-fw-update is running on the same card Exit code 2
7 The sysfs fw_version is not unknown Exit code 2
8 No other process has /dev/haN open Exit code 2. See --force in Option combinations
9 The reset command exists and can be run (skipped with --no-reset). If the parent port is not a root port, only a warning is printed Exit code 1
10 /dev/haN can be opened and card memory to upload the image into can be allocated. The tool checks here whether the card can accept requests Exit code 2

--dry-run completes up to check 10, prints the summary and Dry run: nothing written., and ends with exit code 0. The card memory that was allocated is returned when the tool exits.


Screen output

Summary

When the pre-flight checks pass, the tool prints the following lines.

Line Content
Device Node name, PCI address, current firmware version
Image Image path, size (bytes), kind (gpt or full-flash), CRC-32
Scope Flash range to write. For full, it is full -> flash 0x000000-<end address>; for app, it is the range and size (KiB) of the fip partition. With --rewrite, (rewrite all sectors) is appended. For a 16 MiB image, (16 MiB image: the TPDS region at 0x800000 is overwritten too) appears on the next line, telling you that the TPDS region at 0x800000 is overwritten as well
Estimate device timeout: the ceiling (in seconds) on how long the driver waits for a response from the firmware. It is the deadline determined by the image size plus the default value (12 seconds) of the module parameter ha_devcmd_ceiling_ms, so if you have changed this parameter, the actual ceiling differs accordingly. It is not an estimate of the time required
Reset Reset method. It is SBR via <command name> (parent is a root port) or (parent is NOT a root port), and with --no-reset it is skipped (--no-reset)
WARNING: Do not power off or reboot this host during the update. Recovery requires a debug tool (e.g., Trace32). A notice not to power off or reboot during the update

Steps

Line Content On failure
[1/5] Pre-flight Indicates that all pre-flight checks passed Not applicable
[2/5] Upload Copies the image to card memory. Shows the size (MiB) and the time taken Exit code 2 or 3
[3/5] Flash (device) Waits until the firmware finishes the image check, flash comparison, write, and read-back verification. When done, shows the time taken and <completed sectors>/<total sectors> sectors Exit code 2, 3, or 4
[4/5] Reset (SBR) Closes /dev/haN and runs the reset command. With --no-reset, shows skipped (--no-reset) together with the ha-hotreset command to run later, and ends Exit code 5
[5/5] Verify Waits at 1-second intervals, for up to --boot-timeout, until the node at the same PCI address reports fw_version, and shows firmware <previous> -> <new> (haN) Exit code 6

Progress

During [3/5], if standard output is a terminal, the tool keeps redrawing the same line. Depending on the situation, it takes one of the following formats.

1
2
3
[3/5] Flash (device) ...  43%  (289/672 sectors)  2 s
[3/5] Flash (device) ... ~34%  (elapsed 5 s of ~14 s, estimate)
[3/5] Flash (device) ... 3 s
  • First line: the progress read from sysfs fw_update_progress. Sectors are in 4 KiB units, and sectors that were skipped because they match the flash are also counted as done.
  • Second line: the case where the progress cannot be read and --rewrite was given. It is an estimate calculated from the image size, not the progress.
  • Third line: the elapsed time in the case where the progress cannot be read.

Before the firmware starts writing, fw_update_progress is 0 0, so the display uses the second or third format, and it changes to the first format once writing starts.

If the progress could not be read even once during [3/5], no progress counter (old firmware) appears in place of the sector count when the step ends. If standard output is not a terminal, the tool does not redraw and prints only the step name once, and with --json it draws nothing.

Warnings

Warning Meaning
WARNING: /dev/haN is open by pid(s) <PID> (--force --no-reset): reset it yourself after closing them The tool proceeds with --force --no-reset. After those processes end, you must reset the card yourself
WARNING: <BDF> is not directly under a root port; if the parent port leaves Surprise Down unmasked, ha-hotreset masks the switch path for the SBR, and where it cannot, the new image needs a power cycle The parent port is not a root port. If that port does not mask the Surprise Down error, ha-hotreset masks the path and resets the card in the reset step. If the path cannot be masked, the reset is refused, so booting the new image needs a power cycle. Check whether the card can be reset with sudo ha-hotreset --list
WARNING: same version -- confirm the new image on the UART boot log. The version numbers before and after the update are the same. The result is success (exit code 0). A release firmware image does not print its version on the UART, so the UART boot log cannot show which image is running. Identify the image by the file you wrote. See Verifying that the card booted the new firmware

Exit codes

Code Meaning Flash Typical causes
0 Success New image (not changed with --dry-run) The update, reset, and verification all completed (including the same version warning). --dry-run passed. Only the flash was updated with --no-reset
1 Usage or environment problem Not changed by this run -d format error, --json without -y or --dry-run, not root, the image file could not be read, no reset command, declined at the prompt, Ctrl+C pressed before [3/5]
2 The card cannot be used, or the update is not supported Not changed by this run No card, another update on the same card, fw_version is unknown, another process has the card open, the card is not ready or cannot accept commands, out of card memory, the driver is waiting for a response to an earlier update (upload failed: Device or resource busy), the running firmware or driver does not support the update, the firmware aborted before writing, the firmware could not read the flash, command-line syntax error
3 Image rejected Not changed by this run The tool's image check, the firmware's image check (GPT, CRC), the fip partition layout in the flash differs from the image (rerun with --scope full), request arguments rejected
4 Write failed or state unknown May be partially written The firmware's write or read-back verification failed, the firmware did not respond within the set time, the card stopped responding during the update, other errors that the tool could not classify
5 The flash was updated but the reset failed New image The reset command could not be started, the reset command failed (its output is included in the error message)
6 The card was reset but verification was not completed New image The card at the same PCI address did not report fw_version within --boot-timeout, Ctrl+C pressed after [3/5]
  • On exit code 4, do not reset the card or reboot the host; run the same command again. If the run ended because no response was received from the firmware, run it again after the firmware responds. See When no response is received.
  • Ctrl+C pressed before [3/5] (including at the confirmation prompt) prints aborted (nothing written) and ends with exit code 1.
  • Ctrl+C pressed from [3/5] until the reset finishes is handled after the reset succeeds: the verify step is skipped, interrupted after flashing: ... is printed, and the tool ends with exit code 6. Ctrl+C pressed during the verify step has the same effect. With --no-reset, or if the reset failed, it is not handled, and the tool ends with exit code 0 or 5.
  • A SIGTERM or SIGHUP received from [3/5] until the reset finishes terminates the tool right after the reset succeeds. In this case, the tool ends with the signal instead of an exit code, and no JSON is printed even if --json was given. The flash holds the new image, and the card has been reset. With --no-reset, or if the reset failed, it is not handled.
  • A command-line syntax error (an unknown option, a missing IMAGE, both -d and -i given or neither, a --scope value that is not allowed, or a non-integer -i or --boot-timeout) prints the usage to standard error and ends with exit code 2. In this case, no JSON is printed even if --json was given.

JSON output

With --json, the tool produces no other screen output and prints a single result JSON to standard output when it ends. The format is the same for success and failure. For a command-line syntax error, no JSON is printed. If the tool does not end normally, there may be no JSON, or result and exit_code may be null; in that case, the state of the flash is unknown. Do not reset the card; run the same command again.

Example output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "tool_version": "1.0",
  "device": "ha0",
  "bdf": "0000:01:00.0",
  "image": "image.gpt",
  "image_kind": "gpt",
  "image_size": 2752512,
  "image_crc32": "0x07ba4d6e",
  "scope": "full",
  "rewrite": false,
  "result": "ok",
  "exit_code": 0,
  "error": null,
  "errno": null,
  "fw_rc": null,
  "fw_version_before": "1.0.5",
  "fw_version_after": "1.0.6",
  "version_changed": true,
  "reset": "sbr",
  "device_after": "ha0",
  "sectors": [
    672,
    672
  ],
  "elapsed_s": {
    "upload": 0.412,
    "flash": 4.108,
    "reset": 8.215,
    "verify": 3.004
  }
}

Fields

Field Type Meaning
tool_version String Tool version. In this release, it is "1.0"
device String or null Name of the target node ("ha0")
bdf String or null PCI address of the target card
image String Image path given on the command line
image_kind String or null "gpt" or "full-flash"
image_size Integer or null Image size (bytes)
image_crc32 String or null CRC-32 of the whole image (in the form "0x07ba4d6e")
scope String "full" or "app"
rewrite Boolean Whether --rewrite was given
result String or null The result. See result values. null if the tool did not end normally
exit_code Integer or null The same value as the exit code. null if the tool did not end normally
error String or null Reason for the failure (a human-readable sentence)
errno Integer or null Error number returned by the failed request. For diagnostics
fw_rc Integer or null The result code when the firmware returned a failure result for the update request. See fw_rc values
fw_version_before String or null fw_version before the update
fw_version_after String or null fw_version after the reset. Filled in only when the verify step completed
version_changed Boolean or null Whether the version numbers before and after the update differ. Filled in only when the verify step completed
reset String or null "sbr" (reset done), "skipped" (--no-reset), "failed" (reset could not be done), null (the reset step was not reached)
device_after String or null Node name after the reset. It may differ from the name before the reset
sectors Array of two integers, or null [completed sectors, total sectors] when the write step ended (in 4 KiB units). null if the write step did not complete or the progress could not be read
elapsed_s Object Time taken by each step (seconds): upload, flash, reset, verify. null for a step that was not run

result values

Value Meaning exit_code
"ok" The update, reset, and verification all completed 0
"dry-run" The pre-flight checks of --dry-run passed. Nothing was written 0
"updated-no-reset" The flash was updated and the reset was skipped with --no-reset 0
"interrupted-after-flash" The flash was updated and the card was reset, then Ctrl+C skipped the verify step 6
"aborted" Interrupted with Ctrl+C before writing 1
"error" Failed. See exit_code and error 1~6

When exit_code is 6, result distinguishes the case where the card did not come back ("error") from the case where Ctrl+C skipped the verification ("interrupted-after-flash").

fw_rc values

Value Meaning exit_code
2 The running firmware has no update capability 2
3 The firmware rejected the arguments of the request. The flash was not changed 3
7 The firmware aborted before erasing the flash. The flash was not changed 2
10 The firmware's image check (GPT, CRC) failed. The flash was not changed 3
11 With --scope app, the GPT in the flash or the fip partition inside it cannot be read, or the location of the fip partition differs from the image. The flash was not changed. Rerun with --scope full 3
12 The write or read-back verification failed. The flash may be partially written 4
13 The firmware could not read the flash. This happened before erasing, so the flash was not changed 2
Any other value Unknown result 4

Image file

ha-fw-update accepts two kinds of images.

Kind image_kind Size Ranges that can be written
GPT image (image.gpt) gpt Exactly the disk size described by the GPT of the image full, app
Full flash image full-flash Exactly 16 MiB full

The disk size of a GPT is determined by the position of the backup GPT header ((LBA of the backup header + 1) × 512 bytes). Before writing, the tool checks the following, and if any check fails, it ends with exit code 3. The flash is not changed.

  • There is a GPT header at LBA 1 (offset 512), and the CRCs of the header and of the partition entry table are correct.
  • The partition entry size is 128 bytes, and the number of entries is 1 to 128.
  • The file size is a multiple of 512 and at most 16 MiB.
  • The file size equals the disk size of the GPT or 16 MiB. The tool does not accept a file that is smaller than the disk size or that has other data appended after it.
  • With --scope app, the image must be a GPT image and must have a fip partition.

The firmware checks again the GPT and CRC of the image uploaded to card memory before it erases the flash. With --scope app, the location of the fip partition in the GPT in the flash must also match the image, and if it differs, the firmware rejects the request with fw_rc 11.


Reset command

The reset step runs the command found in the following order, in the form <command> --bdf <BDF>.

  1. If --hotreset PATH is given, only that path is used. If the file cannot be executed, the tool ends in the pre-flight checks with exit code 1.
  2. ha-hotreset.sh in the same directory as the real location of the tool file (the location after following symbolic links)
  3. ha-hotreset found on PATH

When you run the installed /usr/bin/ha-fw-update, /usr/bin/ha-hotreset is used. If ha-hotreset.sh exists in the same directory, it is used first, and it is the same script as ha-hotreset. The output of the reset command appears, as part of the error message, only when the reset fails. If another ha-hotreset is running on the same host, the tool prints [4/5] another ha-hotreset is running on this host; waiting for it (up to 600 s) before the reset and waits up to 600 seconds for that run to end. The conditions for a reset are in ha-hotreset.


Files used

Path Purpose
/dev/haN Uploads the image and requests the update. Closed before the reset step
/sys/class/ha/haN/device Gets the PCI address of the card
/sys/class/ha/haN/fw_version Reads the version before the update, and after the reset checks whether the card is ready and what the new version is
/sys/class/ha/haN/fw_update_progress Reads the progress
/proc/<PID>/fd/ Finds other processes that have /dev/haN open
The sysfs config of the parent port Checks whether the parent port is a root port
/run/lock/ha-fw-update.<BDF>.lock A lock file that prevents concurrent runs on the same card

See also