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 here 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

CP: single device (file)CP: all devices (dir)MCU: single device (file)MCU: all devices (dir)Save logs (--logfile)Exit code handling

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-smd.service
• Unload the driver: sudo modprobe -r rebellions
• Ensure no process is actively using the devices.

Directory mode fails

• Confirm the firmware directory contains the required filenames listed in Command Reference → Directory mode binary requirements.
• Confirm you selected the intended update mode (--cp vs --mcu).

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

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

• rblnBandwidthLatencyTest: Host-to-NPU and NPU-to-NPU performance benchmark
• rbln-bios: System validation
• rbln-smi: Device monitoring and topology inspection