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