Skip to content

Firmware Update (rbln-flash)

rbln-flash is a command-line tool for updating firmware on RBLN NPUs, supporting parallel updates across multiple devices.

It handles two distinct update modes:

  • CP firmware update: updates the Command Processor (CP) firmware.
  • MCU (SMC) firmware update: updates the System Management Controller (SMC) firmware.

Info

The devices are unavailable while the update runs. Before updating, stop all workloads, stop rbln-smd, and unload the rebellions driver. See Before you run rbln-flash for the commands.

Quick Start

CP firmware update (directory mode, all devices)

$ sudo systemctl stop rbln-smd.service
$ sudo modprobe -r rebellions

$ sudo rbln-flash --cp -d <DIR_PATH> -s all

$ sudo modprobe rebellions
$ sudo systemctl start rbln-smd.service

$ rbln-smi -q -qd npu,name,device,fw_ver

Check that the fw_ver column shows the new firmware version for every device.

Key Concepts and Terminology

Update selection

  • Update mode: CP (--cp) or MCU (SMC) (--mcu).
  • Image source: Single firmware image file (-f) or firmware directory (-d).
  • Targets: A single device by its PCI BDF (bus/device/function), e.g. -s 01:00.0, or all devices (-s all).

See Command Reference for exact flag syntax and constraints (e.g., "select exactly one of --cp/--mcu").

Command Reference

Before you run rbln-flash

Preconditions

If the package is already installed and the driver is loaded, stop rbln-smd and unload the rebellions driver.

$ sudo systemctl stop rbln-smd.service
$ sudo modprobe -r rebellions

After the update

The new firmware takes effect as follows:

  • Rebel100™: rbln-flash resets each updated device and confirms that it boots before it reports SUCCESS. For an MCU update, it also confirms that the device runs the new SMC firmware version.
  • ATOM™: the new firmware takes effect when the rebellions driver is loaded again.

Load the driver, restart rbln-smd, and check the CP firmware version:

$ sudo modprobe rebellions
$ sudo systemctl start rbln-smd.service
$ rbln-smi -q -qd npu,name,device,fw_ver

Check that the fw_ver column shows the new version for every device. rbln-smi reports the CP firmware version; it does not report the SMC firmware version.

Note

After an update on Rebel100™, or an MCU update on RBLN-CA22, rbln-flash rescans the PCI devices when it finishes, and the rebellions driver may load automatically. Before you run rbln-flash again, for example an MCU update right after a CP update, check lsmod | grep rebellions and unload the driver if it is listed. Otherwise the tool exits with 240 (-EBUSY).

General usage

$ sudo rbln-flash --cp -f <FILE_PATH> -s <PCI_ADDR | all>
$ sudo rbln-flash --cp -d <DIR_PATH> -s <PCI_ADDR | all>

$ sudo rbln-flash --mcu -f <FILE_PATH> -s <PCI_ADDR | all>
$ sudo rbln-flash --mcu -d <DIR_PATH> -s <PCI_ADDR | all>

Options

Option Description Example
--cp Update firmware for the Command Processor (CP). --cp -f image.gpt
--mcu Update firmware for the MCU (SMC). --mcu -f smc_fw.bin
-d, --dir <DIR_PATH> Directory containing the image to be updated. -d /lib/firmware/3.0/
-f, --file <FILE_PATH> Full path of a single image to be updated. -f /lib/firmware/3.0/image.bin
-s, --pci_addr <PCI_ADDR | all> Target device for the update. Use the BB:DD.F form shown by lspci (e.g., 01:00.0), or all to select all devices. -s 01:00.0 | -s all
-l, --logfile <LOG_PATH> Path to a log file to save detailed update logs. If omitted, logs are printed only to stdout. -l update.log
-h, --help Show help message and exit. --help
--version Show version information and exit. --version

Note

  • Exactly one of --cp or --mcu must be specified.
  • Exactly one of -d or -f must be specified.

Directory mode binary requirements

When using -d, the directory must contain firmware files with the following exact names:

Component Required filename
ATOM-CP (RBLN-CA25) atom-cp-secure.bin
ATOM-CP (other ATOM™ cards) atom-cp.bin
ATOM-SMC atom-smc.bin
REBEL-CP rebel-q-cp.bin
REBEL-SMC rebel-smc.bin

The tool selects the file from the detected device platform, the card, and the update mode (--cp or --mcu). It picks one file, based on the first detected device, and writes that file to every target device. On a host that has both RBLN-CA25 and other ATOM™ cards, update each card separately with -s <PCI_ADDR>.

Return codes

The tool returns the following exit codes:

Exit code Meaning
0 All devices updated successfully.
1 to 128 Number of devices that failed to update.
129 to 255 The tool stopped before updating any device. It returns a negative Linux errno value, which the shell reports as 256 - errno.

Common error exit codes:

Exit code errno Cause
255 -1 Not running as root (-EPERM), or the firmware file does not exist. Run with sudo and check the file path.
240 -EBUSY The rebellions driver is still loaded. Unload it first.
237 -ENODEV No matching device was found. Check the -s value.
234 -EINVAL Invalid option combination or firmware image. Check the flags and the image file.

