Documentation/networking/devlink/devlink-flash.rst

   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 Firmware Loading
  20 ================
  21
  22 Devices which require firmware to operate usually store it in non-volatile
  23 memory on the board, e.g. flash. Some devices store only basic firmware on
  24 the board, and the driver loads the rest from disk during probing.
  25 ``devlink-info`` allows users to query firmware information (loaded
  26 components and versions).
  27
  28 In other cases the device can both store the image on the board, load from
  29 disk, or automatically flash a new image from disk. The ``fw_load_policy``
  30 devlink parameter can be used to control this behavior
  31 (:ref:`Documentation/networking/devlink/devlink-params.rst <devlink_params_generic>`).
  32
  33 On-disk firmware files are usually stored in ``/lib/firmware/``.
  34
  35 Firmware Version Management
  36 ===========================
  37
  38 Drivers are expected to implement ``devlink-flash`` and ``devlink-info``
  39 functionality, which together allow for implementing vendor-independent
  40 automated firmware update facilities.
  41
  42 ``devlink-info`` exposes the ``driver`` name and three version groups
  43 (``fixed``, ``running``, ``stored``).
  44
  45 The ``driver`` attribute and ``fixed`` group identify the specific device
  46 design, e.g. for looking up applicable firmware updates. This is why
  47 ``serial_number`` is not part of the ``fixed`` versions (even though it
  48 is fixed) - ``fixed`` versions should identify the design, not a single
  49 device.
  50
  51 ``running`` and ``stored`` firmware versions identify the firmware running
  52 on the device, and firmware which will be activated after reboot or device
  53 reset.
  54
  55 The firmware update agent is supposed to be able to follow this simple
  56 algorithm to update firmware contents, regardless of the device vendor:
  57
  58 .. code-block:: sh
  59
  60   # Get unique HW design identifier
  61   $hw_id = devlink-dev-info['fixed']
  62
  63   # Find out which FW flash we want to use for this NIC
  64   $want_flash_vers = some-db-backed.lookup($hw_id, 'flash')
  65
  66   # Update flash if necessary
  67   if $want_flash_vers != devlink-dev-info['stored']:
  68       $file = some-db-backed.download($hw_id, 'flash')
  69       devlink-dev-flash($file)
  70
  71   # Find out the expected overall firmware versions
  72   $want_fw_vers = some-db-backed.lookup($hw_id, 'all')
  73
  74   # Update on-disk file if necessary
  75   if $want_fw_vers != devlink-dev-info['running']:
  76       $file = some-db-backed.download($hw_id, 'disk')
  77       write($file, '/lib/firmware/')
  78
  79   # Try device reset, if available
  80   if $want_fw_vers != devlink-dev-info['running']:
  81      devlink-reset()
  82
  83   # Reboot, if reset wasn't enough
  84   if $want_fw_vers != devlink-dev-info['running']:
  85      reboot()
  86
  87 Note that each reference to ``devlink-dev-info`` in this pseudo-code
  88 is expected to fetch up-to-date information from the kernel.
  89
  90 For the convenience of identifying firmware files some vendors add
  91 ``bundle_id`` information to the firmware versions. This meta-version covers
  92 multiple per-component versions and can be used e.g. in firmware file names
  93 (all component versions could get rather long.)