Skip to content

Firmware Update (rbln-flash)

rbln-flash is a command-line tool to update firmware on RBLN NPUs.

It supports parallel updates and 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 here for driver handling instructions.

Note

This tool requires the driver to be unloaded to function correctly.

Quick Start

CP firmware update (directory mode, all devices)

$ sudo systemctl stop rbln_daemon.service
$ sudo modprobe -r rebellions

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

$ sudo modprobe rebellions
$ sudo systemctl start rbln_daemon.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_daemon and unload the rebellions driver.

$ sudo systemctl stop rbln_daemon.service
$ sudo modprobe -r rebellions

After the update

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

$ sudo modprobe rebellions
$ sudo systemctl start rbln_daemon.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 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.

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).

Summary

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

Command

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_daemon.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.
  • 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