0001 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002
0003 ============
0004 Devlink Info
0005 ============
0006
0007 The ``devlink-info`` mechanism enables device drivers to report device
0008 (hardware and firmware) information in a standard, extensible fashion.
0009
0010 The original motivation for the ``devlink-info`` API was twofold:
0011
0012 - making it possible to automate device and firmware management in a fleet
0013 of machines in a vendor-independent fashion (see also
0014 :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`);
0015 - name the per component FW versions (as opposed to the crowded ethtool
0016 version string).
0017
0018 ``devlink-info`` supports reporting multiple types of objects. Reporting driver
0019 versions is generally discouraged - here, and via any other Linux API.
0020
0021 .. list-table:: List of top level info objects
0022 :widths: 5 95
0023
0024 * - Name
0025 - Description
0026 * - ``driver``
0027 - Name of the currently used device driver, also available through sysfs.
0028
0029 * - ``serial_number``
0030 - Serial number of the device.
0031
0032 This is usually the serial number of the ASIC, also often available
0033 in PCI config space of the device in the *Device Serial Number*
0034 capability.
0035
0036 The serial number should be unique per physical device.
0037 Sometimes the serial number of the device is only 48 bits long (the
0038 length of the Ethernet MAC address), and since PCI DSN is 64 bits long
0039 devices pad or encode additional information into the serial number.
0040 One example is adding port ID or PCI interface ID in the extra two bytes.
0041 Drivers should make sure to strip or normalize any such padding
0042 or interface ID, and report only the part of the serial number
0043 which uniquely identifies the hardware. In other words serial number
0044 reported for two ports of the same device or on two hosts of
0045 a multi-host device should be identical.
0046
0047 * - ``board.serial_number``
0048 - Board serial number of the device.
0049
0050 This is usually the serial number of the board, often available in
0051 PCI *Vital Product Data*.
0052
0053 * - ``fixed``
0054 - Group for hardware identifiers, and versions of components
0055 which are not field-updatable.
0056
0057 Versions in this section identify the device design. For example,
0058 component identifiers or the board version reported in the PCI VPD.
0059 Data in ``devlink-info`` should be broken into the smallest logical
0060 components, e.g. PCI VPD may concatenate various information
0061 to form the Part Number string, while in ``devlink-info`` all parts
0062 should be reported as separate items.
0063
0064 This group must not contain any frequently changing identifiers,
0065 such as serial numbers. See
0066 :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`
0067 to understand why.
0068
0069 * - ``running``
0070 - Group for information about currently running software/firmware.
0071 These versions often only update after a reboot, sometimes device reset.
0072
0073 * - ``stored``
0074 - Group for software/firmware versions in device flash.
0075
0076 Stored values must update to reflect changes in the flash even
0077 if reboot has not yet occurred. If device is not capable of updating
0078 ``stored`` versions when new software is flashed, it must not report
0079 them.
0080
0081 Each version can be reported at most once in each version group. Firmware
0082 components stored on the flash should feature in both the ``running`` and
0083 ``stored`` sections, if device is capable of reporting ``stored`` versions
0084 (see :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
0085 In case software/firmware components are loaded from the disk (e.g.
0086 ``/lib/firmware``) only the running version should be reported via
0087 the kernel API.
0088
0089 Generic Versions
0090 ================
0091
0092 It is expected that drivers use the following generic names for exporting
0093 version information. If a generic name for a given component doesn't exist yet,
0094 driver authors should consult existing driver-specific versions and attempt
0095 reuse. As last resort, if a component is truly unique, using driver-specific
0096 names is allowed, but these should be documented in the driver-specific file.
0097
0098 All versions should try to use the following terminology:
0099
0100 .. list-table:: List of common version suffixes
0101 :widths: 10 90
0102
0103 * - Name
0104 - Description
0105 * - ``id``, ``revision``
0106 - Identifiers of designs and revision, mostly used for hardware versions.
0107
0108 * - ``api``
0109 - Version of API between components. API items are usually of limited
0110 value to the user, and can be inferred from other versions by the vendor,
0111 so adding API versions is generally discouraged as noise.
0112
0113 * - ``bundle_id``
0114 - Identifier of a distribution package which was flashed onto the device.
0115 This is an attribute of a firmware package which covers multiple versions
0116 for ease of managing firmware images (see
0117 :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
0118
0119 ``bundle_id`` can appear in both ``running`` and ``stored`` versions,
0120 but it must not be reported if any of the components covered by the
0121 ``bundle_id`` was changed and no longer matches the version from
0122 the bundle.
0123
0124 board.id
0125 --------
0126
0127 Unique identifier of the board design.
0128
0129 board.rev
0130 ---------
0131
0132 Board design revision.
0133
0134 asic.id
0135 -------
0136
0137 ASIC design identifier.
0138
0139 asic.rev
0140 --------
0141
0142 ASIC design revision/stepping.
0143
0144 board.manufacture
0145 -----------------
0146
0147 An identifier of the company or the facility which produced the part.
0148
0149 fw
0150 --
0151
0152 Overall firmware version, often representing the collection of
0153 fw.mgmt, fw.app, etc.
0154
0155 fw.mgmt
0156 -------
0157
0158 Control unit firmware version. This firmware is responsible for house
0159 keeping tasks, PHY control etc. but not the packet-by-packet data path
0160 operation.
0161
0162 fw.mgmt.api
0163 -----------
0164
0165 Firmware interface specification version of the software interfaces between
0166 driver and firmware.
0167
0168 fw.app
0169 ------
0170
0171 Data path microcode controlling high-speed packet processing.
0172
0173 fw.undi
0174 -------
0175
0176 UNDI software, may include the UEFI driver, firmware or both.
0177
0178 fw.ncsi
0179 -------
0180
0181 Version of the software responsible for supporting/handling the
0182 Network Controller Sideband Interface.
0183
0184 fw.psid
0185 -------
0186
0187 Unique identifier of the firmware parameter set. These are usually
0188 parameters of a particular board, defined at manufacturing time.
0189
0190 fw.roce
0191 -------
0192
0193 RoCE firmware version which is responsible for handling roce
0194 management.
0195
0196 fw.bundle_id
0197 ------------
0198
0199 Unique identifier of the entire firmware bundle.
0200
0201 Future work
0202 ===========
0203
0204 The following extensions could be useful:
0205
0206 - on-disk firmware file names - drivers list the file names of firmware they
0207 may need to load onto devices via the ``MODULE_FIRMWARE()`` macro. These,
0208 however, are per module, rather than per device. It'd be useful to list
0209 the names of firmware files the driver will try to load for a given device,
0210 in order of priority.
