networking/devlink/devlink-flash.rst

1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
9 The ``devlink-flash`` API allows updating device firmware. It replaces the
10 older ``ethtool-flash`` mechanism, and doesn't require taking any
13   $ devlink dev flash pci/0000:05:00.0 file flash-boot.bin
15 Note that the file name is a path relative to the firmware loading path
16 (usually ``/lib/firmware/``). Drivers may send status updates to inform
22 The ``devlink-flash`` command allows optionally specifying a mask indicating
26 .. list-table:: List of overwrite mask bits
29    * - Name
30      - Description
31    * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS``
32      - Indicates that the device should overwrite settings in the components
34    * - ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS``
35      - Indicates that the device should overwrite identifiers in the
41 are provided, it is expected that the device only update firmware binaries
47 Firmware Loading
50 Devices which require firmware to operate usually store it in non-volatile
51 memory on the board, e.g. flash. Some devices store only basic firmware on
53 ``devlink-info`` allows users to query firmware information (loaded
59 (:ref:`Documentation/networking/devlink/devlink-params.rst <devlink_params_generic>`).
61 On-disk firmware files are usually stored in ``/lib/firmware/``.
63 Firmware Version Management
66 Drivers are expected to implement ``devlink-flash`` and ``devlink-info``
67 functionality, which together allow for implementing vendor-independent
68 automated firmware update facilities.
70 ``devlink-info`` exposes the ``driver`` name and three version groups
74 design, e.g. for looking up applicable firmware updates. This is why
76 is fixed) - ``fixed`` versions should identify the design, not a single
79 ``running`` and ``stored`` firmware versions identify the firmware running
80 on the device, and firmware which will be activated after reboot or device
81 reset.
83 The firmware update agent is supposed to be able to follow this simple
84 algorithm to update firmware contents, regardless of the device vendor:
86 .. code-block:: sh
89   $hw_id = devlink-dev-info['fixed']
92   $want_flash_vers = some-db-backed.lookup($hw_id, 'flash')
95   if $want_flash_vers != devlink-dev-info['stored']:
96       $file = some-db-backed.download($hw_id, 'flash')
97       devlink-dev-flash($file)
99   # Find out the expected overall firmware versions
100   $want_fw_vers = some-db-backed.lookup($hw_id, 'all')
102   # Update on-disk file if necessary
103   if $want_fw_vers != devlink-dev-info['running']:
104       $file = some-db-backed.download($hw_id, 'disk')
105       write($file, '/lib/firmware/')
107   # Try device reset, if available
108   if $want_fw_vers != devlink-dev-info['running']:
109      devlink-reset()
111   # Reboot, if reset wasn't enough
112   if $want_fw_vers != devlink-dev-info['running']:
115 Note that each reference to ``devlink-dev-info`` in this pseudo-code
116 is expected to fetch up-to-date information from the kernel.
118 For the convenience of identifying firmware files some vendors add
119 ``bundle_id`` information to the firmware versions. This meta-version covers
120 multiple per-component versions and can be used e.g. in firmware file names