ha-led¶
ha-led is a host command-line tool that blinks the board LED of a single card, so that you can find in the chassis the slot where that card is plugged in. When you specify, by PCI address, a card that hyperaccel-smi shows as Bus-Id, the tool sends LED on and off commands to the firmware of that card through the driver. This page defines the install location, requirements, arguments, behavior, output, exit codes, and error messages.
Included starting with release 2.5.0
ha-led is not present in releases earlier than 2.5.0. This tool and the driver's LED command that the tool uses are included in the release together starting with 2.5.0.
Install location¶
ha-led is installed to /usr/bin/ha-led by the driver deb package hyperdriver-dkms. It is installed together with hyperaccel-smi, ha-hotreset, and ha-fw-update, and is removed together with the driver (when the package is removed).
Requirements¶
- Run it as root on the host. If you are not root, the tool prints
ha-led: root requiredat the step where it sends the command and ends with exit code1. python3is required. It uses only the standard library.- The driver must have probed the target card so that
haNexists under/sys/class/ha/. - The loaded driver must be from the same release as
ha-led. A driver from an earlier release does not support the LED command. Check the loaded version withcat /sys/module/ha/version. - The firmware of the card must support the LED command. See Checking firmware support below.
Checking firmware support¶
The LED command works only when both of the following conditions are met.
- The driver must be version 2.5.0 or later, and the firmware must be version 1.0.6 (protocol v8) or later.
- The board of the card must have an LED. The driver and firmware versions mean only that the command exists; they do not mean that the board has an LED. Firmware built for a board without an LED rejects the command.
When the driver probes a card, it records the protocol of the firmware in the kernel log.
1 | |
1 | |
The number right after ABI protocol (v8) is the protocol of the firmware. Judge from this line together with the version number of the firmware. If the protocol is lower than 8, update the firmware with ha-fw-update.
Synopsis¶
1 2 | |
Arguments and options¶
| Argument | Description |
|---|---|
-d BDF, --bdf BDF |
Required. PCI address of the target card. You can specify only one card. See Specifying the card |
on |
Starts blinking the LED and ends immediately. The LED keeps blinking until off is sent |
off |
Turns the LED off |
Both on and off omitted |
Blinks for 10 seconds and then turns the LED off. The 10 seconds cannot be changed |
-h, --help |
Prints the usage and ends |
The blink period of the LED is determined by the firmware.
Specifying the card¶
- For
-d, use the PCI address thathyperaccel-smishows asBus-Id(Card table). The card is identified by PCI address rather than byhaNnumber because the number can change depending on the card configuration. - The format is
dddd:bb:dd.f(for example,0000:65:00.0) orbb:dd.fwithout the domain (for example,65:00.0). It is case-insensitive, and leading and trailing whitespace is ignored. - An address without the domain is accepted only if exactly one card has that address. If the same address exists in several PCI domains, the tool prints the candidates and refuses with exit code
2, so include the domain. - It searches only the cards that the driver has probed. If the card is not found, the tool also prints the list of cards currently probed.
- If the address format is wrong, the tool ends with exit code
1.
Behavior¶
The default mode, in which both on and off are omitted, proceeds in the following order.
- Sends the blink command to the card and, if it succeeds, prints one line.
- Waits for 10 seconds. If it receives SIGINT (Ctrl-C), SIGTERM, or SIGHUP while waiting, it ends the wait immediately.
- Sends the off command to the card, prints one line, and ends. It sends the off command however the wait ended, and even if the output fails (for example, when the pipe is broken).
Once the firmware receives the blink command, it keeps blinking until the off command arrives. Turning the LED off is therefore the host's job, and it is this tool that turns it off after 10 seconds.
- While running, the tool blocks SIGINT, SIGTERM, and SIGHUP and uses them only to end the wait. These signals do not interrupt a command that has already gone out to the card.
- The tool opens
/dev/haNonly while sending a command and closes it right away. ha-hotreset refuses to reset when a process has the device node open, butha-leddoes not keep the node open during the 10-second wait, so this tool does not cause a reset to be refused. - The off command finds the card again by PCI address rather than by the
haNfound at the start. Even if the card is reset during the wait and gets a differenthaNnumber, the tool turns off the same card.
Output¶
Progress goes to standard output, and errors go to standard error as lines that start with ha-led:. The ha1 0000:65:00.0 at the start of a line is the number and PCI address of the card.
1 2 3 | |
The first line appears as soon as the blink command succeeds, and the second line appears when 10 seconds have passed or the wait is ended by a signal.
1 2 3 4 | |
When the LED stays on¶
In the following cases, the off command may not reach the card, and the LED may keep blinking.
ha-ledwas ended with SIGKILL during the 10-second wait, or the host shut down. To end the tool, use Ctrl-C or SIGTERM instead of SIGKILL. The tool then turns the LED off and ends.- The card was reset. An SDK device reset and an automatic reset do not stop the blink. After an SBR or
ha-hotreset, the pin state is not defined. - The off command failed. See Error messages.
In any of these cases, turn the LED off with off once the card responds again.
1 | |
Exit codes¶
| Code | Meaning |
|---|---|
0 |
The command succeeded. The same applies when --help is printed |
1 |
Usage error, or not root. This includes the cases where -d was omitted, the address format is wrong, or an argument other than on and off was given, and the case where there is no permission to open the device node |
2 |
The card cannot be used. The card was not found, the address matches several cards, the driver or firmware does not support the LED command, or the card is being updated, is not ready, or is FATAL |
3 |
The command failed in the firmware, or the firmware did not respond. The state of the LED is unknown in this case |
Error messages¶
Only the beginning of each message is listed. Depending on the cause, further guidance may follow at the end of the line.
| Code | Output (beginning) | Meaning and what to do |
|---|---|---|
1 |
ha-led: root required |
You are not root. Run it with sudo |
1 |
ha-led: '<value>' is not a PCI address |
The address format is wrong. Write it as dddd:bb:dd.f or bb:dd.f |
1 |
ha-led: cannot open /dev/haN: Permission denied |
You do not have permission to open the device node. Check that you are running as root |
2 |
ha-led: cannot open /dev/haN: <reason> |
The node cannot be opened. No such file or directory means that the node does not exist, so check that the driver probed the card |
2 |
ha-led: no HyperAccel card at <value>; cards present: … |
The driver has not probed a card at that address. The cards currently probed follow as a list of <BDF> (ha<N>). If it shows none (is the ha driver loaded?), check that the driver is loaded |
2 |
ha-led: <value> matches more than one card: … |
The address without a domain matches several cards. Give the full address including the domain |
2 |
ha-led: this driver has no LED command |
The loaded driver does not support the LED command. Install and load the driver from the same release as ha-led |
2 |
ha-led: this card cannot blink its LED |
The protocol of the firmware is lower than 8, or the firmware is built for a board without an LED. Check as described in Checking firmware support, and update the firmware if the protocol is low |
2 |
ha-led: a firmware update is running on this card, or the last one got no answer |
A firmware update is in progress on the card, or the last update got no response. Run the tool again after the update finishes. If no response was received, follow When no response is received |
2 |
ha-led: the card is not ready |
The firmware is booting or being reset. Run the tool again after a short while |
2 |
ha-led: the card was reset while the command was on its way |
The card was reset while the command was on its way. Run the tool again |
2 |
ha-led: the card is being removed or is gone |
The card is being removed or is already gone |
2 |
ha-led: the card is in a fatal state |
The card is in the FATAL state. The tool first advises resetting with ha-hotreset, but the recovery method depends on the cause. Follow FATAL and recovery |
2 |
ha-led: the driver could not map the card's control window |
The driver could not map the control window of the card. Run the tool again. If it repeats, collect the kernel log and contact HyperAccel |
2 |
ha-led: the firmware on this card was built without the LED command |
The firmware does not support the LED command. Update the firmware with ha-fw-update |
3 |
ha-led: the firmware did not answer, or a reset was in progress |
The firmware did not respond, or a reset was in progress, so the LED state is unknown. Run off once the card responds again. A non-response is recorded as described in When the ceiling expires |
3 |
ha-led: the firmware could not start the blink (rc 4) |
The firmware could not start the blink, and the LED may have been left on in the meantime. The tool sends the off command one more time. If the LED is on, run off |
3 |
ha-led: the firmware refused the command (rc <N>) |
The firmware refused the command. If it repeats, collect the kernel log and contact HyperAccel |
3 |
ha-led: LED command failed: <reason> |
Any other failure not listed above |
In the default mode, if the off command fails, ; the LED may still be blinking: run ha-led -d <BDF> off is appended to the message above, and the exit code is the code of that failure. Run off as the message advises.
When the firmware responds with an error (built without the LED command, could not start the blink, refused the command), the driver counts it as a firmware error. devcmd_fw_errors increases by 1, health becomes degraded, and Firmware error: resq[…] is logged in the kernel log (Firmware error result). The output of the tool also carries a note that the error is counted as a firmware error and that health becomes degraded. This does not mean that the card is failing now; health returns to ok when the driver probes the card again (hot reset, module reload, reboot). You do not need to reset the card because of this indication. this card cannot blink its LED is not counted as a firmware error, so it has no effect on health. For details, see Telemetry.
Usage example¶
Finding a card in the chassis:
- Check the
Bus-Idof the card you want to find withhyperaccel-smi. -
Run the tool with that address. The LED blinks for 10 seconds.
1sudo ha-led -d 0000:65:00.0 -
If you need more time to find the card at the chassis, leave it blinking with
on, and turn it off withoffafter you find it.1 2
sudo ha-led -d 0000:65:00.0 on sudo ha-led -d 0000:65:00.0 off
See also¶
- hyperaccel-smi — checking the PCI address (
Bus-Id) of a card - ha-fw-update — updating to firmware that supports the LED command
- ha-hotreset — resetting a card. After an SBR or a hot reset, the LED pin state is not defined. An SDK device reset does not stop the blink
- FATAL and recovery — when a card is FATAL
- Hang detection and the watchdog — what is recorded when the firmware does not respond
- Telemetry —
healthanddegraded - Multiple devices — how card numbers map to PCI addresses