Plugin: Devlink

Introduction

This plugin provides firmware update support for network interface cards that support the Linux devlink interface. This is a generic plugin that can work with any device that implements devlink functionality.

Supported Devices

The plugin supports devices implementing the devlink interface on the PCI and MDIO buses, as well as emulated netdevsim devices for testing.

Firmware Format

The daemon will decompress the cabinet archive and extract a firmware blob in a packed binary file format.

This plugin supports the following protocol ID:

  • org.kernel.devlink

GUID Generation

These devices use custom instance IDs consisting of the component name.

  • PCI\VEN_15B3&DEV_1021&COMPONENT_fw
  • MDIO_BUS\COMPONENT_fw
  • MDIO_BUS\VEN_maxlinear&DEV_mxl86252&COMPONENT_fw

Optionally, additional GUIDs might be generated as specified in the quirk file, see below.

For devices attached via MDIO with an associated devicetree node, the vendor prefix and device name from the first “compatible” string are used as the VEN and DEV instance ID components, resulting in a quirk-only MDIO_BUS\VEN_maxlinear&DEV_mxl86252 instance ID on the devlink device and component GUIDs just like for PCI devices. Unlike the versions reported by the kernel, the devicetree compatible is available even when the device cannot report any version information, for example while it is stuck in a bootloader rescue mode, so firmware targeting the compatible-based GUID can still be matched and flashed to recover such a device.

Device Identification

Devices are identified using their in the format:

BUS_NAME/DEV_NAME

For PCI, this is for example:

pci/0000:01:00.0

Requirements

  • Linux kernel with devlink support
  • Device driver with devlink implementation
  • Root privileges (required for devlink write commands)

Update Behavior

The plugin uses the Linux devlink netlink interface to communicate with the kernel and perform firmware updates. The process involves:

  1. Netlink Communication: Opens Netlink socket to communicate with the devlink subsystem
  2. Device Detection: Gets all existing devlink devices
  3. Firmware Upload: Writes the firmware file to CACHE_DIRECTORY and instructs devlink to flash it
  4. Progress Monitoring: Monitors devlink status messages to provide real-time progress updates
  5. Firmware Activation: Activates firmware using devlink reload activate action

The plugin implements the devlink generic netlink protocol:

  1. Device Enumeration: Sends DEVLINK_CMD_GET with dump flag to discover all devlink devices
  2. Device Monitoring: Receives DEVLINK_CMD_NEW notifications when devices are added
  3. Device Removal: Receives DEVLINK_CMD_DEL notifications when devices are removed
  4. Device Information: Sends DEVLINK_CMD_INFO_GET to retrieve device details and versions
  5. Flash Command: Sends DEVLINK_CMD_FLASH_UPDATE with device and file information
  6. Status Monitoring: Receives DEVLINK_CMD_FLASH_UPDATE_STATUS messages for progress
  7. Completion: Waits for DEVLINK_CMD_FLASH_UPDATE_END to confirm completion
  8. Firmware Activation: Sends DEVLINK_CMD_RELOAD with fw_activate action to activate updated firmware

Quirk Use

This plugin uses the following plugin-specific quirks:

DevlinkFixedVersions

Specifies a comma-separated list of “fixed version” names that should be used to generate additional GUID instance IDs for component matching. This is useful to target specific device according to device IDs, like ASIC ID, Board ID, etc.

Example usage in quirk file:

[PCI\VEN_15B3&DEV_1021]
DevlinkFixedVersions = fw.psid

Since: 2.0.15

Private Flags

The plugin supports the following private flags:

Flags=omit-component-name

When this flag is set, the plugin will not include the DEVLINK_ATTR_FLASH_UPDATE_COMPONENT attribute in the flash command. This is useful for devices that don’t support component-specific updates. For such, passing DEVLINK_ATTR_FLASH_UPDATE_COMPONENT in flash netlink message would cause an error.

Usage in metainfo XML:

<custom>
  <value key="LVFS::DeviceFlags">omit-component-name</value>
</custom>

Since: 2.0.15

Error Handling

The plugin handles various error conditions:

  • Kernel without devlink support
  • Device without devlink implementation
  • Device without devlink flash implementation
  • Firmware file access issues
  • Flash operation failures

Security Considerations

  • Firmware files are temporarily stored in /lib/firmware/
  • Root privileges are required for devlink write commands
  • Temporary files are cleaned up after the operation

Vendor ID Security

The vendor ID is set from the PCI vendor, or for devices on the MDIO bus, from the devicetree vendor prefix, e.g. DT:maxlinear.

External Interface Access

This plugin requires read/write access to /dev/bus/usb.

Version Considerations

This plugin has been available since fwupd version 2.0.15.

References