| 1 |
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) |
| 2 |
|
| 3 |
.. _devlink_flash: |
| 4 |
|
| 5 |
============= |
| 6 |
Devlink Flash |
| 7 |
============= |
| 8 |
|
| 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:: |
| 12 |
|
| 13 |
$ devlink dev flash pci/0000:05:00.0 file flash-boot.bin |
| 14 |
|
| 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 |
| 17 |
user space about the progress of the update operation. |
| 18 |
|
| 19 |
Overwrite Mask |
| 20 |
============== |
| 21 |
|
| 22 |
The ``devlink-flash`` command allows optionally specifying a mask indicating |
| 23 |
how the device should handle subsections of flash components when updating. |
| 24 |
This mask indicates the set of sections which are allowed to be overwritten. |
| 25 |
|
| 26 |
.. list-table:: List of overwrite mask bits |
| 27 |
:widths: 5 95 |
| 28 |
|
| 29 |
* - Name |
| 30 |
- Description |
| 31 |
* - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` |
| 32 |
- Indicates that the device should overwrite settings in the components |
| 33 |
being updated with the settings found in the provided image. |
| 34 |
* - ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` |
| 35 |
- Indicates that the device should overwrite identifiers in the |
| 36 |
components being updated with the identifiers found in the provided |
| 37 |
image. This includes MAC addresses, serial IDs, and similar device |
| 38 |
identifiers. |
| 39 |
|
| 40 |
Multiple overwrite bits may be combined and requested together. If no bits |
| 41 |
are provided, it is expected that the device only update firmware binaries |
| 42 |
in the components being updated. Settings and identifiers are expected to be |
| 43 |
preserved across the update. A device may not support every combination and |
| 44 |
the driver for such a device must reject any combination which cannot be |
| 45 |
faithfully implemented. |
| 46 |
|
| 47 |
Firmware Loading |
| 48 |
================ |
| 49 |
|
| 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 |
| 52 |
the board, and the driver loads the rest from disk during probing. |
| 53 |
``devlink-info`` allows users to query firmware information (loaded |
| 54 |
components and versions). |
| 55 |
|
| 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`` |
| 58 |
devlink parameter can be used to control this behavior |
| 59 |
(:ref:`Documentation/networking/devlink/devlink-params.rst <devlink_params_generic>`). |
| 60 |
|
| 61 |
On-disk firmware files are usually stored in ``/lib/firmware/``. |
| 62 |
|
| 63 |
Firmware Version Management |
| 64 |
=========================== |
| 65 |
|
| 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. |
| 69 |
|
| 70 |
``devlink-info`` exposes the ``driver`` name and three version groups |
| 71 |
(``fixed``, ``running``, ``stored``). |
| 72 |
|
| 73 |
The ``driver`` attribute and ``fixed`` group identify the specific device |
| 74 |
design, e.g. for looking up applicable firmware updates. This is why |
| 75 |
``serial_number`` is not part of the ``fixed`` versions (even though it |
| 76 |
is fixed) - ``fixed`` versions should identify the design, not a single |
| 77 |
device. |
| 78 |
|
| 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. |
| 82 |
|
| 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: |
| 85 |
|
| 86 |
.. code-block:: sh |
| 87 |
|
| 88 |
# Get unique HW design identifier |
| 89 |
$hw_id = devlink-dev-info['fixed'] |
| 90 |
|
| 91 |
# Find out which FW flash we want to use for this NIC |
| 92 |
$want_flash_vers = some-db-backed.lookup($hw_id, 'flash') |
| 93 |
|
| 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) |
| 98 |
|
| 99 |
# Find out the expected overall firmware versions |
| 100 |
$want_fw_vers = some-db-backed.lookup($hw_id, 'all') |
| 101 |
|
| 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/') |
| 106 |
|
| 107 |
# Try device reset, if available |
| 108 |
if $want_fw_vers != devlink-dev-info['running']: |
| 109 |
devlink-reset() |
| 110 |
|
| 111 |
# Reboot, if reset wasn't enough |
| 112 |
if $want_fw_vers != devlink-dev-info['running']: |
| 113 |
reboot() |
| 114 |
|
| 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. |
| 117 |
|
| 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 |
| 121 |
(all component versions could get rather long.) |