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
python3onPATH, so ifpython3 --versionreports 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-hotresetusespciutils(lspci,setpci)
Synopsis¶
1 2 | |
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
-dis hexadecimal in the formatdddd:bb:dd.f(domaindevice.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 justbb:dd.f. If cards with the samebb:dd.fexist 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/haNand 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.
yoryes(case-insensitive) proceeds.- Any other input, an empty line, or end of input (EOF) prints
ERROR: abortedand 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 | |
- 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
--rewritewas 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) printsaborted (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
SIGTERMorSIGHUPreceived 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--jsonwas 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-dand-igiven or neither, a--scopevalue that is not allowed, or a non-integer-ior--boot-timeout) prints the usage to standard error and ends with exit code 2. In this case, no JSON is printed even if--jsonwas 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 | |
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>.
- If
--hotreset PATHis given, only that path is used. If the file cannot be executed, the tool ends in the pre-flight checks with exit code 1. ha-hotreset.shin the same directory as the real location of the tool file (the location after following symbolic links)ha-hotresetfound onPATH
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¶
- Firmware update — procedure, constraints during an update, and how to respond to a failure
- Updating firmware on several cards in sequence — an example script that updates several cards one at a time using the
--jsonresult - ha-hotreset — the hot reset command used in the reset step
- hyperaccel-smi — the
Bus-Idand firmware version of a card - sysfs nodes —
fw_version,fw_update_progress - Kernel log messages
- Supported environments