networking/devlink/devlink-flash.rst

1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
6 Devlink Flash
9 The ``devlink-flash`` API allows updating device firmware. It replaces the
10 older ``ethtool-flash`` mechanism, and doesn't require taking any
11 networking locks in the kernel to perform the flash update. Example use::
13   $ devlink dev flash pci/0000:05:00.0 file flash-boot.bin
22 The ``devlink-flash`` command allows optionally specifying a mask indicating
23 how the device should handle subsections of flash components when updating.
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
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
56 In other cases the device can both store the image on the board, load from
57 disk, or automatically flash a new image from disk. The ``fw_load_policy``
59 (:ref:`Documentation/networking/devlink/devlink-params.rst <devlink_params_generic>`).
61 On-disk firmware files are usually stored in ``/lib/firmware/``.
66 Drivers are expected to implement ``devlink-flash`` and ``devlink-info``
67 functionality, which together allow for implementing vendor-independent
70 ``devlink-info`` exposes the ``driver`` name and three version groups
76 is fixed) - ``fixed`` versions should identify the design, not a single
80 on the device, and firmware which will be activated after reboot or device
86 .. code-block:: sh
89   $hw_id = devlink-dev-info['fixed']
91   # Find out which FW flash we want to use for this NIC
92   $want_flash_vers = some-db-backed.lookup($hw_id, 'flash')
94   # Update flash if necessary
95   if $want_flash_vers != devlink-dev-info['stored']:
96       $file = some-db-backed.download($hw_id, 'flash')
97       devlink-dev-flash($file)
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')
108   if $want_fw_vers != devlink-dev-info['running']:
109      devlink-reset()
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.
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