Firmware Update Tool

The firmware update tool, hl-fw-loader, updates the firmware of the device from the host side. By default, the tool updates the firmware of all available devices. You can update a specific device by using -d flag.

Updating the Firmware

To update the firmware, follow the below steps:

  1. Remove drivers in this order - habanalabs, habanalabs_cn, habanalabs_en:

$ sudo modprobe -r <driver name>
  1. Reset the device.

  2. Update the new firmware:

$ hl-fw-loader [<options>]
  1. Load the drivers in this order - habanalabs_en, habanalabs_cn, habanalabs:

$ sudo modprobe <driver name>

See Firmware Update Options for the full list of hl-fw-loader options and their description. The below is an example of the tool command line:

$ hl-fw-loader -f <fw file>

Low Level Access to Burn FW

In case the standard method of the FW update fails, you can run a recovery (direct) flash burn by using -r flag:

$ sudo hl-fw-loader –r –f <fw file>


This option is not available for secured OAM.

Firmware Update Options

For the supported options of the firmware update tool, use -h argument. The below table presents all the options available and their description.



-f <fw file>

Path to the firmware file. The default agent file is /lib/firmware/habanalabs/ gaudi/gaudi-agent- fw_loader-fit.itb

Make sure to use the default agent file.

If the default agent file does not exist and no file is specified, f flag allows the hl-fw-loader to use /lib/firmware/habanalabs/ gaudi/gaudi-boot-fit.itb

-d, –device <pci addr>

-d, –device <i2c bus>

The PCI address of the Intel Gaudi device (e.g. 01:00.0). The flag is optional. The default method is to program all the devices in the system.

When running from BMC, the transport is I2C and the device is selected by I2C bus number.


Sends request to reset the device.


Prints the device status.

-r, –recover

Recovery mode. Updates the firmware file directly to flash or EEPROM and starts using the new firmware. Only the primary image is updated. Not operational on secured device.

-p, –prog-only

Program only - depends on recovery mode. Use this option when manual host reboot is needed.

-y, –yes

Answers ‘yes’ to all questions.

Disabled in recovery mode (-r switch).

-h, –help

Prints this help message.

-v, –version

Prints version information and the utility termination.

-t, –timeout <seconds>

Timeout for waiting for device readiness (in seconds).

Default value: 25 seconds

-n, –nvread [[offset]:size]

Reads media raw content such as flash. Offset and size are optional. By default, read the first 1M of the media into an external file.

Applicable only in recovery mode.


The operation is associated with the OTP. When combining with --nvread, it reads the OTP area in flash.

-T, –trans-force <name>

Forces a specific transport.


Writes the OTP TB (Top/Bottom) bit register of the Macronix SPI flash.


Enables debug log level. Default value: Critical


Enables debug trace level. Default value: Critical

-D, –device-type <device type>n

Enforces specifying device types. Devices not matching the type on PCI/I2C will be ignored. For I2C recovery, the specified type aids detection.