The Linux Kernel Logo
  • Development process
  • Submitting patches
  • Code of conduct
  • Maintainer handbook
  • All development-process docs
  • Core API
  • Driver APIs
  • Subsystems
    • Core subsystems
    • Human interfaces
    • Networking interfaces
      • Networking
        • AF_XDP
        • Bare UDP Tunnelling Module Documentation
        • batman-adv
        • SocketCAN - Controller Area Network
        • The UCAN Protocol
        • Hardware Device Drivers
        • Networking Diagnostics
        • Distributed Switch Architecture
        • Linux Devlink Documentation
          • Locking
          • Nested instances
          • Interface documentation
            • Devlink DPIPE
            • Devlink Health
            • Devlink Info
            • Devlink Flash
              • Overwrite Mask
              • Firmware Loading
              • Firmware Version Management
            • Devlink Params
            • Devlink Port
            • Devlink Region
            • Devlink Resource
            • Devlink Reload
            • Devlink Selftests
            • Devlink Trap
            • Devlink Line card
            • Devlink E-Switch Attribute
          • Driver-specific documentation
        • CAIF
        • Netlink interface for ethtool
        • IEEE 802.15.4 Developer’s Guide
        • ISO 15765-2 (ISO-TP)
        • J1939 Documentation
        • Linux Networking and Network Devices APIs
        • MSG_ZEROCOPY
        • FAILOVER
        • Net DIM - Generic Network Dynamic Interrupt Moderation
        • NET_FAILOVER
        • Page Pool API
        • PHY Abstraction Layer
        • phylink
        • IP-Aliasing
        • Ethernet Bridging
        • SNMP counter
        • Checksum Offloads
        • Segmentation Offloads
        • Scaling in the Linux Networking Stack
        • Kernel TLS
        • Kernel TLS offload
        • In-Kernel TLS Handshake
        • Linux NFC subsystem
        • Netdev private dataroom for 6lowpan interfaces
        • 6pack Protocol
        • ARCnet Hardware
        • ARCnet
        • ATM
        • AX.25
        • Linux Ethernet Bonding Driver HOWTO
        • cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
        • DCCP protocol
        • DCTCP (DataCenter TCP)
        • Device Memory TCP
        • DNS Resolver Module
        • Softnet Driver Issues
        • EQL Driver: Serial IP Load Balancing HOWTO
        • LC-trie implementation notes
        • Linux Socket Filtering aka Berkeley Packet Filter (BPF)
        • Generic HDLC layer
        • Generic Netlink
        • Netlink Family Specifications
        • Generic networking statistics for netlink users
        • The Linux kernel GTP tunneling module
        • Identifier Locator Addressing (ILA)
        • IOAM6 Sysfs variables
        • io_uring zero copy Rx
        • IP dynamic address hack-port v0.03
        • IPsec
        • IP Sysctl
        • IPv6
        • IPVLAN Driver HOWTO
        • IPvs-sysctl
        • Kernel Connection Multiplexor
        • L2TP
        • The Linux LAPB Module Interface
        • How to use packet injection with mac80211
        • Management Component Transport Protocol (MCTP)
        • MPLS Sysfs variables
        • Multipath TCP (MPTCP)
        • MPTCP Sysfs variables
        • HOWTO for multiqueue network device support
        • Multi-PF Netdev
        • NAPI
        • Common Networking Struct Cachelines
        • Netconsole
        • Netdev features mess and how to get out from it alive
        • Network Devices, the Kernel, and You!
        • Netfilter Sysfs variables
        • NETIF Msg Level
        • Netmem Support for Network Drivers
        • Resilient Next-hop Groups
        • Netfilter Conntrack Sysfs variables
        • Netfilter’s flowtable infrastructure
        • OPEN Alliance 10BASE-T1x MAC-PHY Serial Interface (TC6) Framework Support
        • Open vSwitch datapath developer documentation
        • Operational States
        • Packet MMAP
        • Linux Phonet protocol family
        • PHY link topology
        • HOWTO for the linux packet generator
        • PLIP: The Parallel Line Internet Protocol Device
        • PPP Generic Driver and Channel Interface
        • The proc/net/tcp and proc/net/tcp6 variables
        • Power Sourcing Equipment (PSE) Documentation
        • How to use radiotap headers
        • RDS
        • Linux wireless regulatory documentation
        • Network Function Representors
        • RxRPC Network Protocol
        • SOCKET OPTIONS
        • SECURITY
        • EXAMPLE CLIENT USAGE
        • Linux Kernel SCTP
        • LSM/SeLinux secid
        • Seg6 Sysfs variables
        • struct sk_buff
        • SMC Sysctl
        • NIC SR-IOV APIs
        • Interface statistics
        • Stream Parser (strparser)
        • Ethernet switch device driver model (switchdev)
        • Sysfs tagging
        • TC Actions - Environmental Rules
        • TC queue based filtering
        • TCP Authentication Option Linux implementation (RFC5925)
        • Thin-streams and TCP
        • Team
        • Timestamping
        • Linux Kernel TIPC
        • Transparent proxy support
        • Universal TUN/TAP device driver
        • The UDP-Lite protocol (RFC 3828)
        • Virtual Routing and Forwarding (VRF)
        • Virtual eXtensible Local Area Networking documentation
        • Linux X.25 Project
        • X.25 Device Driver Interface
        • XFRM device - offloading the IPsec computations
        • XFRM proc - /proc/net/xfrm_* files
        • XFRM
        • XFRM Syscall
        • XDP RX Metadata
        • AF_XDP TX Metadata
      • NetLabel
      • InfiniBand
      • ISDN
      • MHI
    • Storage interfaces
    • Other subsystems
  • Locking
  • Licensing rules
  • Writing documentation
  • Development tools
  • Testing guide
  • Hacking guide
  • Tracing
  • Fault injection
  • Livepatching
  • Rust
  • Administration
  • Build system
  • Reporting issues
  • Userspace tools
  • Userspace API
  • Firmware
  • Firmware and Devicetree
  • CPU architectures
  • Unsorted documentation
  • Translations