See CLI Examples → Exit code handling for a scripting example.

Firmware Logs on Failure

When a device reports FAILED or TIMEOUT, rbln-flash automatically saves a device-side firmware log to the current working directory. These logs are intended to help diagnose per-device update failures.

File naming

fwlog_<DOMAIN>:<BUS>:<SLOT>.<FUNC>.txt

For example: fwlog_0000:01:00.0.txt, fwlog_0000:02:00.0.txt.

Behavior

  • Generated only for devices whose result is FAILED or TIMEOUT.
  • Saved in the current working directory.
  • If a file with the same name already exists, it is overwritten.

Note

fwlog_<BDF>.txt is independent of the -l, --logfile option. -l records the host-side update progress log; fwlog_<BDF>.txt is a device-side firmware diagnostic log.

CLI Examples

Firmware update workflows

Summary

CP firmware update for a specific device with file path.

Command

Command
$ sudo rbln-flash --cp -f /PATH/image.bin -s 01:00.0

Output (example)

Result summary (example)
==== Firmware Update Results ====
0000:01:00.0 : SUCCESS [O]
=================================

Summary

CP firmware update for all devices with directory path.

Command

Command
$ sudo rbln-flash --cp -d /PATH/ -s all

Output (example)

Result summary (example)
==== Firmware Update Results ====
0000:01:00.0 : SUCCESS [O]
0000:02:00.0 : FAILED [X]
0000:03:00.0 : TIMEOUT [...]
=================================
2 device(s) failed to update.
Firmware logs have been saved to fwlog_<BDF>.txt for each failed device.
Please check the firmware logs, reset the device, and retry the update.

Summary

MCU firmware update for a specific device with file path.

Command

Command
$ sudo rbln-flash --mcu -f /PATH/image.bin -s 01:00.0

Output (example)

Result summary (example)
==== Firmware Update Results ====
0000:01:00.0 : SUCCESS [O]
=================================

Summary

MCU firmware update for all devices with directory path.

Command

Command
$ sudo rbln-flash --mcu -d /PATH/ -s all

Output (example)

Result summary (example)
==== Firmware Update Results ====
0000:01:00.0 : SUCCESS [O]
0000:02:00.0 : FAILED [X]
0000:03:00.0 : TIMEOUT [...]
=================================
2 device(s) failed to update.
Firmware logs have been saved to fwlog_<BDF>.txt for each failed device.
Please check the firmware logs, reset the device, and retry the update.

Summary

Updates firmware and writes detailed logs to a file.

Command

Command
$ sudo rbln-flash --cp -d /PATH/ -s all -l update.log

Output (example)

Result summary + logfile (example)
==== Firmware Update Results ====
0000:01:00.0 : SUCCESS [O]
0000:02:00.0 : FAILED [X]
0000:03:00.0 : TIMEOUT [...]
=================================
2 device(s) failed to update.
Firmware logs have been saved to fwlog_<BDF>.txt for each failed device.
Please check the firmware logs, reset the device, and retry the update.

Logs are written to update.log (and also printed to stdout).

Exit code handling

Example shell logic for interpreting rbln-flash exit codes in scripts/CI:

Example
sudo rbln-flash --cp -d /PATH -s all
ret=$?

if [ $ret -eq 0 ]; then
  echo "All devices updated successfully!"
elif [ $ret -le 128 ]; then
  echo "$ret device(s) failed to update."
else
  echo "Error occurred: errno $((256 - ret))"
fi

Troubleshooting

The driver cannot be unloaded

  • Stop the daemon: sudo systemctl stop rbln-smd.service
  • Unload the driver: sudo modprobe -r rebellions
  • If the module is still in use, find what holds it. lsmod | grep rebellions shows the use count in the Used by column, and sudo lsof /dev/rbln* lists the processes that have a device open. Stop those processes and unload the driver again.
  • If the driver loaded again on its own after a previous update, unload it before the next run (see After the update).

Directory mode fails

Some devices failed to update

  • Check the return code (see Command Reference → Return codes).
  • Re-run with --logfile and inspect the logs for per-device errors.
  • Inspect the auto-generated fwlog_<BDF>.txt files in the current directory for device-side diagnostic logs (see Firmware Logs on Failure).
  • After reviewing the logs, reset the failed device and retry the update.

Notes

  • The tool performs parallel firmware updates to all selected devices.
  • Each device reports its result: SUCCESS, FAILED, or TIMEOUT.
  • When a device fails or times out, a per-device firmware log file (fwlog_<BDF>.txt) is automatically written to the current working directory. See Firmware Logs on Failure.
  • Ensure the firmware image matches the target update mode (--cp or --mcu).
  • An interrupted update or an invalid image can cause the device to malfunction. If an update is interrupted, run the same rbln-flash command again. If the update still fails or the device is no longer detected, contact technical support through Contact Us.
  • When -l is specified, logs are written to the file and also printed to stdout. If omitted, logs are printed to stdout only.

See also