| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
===================== |
| 4 |
ixgbe devlink support |
| 5 |
===================== |
| 6 |
|
| 7 |
This document describes the devlink features implemented by the ``ixgbe`` |
| 8 |
device driver. |
| 9 |
|
| 10 |
Info versions |
| 11 |
============= |
| 12 |
|
| 13 |
Any of the versions dealing with the security presented by ``devlink-info`` |
| 14 |
is purely informational. Devlink does not use a secure channel to communicate |
| 15 |
with the device. |
| 16 |
|
| 17 |
The ``ixgbe`` driver reports the following versions |
| 18 |
|
| 19 |
.. list-table:: devlink info versions implemented |
| 20 |
:widths: 5 5 5 90 |
| 21 |
|
| 22 |
* - Name |
| 23 |
- Type |
| 24 |
- Example |
| 25 |
- Description |
| 26 |
* - ``board.id`` |
| 27 |
- fixed |
| 28 |
- H49289-000 |
| 29 |
- The Product Board Assembly (PBA) identifier of the board. |
| 30 |
* - ``fw.undi`` |
| 31 |
- running |
| 32 |
- 1.1937.0 |
| 33 |
- Version of the Option ROM containing the UEFI driver. The version is |
| 34 |
reported in ``major.minor.patch`` format. The major version is |
| 35 |
incremented whenever a major breaking change occurs, or when the |
| 36 |
minor version would overflow. The minor version is incremented for |
| 37 |
non-breaking changes and reset to 1 when the major version is |
| 38 |
incremented. The patch version is normally 0 but is incremented when |
| 39 |
a fix is delivered as a patch against an older base Option ROM. |
| 40 |
* - ``fw.undi.srev`` |
| 41 |
- running |
| 42 |
- 4 |
| 43 |
- Number indicating the security revision of the Option ROM. |
| 44 |
* - ``fw.bundle_id`` |
| 45 |
- running |
| 46 |
- 0x80000d0d |
| 47 |
- Unique identifier of the firmware image file that was loaded onto |
| 48 |
the device. Also referred to as the EETRACK identifier of the NVM. |
| 49 |
* - ``fw.mgmt.api`` |
| 50 |
- running |
| 51 |
- 1.5.1 |
| 52 |
- 3-digit version number (major.minor.patch) of the API exported over |
| 53 |
the AdminQ by the management firmware. Used by the driver to |
| 54 |
identify what commands are supported. Historical versions of the |
| 55 |
kernel only displayed a 2-digit version number (major.minor). |
| 56 |
* - ``fw.mgmt.build`` |
| 57 |
- running |
| 58 |
- 0x305d955f |
| 59 |
- Unique identifier of the source for the management firmware. |
| 60 |
* - ``fw.mgmt.srev`` |
| 61 |
- running |
| 62 |
- 3 |
| 63 |
- Number indicating the security revision of the firmware. |
| 64 |
* - ``fw.psid.api`` |
| 65 |
- running |
| 66 |
- 0.80 |
| 67 |
- Version defining the format of the flash contents. |
| 68 |
* - ``fw.netlist`` |
| 69 |
- running |
| 70 |
- 1.1.2000-6.7.0 |
| 71 |
- The version of the netlist module. This module defines the device's |
| 72 |
Ethernet capabilities and default settings, and is used by the |
| 73 |
management firmware as part of managing link and device |
| 74 |
connectivity. |
| 75 |
* - ``fw.netlist.build`` |
| 76 |
- running |
| 77 |
- 0xee16ced7 |
| 78 |
- The first 4 bytes of the hash of the netlist module contents. |
| 79 |
|
| 80 |
Flash Update |
| 81 |
============ |
| 82 |
|
| 83 |
The ``ixgbe`` driver implements support for flash update using the |
| 84 |
``devlink-flash`` interface. It supports updating the device flash using a |
| 85 |
combined flash image that contains the ``fw.mgmt``, ``fw.undi``, and |
| 86 |
``fw.netlist`` components. |
| 87 |
|
| 88 |
.. list-table:: List of supported overwrite modes |
| 89 |
:widths: 5 95 |
| 90 |
|
| 91 |
* - Bits |
| 92 |
- Behavior |
| 93 |
* - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` |
| 94 |
- Do not preserve settings stored in the flash components being |
| 95 |
updated. This includes overwriting the port configuration that |
| 96 |
determines the number of physical functions the device will |
| 97 |
initialize with. |
| 98 |
* - ``DEVLINK_FLASH_OVERWRITE_SETTINGS`` and ``DEVLINK_FLASH_OVERWRITE_IDENTIFIERS`` |
| 99 |
- Do not preserve either settings or identifiers. Overwrite everything |
| 100 |
in the flash with the contents from the provided image, without |
| 101 |
performing any preservation. This includes overwriting device |
| 102 |
identifying fields such as the MAC address, Vital product Data (VPD) area, |
| 103 |
and device serial number. It is expected that this combination be used with an |
| 104 |
image customized for the specific device. |
| 105 |
|
| 106 |
Reload |
| 107 |
====== |
| 108 |
|
| 109 |
The ``ixgbe`` driver supports activating new firmware after a flash update |
| 110 |
using ``DEVLINK_CMD_RELOAD`` with the ``DEVLINK_RELOAD_ACTION_FW_ACTIVATE`` |
| 111 |
action. |
| 112 |
|
| 113 |
.. code:: shell |
| 114 |
|
| 115 |
$ devlink dev reload pci/0000:01:00.0 reload action fw_activate |
| 116 |
|
| 117 |
The new firmware is activated by issuing a device specific Embedded |
| 118 |
Management Processor reset which requests the device to reset and reload the |
| 119 |
EMP firmware image. |
| 120 |
|
| 121 |
The driver does not currently support reloading the driver via |
| 122 |
``DEVLINK_RELOAD_ACTION_DRIVER_REINIT``. |
| 123 |
|
| 124 |
Regions |
| 125 |
======= |
| 126 |
|
| 127 |
The ``ixgbe`` driver implements the following regions for accessing internal |
| 128 |
device data. |
| 129 |
|
| 130 |
.. list-table:: regions implemented |
| 131 |
:widths: 15 85 |
| 132 |
|
| 133 |
* - Name |
| 134 |
- Description |
| 135 |
* - ``nvm-flash`` |
| 136 |
- The contents of the entire flash chip, sometimes referred to as |
| 137 |
the device's Non Volatile Memory. |
| 138 |
* - ``shadow-ram`` |
| 139 |
- The contents of the Shadow RAM, which is loaded from the beginning |
| 140 |
of the flash. Although the contents are primarily from the flash, |
| 141 |
this area also contains data generated during device boot which is |
| 142 |
not stored in flash. |
| 143 |
* - ``device-caps`` |
| 144 |
- The contents of the device firmware's capabilities buffer. Useful to |
| 145 |
determine the current state and configuration of the device. |
| 146 |
|
| 147 |
Both the ``nvm-flash`` and ``shadow-ram`` regions can be accessed without a |
| 148 |
snapshot. The ``device-caps`` region requires a snapshot as the contents are |
| 149 |
sent by firmware and can't be split into separate reads. |
| 150 |
|
| 151 |
Users can request an immediate capture of a snapshot for all three regions |
| 152 |
via the ``DEVLINK_CMD_REGION_NEW`` command. |
| 153 |
|
| 154 |
.. code:: shell |
| 155 |
|
| 156 |
$ devlink region show |
| 157 |
pci/0000:01:00.0/nvm-flash: size 10485760 snapshot [] max 1 |
| 158 |
pci/0000:01:00.0/device-caps: size 4096 snapshot [] max 10 |
| 159 |
|
| 160 |
$ devlink region new pci/0000:01:00.0/nvm-flash snapshot 1 |
| 161 |
|
| 162 |
$ devlink region dump pci/0000:01:00.0/nvm-flash snapshot 1 |
| 163 |
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 |
| 164 |
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8 |
| 165 |
0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc |
| 166 |
0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5 |
| 167 |
|
| 168 |
$ devlink region read pci/0000:01:00.0/nvm-flash snapshot 1 address 0 length 16 |
| 169 |
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 |
| 170 |
|
| 171 |
$ devlink region delete pci/0000:01:00.0/device-caps snapshot 1 |