The Linux Kernel
  • Kernel subsystem documentation
  • Networking
  • Linux Devlink Documentation
  • Devlink Flash
  • View page source

Devlink Flash¶

The devlink-flash API allows updating device firmware. It replaces the older ethtool-flash mechanism, and doesn’t require taking any networking locks in the kernel to perform the flash update. Example use:

$ devlink dev flash pci/0000:05:00.0 file flash-boot.bin

Note that the file name is a path relative to the firmware loading path (usually /lib/firmware/). Drivers may send status updates to inform user space about the progress of the update operation.

Overwrite Mask¶

The devlink-flash command allows optionally specifying a mask indicating how the device should handle subsections of flash components when updating. This mask indicates the set of sections which are allowed to be overwritten.

List of overwrite mask bits¶

Name

Description

DEVLINK_FLASH_OVERWRITE_SETTINGS

Indicates that the device should overwrite settings in the components being updated with the settings found in the provided image.

DEVLINK_FLASH_OVERWRITE_IDENTIFIERS

Indicates that the device should overwrite identifiers in the components being updated with the identifiers found in the provided image. This includes MAC addresses, serial IDs, and similar device identifiers.

Multiple overwrite bits may be combined and requested together. If no bits are provided, it is expected that the device only update firmware binaries in the components being updated. Settings and identifiers are expected to be preserved across the update. A device may not support every combination and the driver for such a device must reject any combination which cannot be faithfully implemented.

Firmware Loading¶

Devices which require firmware to operate usually store it in non-volatile memory on the board, e.g. flash. Some devices store only basic firmware on the board, and the driver loads the rest from disk during probing. devlink-info allows users to query firmware information (loaded components and versions).

In other cases the device can both store the image on the board, load from disk, or automatically flash a new image from disk. The fw_load_policy devlink parameter can be used to control this behavior (Documentation/networking/devlink/devlink-params.rst).

On-disk firmware files are usually stored in /lib/firmware/.

Firmware Version Management¶

Drivers are expected to implement devlink-flash and devlink-info functionality, which together allow for implementing vendor-independent automated firmware update facilities.

devlink-info exposes the driver name and three version groups (fixed, running, stored).

The driver attribute and fixed group identify the specific device design, e.g. for looking up applicable firmware updates. This is why serial_number is not part of the fixed versions (even though it is fixed) - fixed versions should identify the design, not a single device.

running and stored firmware versions identify the firmware running on the device, and firmware which will be activated after reboot or device reset.

The firmware update agent is supposed to be able to follow this simple algorithm to update firmware contents, regardless of the device vendor:

# Get unique HW design identifier
$hw_id = devlink-dev-info['fixed']

# Find out which FW flash we want to use for this NIC
$want_flash_vers = some-db-backed.lookup($hw_id, 'flash')

# Update flash if necessary
if $want_flash_vers != devlink-dev-info['stored']:
    $file = some-db-backed.download($hw_id, 'flash')
    devlink-dev-flash($file)

# Find out the expected overall firmware versions
$want_fw_vers = some-db-backed.lookup($hw_id, 'all')

# Update on-disk file if necessary
if $want_fw_vers != devlink-dev-info['running']:
    $file = some-db-backed.download($hw_id, 'disk')
    write($file, '/lib/firmware/')

# Try device reset, if available
if $want_fw_vers != devlink-dev-info['running']:
   devlink-reset()

# Reboot, if reset wasn't enough
if $want_fw_vers != devlink-dev-info['running']:
   reboot()

Note that each reference to devlink-dev-info in this pseudo-code is expected to fetch up-to-date information from the kernel.

For the convenience of identifying firmware files some vendors add bundle_id information to the firmware versions. This meta-version covers multiple per-component versions and can be used e.g. in firmware file names (all component versions could get rather long.)

Previous Next

© Copyright The kernel development community.

Built with Sphinx using a theme provided by Read the Docs.