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 (Command Processor) firmware update
  • MCU (SMC) firmware update

Warning

Firmware updates disrupt system operations. Stop all workloads before updating. Refer to Before you run rbln-flash for driver handling instructions.

Note

The RBLN driver must be unloaded before running this command.

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

Key Concepts and Terms

Update Selection

  • Update mode: CP (--cp) or MCU (SMC) (--mcu).
  • Image source: Single firmware image file (-f) or firmware directory (-d).
  • Targets (CP update): A single PCI BDF (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 the rbln-smd and unload the rebellions driver.

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

After the update

If you stopped the rbln-smd and unloaded the rebellions driver, follow these steps to restore the system to its normal state.

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

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 Microcontroller (MCU). --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 PCI address(es) for CP/MCU update. -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

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 atom-cp.bin and atom-cp-secure.bin
ATOM-SMC atom-smc.bin
REBEL-CP rebel-q-cp.bin
REBEL-SMC rebel-smc.bin

The tool automatically selects the correct file based on the detected device platform and the update mode (--cp or --mcu).

Return codes

The tool returns the following exit codes:

Value type Meaning
0 All devices updated successfully.
Negative integer Linux errno-style error code (e.g., -EINVAL, -ENODEV).
Positive integer Number of devices that failed during update.

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]
0000:02:00.0 : FAILED [X]
0000:03:00.0 : TIMEOUT [...]
=================================

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 [...]
=================================

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]
0000:02:00.0 : FAILED [X]
0000:03:00.0 : TIMEOUT [...]
=================================

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 [...]
=================================

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 [...]
=================================

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 -gt 0 ]; then
  echo "$ret device(s) failed to update."
elif [ $ret -lt 0 ]; then
  echo "Error occurred: $ret"
else
  echo "All devices updated successfully!"
fi

Troubleshooting

The driver cannot be unloaded

  • Stop the daemon: sudo systemctl stop rbln-smd.service
  • Unload the driver: sudo modprobe -r rebellions
  • Ensure no process is actively using the devices.

Directory mode fails

Some devices failed to 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).
  • Interrupted updates or invalid images may cause device malfunction.
  • 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