1 .. SPDX-License-Identifier: (GPL-2.0-only OR B 1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 2
3 .. _devlink_flash: 3 .. _devlink_flash:
4 4
5 ============= 5 =============
6 Devlink Flash 6 Devlink Flash
7 ============= 7 =============
8 8
9 The ``devlink-flash`` API allows updating devi 9 The ``devlink-flash`` API allows updating device firmware. It replaces the
10 older ``ethtool-flash`` mechanism, and doesn't 10 older ``ethtool-flash`` mechanism, and doesn't require taking any
11 networking locks in the kernel to perform the 11 networking locks in the kernel to perform the flash update. Example use::
12 12
13 $ devlink dev flash pci/0000:05:00.0 file fl 13 $ devlink dev flash pci/0000:05:00.0 file flash-boot.bin
14 14
15 Note that the file name is a path relative to 15 Note that the file name is a path relative to the firmware loading path
16 (usually ``/lib/firmware/``). Drivers may send 16 (usually ``/lib/firmware/``). Drivers may send status updates to inform
17 user space about the progress of the update op 17 user space about the progress of the update operation.
18 18
19 Overwrite Mask 19 Overwrite Mask
20 ============== 20 ==============
21 21
22 The ``devlink-flash`` command allows optionall 22 The ``devlink-flash`` command allows optionally specifying a mask indicating
23 how the device should handle subsections of fl 23 how the device should handle subsections of flash components when updating.
24 This mask indicates the set of sections which 24 This mask indicates the set of sections which are allowed to be overwritten.
25 25
26 .. list-table:: List of overwrite mask bits 26 .. list-table:: List of overwrite mask bits
27 :widths: 5 95 27 :widths: 5 95
28 28
29 * - Name 29 * - Name
30 - Description 30 - Description
31 * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` 31 * - ``DEVLINK_FLASH_OVERWRITE_SETTINGS``
32 - Indicates that the device should overwr 32 - Indicates that the device should overwrite settings in the components
33 being updated with the settings found i 33 being updated with the settings found in the provided image.
34 * - ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` 34 * - ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS``
35 - Indicates that the device should overwr 35 - Indicates that the device should overwrite identifiers in the
36 components being updated with the ident 36 components being updated with the identifiers found in the provided
37 image. This includes MAC addresses, ser 37 image. This includes MAC addresses, serial IDs, and similar device
38 identifiers. 38 identifiers.
39 39
40 Multiple overwrite bits may be combined and re 40 Multiple overwrite bits may be combined and requested together. If no bits
41 are provided, it is expected that the device o 41 are provided, it is expected that the device only update firmware binaries
42 in the components being updated. Settings and 42 in the components being updated. Settings and identifiers are expected to be
43 preserved across the update. A device may not 43 preserved across the update. A device may not support every combination and
44 the driver for such a device must reject any c 44 the driver for such a device must reject any combination which cannot be
45 faithfully implemented. 45 faithfully implemented.
46 46
47 Firmware Loading 47 Firmware Loading
48 ================ 48 ================
49 49
50 Devices which require firmware to operate usua 50 Devices which require firmware to operate usually store it in non-volatile
51 memory on the board, e.g. flash. Some devices 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 52 the board, and the driver loads the rest from disk during probing.
53 ``devlink-info`` allows users to query firmwar 53 ``devlink-info`` allows users to query firmware information (loaded
54 components and versions). 54 components and versions).
55 55
56 In other cases the device can both store the i 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 57 disk, or automatically flash a new image from disk. The ``fw_load_policy``
58 devlink parameter can be used to control this 58 devlink parameter can be used to control this behavior
59 (:ref:`Documentation/networking/devlink/devlin 59 (:ref:`Documentation/networking/devlink/devlink-params.rst <devlink_params_generic>`).
60 60
61 On-disk firmware files are usually stored in ` 61 On-disk firmware files are usually stored in ``/lib/firmware/``.
62 62
63 Firmware Version Management 63 Firmware Version Management
64 =========================== 64 ===========================
65 65
66 Drivers are expected to implement ``devlink-fl 66 Drivers are expected to implement ``devlink-flash`` and ``devlink-info``
67 functionality, which together allow for implem 67 functionality, which together allow for implementing vendor-independent
68 automated firmware update facilities. 68 automated firmware update facilities.
69 69
70 ``devlink-info`` exposes the ``driver`` name a 70 ``devlink-info`` exposes the ``driver`` name and three version groups
71 (``fixed``, ``running``, ``stored``). 71 (``fixed``, ``running``, ``stored``).
72 72
73 The ``driver`` attribute and ``fixed`` group i 73 The ``driver`` attribute and ``fixed`` group identify the specific device
74 design, e.g. for looking up applicable firmwar 74 design, e.g. for looking up applicable firmware updates. This is why
75 ``serial_number`` is not part of the ``fixed`` 75 ``serial_number`` is not part of the ``fixed`` versions (even though it
76 is fixed) - ``fixed`` versions should identify 76 is fixed) - ``fixed`` versions should identify the design, not a single
77 device. 77 device.
78 78
79 ``running`` and ``stored`` firmware versions i 79 ``running`` and ``stored`` firmware versions identify the firmware running
80 on the device, and firmware which will be acti 80 on the device, and firmware which will be activated after reboot or device
81 reset. 81 reset.
82 82
83 The firmware update agent is supposed to be ab 83 The firmware update agent is supposed to be able to follow this simple
84 algorithm to update firmware contents, regardl 84 algorithm to update firmware contents, regardless of the device vendor:
85 85
86 .. code-block:: sh 86 .. code-block:: sh
87 87
88 # Get unique HW design identifier 88 # Get unique HW design identifier
89 $hw_id = devlink-dev-info['fixed'] 89 $hw_id = devlink-dev-info['fixed']
90 90
91 # Find out which FW flash we want to use for 91 # Find out which FW flash we want to use for this NIC
92 $want_flash_vers = some-db-backed.lookup($hw 92 $want_flash_vers = some-db-backed.lookup($hw_id, 'flash')
93 93
94 # Update flash if necessary 94 # Update flash if necessary
95 if $want_flash_vers != devlink-dev-info['sto 95 if $want_flash_vers != devlink-dev-info['stored']:
96 $file = some-db-backed.download($hw_id, 96 $file = some-db-backed.download($hw_id, 'flash')
97 devlink-dev-flash($file) 97 devlink-dev-flash($file)
98 98
99 # Find out the expected overall firmware ver 99 # Find out the expected overall firmware versions
100 $want_fw_vers = some-db-backed.lookup($hw_id 100 $want_fw_vers = some-db-backed.lookup($hw_id, 'all')
101 101
102 # Update on-disk file if necessary 102 # Update on-disk file if necessary
103 if $want_fw_vers != devlink-dev-info['runnin 103 if $want_fw_vers != devlink-dev-info['running']:
104 $file = some-db-backed.download($hw_id, 104 $file = some-db-backed.download($hw_id, 'disk')
105 write($file, '/lib/firmware/') 105 write($file, '/lib/firmware/')
106 106
107 # Try device reset, if available 107 # Try device reset, if available
108 if $want_fw_vers != devlink-dev-info['runnin 108 if $want_fw_vers != devlink-dev-info['running']:
109 devlink-reset() 109 devlink-reset()
110 110
111 # Reboot, if reset wasn't enough 111 # Reboot, if reset wasn't enough
112 if $want_fw_vers != devlink-dev-info['runnin 112 if $want_fw_vers != devlink-dev-info['running']:
113 reboot() 113 reboot()
114 114
115 Note that each reference to ``devlink-dev-info 115 Note that each reference to ``devlink-dev-info`` in this pseudo-code
116 is expected to fetch up-to-date information fr 116 is expected to fetch up-to-date information from the kernel.
117 117
118 For the convenience of identifying firmware fi 118 For the convenience of identifying firmware files some vendors add
119 ``bundle_id`` information to the firmware vers 119 ``bundle_id`` information to the firmware versions. This meta-version covers
120 multiple per-component versions and can be use 120 multiple per-component versions and can be used e.g. in firmware file names
121 (all component versions could get rather long. 121 (all component versions could get rather long.)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.