1.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
3============
4Devlink Info
5============
6
7The ``devlink-info`` mechanism enables device drivers to report device
8(hardware and firmware) information in a standard, extensible fashion.
9
10The original motivation for the ``devlink-info`` API was twofold:
11
12 - making it possible to automate device and firmware management in a fleet
13   of machines in a vendor-independent fashion (see also
14   :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`);
15 - name the per component FW versions (as opposed to the crowded ethtool
16   version string).
17
18``devlink-info`` supports reporting multiple types of objects. Reporting driver
19versions is generally discouraged - here, and via any other Linux API.
20
21.. list-table:: List of top level info objects
22   :widths: 5 95
23
24   * - Name
25     - Description
26   * - ``driver``
27     - Name of the currently used device driver, also available through sysfs.
28
29   * - ``serial_number``
30     - Serial number of the device.
31
32       This is usually the serial number of the ASIC, also often available
33       in PCI config space of the device in the *Device Serial Number*
34       capability.
35
36       The serial number should be unique per physical device.
37       Sometimes the serial number of the device is only 48 bits long (the
38       length of the Ethernet MAC address), and since PCI DSN is 64 bits long
39       devices pad or encode additional information into the serial number.
40       One example is adding port ID or PCI interface ID in the extra two bytes.
41       Drivers should make sure to strip or normalize any such padding
42       or interface ID, and report only the part of the serial number
43       which uniquely identifies the hardware. In other words serial number
44       reported for two ports of the same device or on two hosts of
45       a multi-host device should be identical.
46
47       .. note:: ``devlink-info`` API should be extended with a new field
48	  if devices want to report board/product serial number (often
49	  reported in PCI *Vital Product Data* capability).
50
51   * - ``fixed``
52     - Group for hardware identifiers, and versions of components
53       which are not field-updatable.
54
55       Versions in this section identify the device design. For example,
56       component identifiers or the board version reported in the PCI VPD.
57       Data in ``devlink-info`` should be broken into the smallest logical
58       components, e.g. PCI VPD may concatenate various information
59       to form the Part Number string, while in ``devlink-info`` all parts
60       should be reported as separate items.
61
62       This group must not contain any frequently changing identifiers,
63       such as serial numbers. See
64       :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`
65       to understand why.
66
67   * - ``running``
68     - Group for information about currently running software/firmware.
69       These versions often only update after a reboot, sometimes device reset.
70
71   * - ``stored``
72     - Group for software/firmware versions in device flash.
73
74       Stored values must update to reflect changes in the flash even
75       if reboot has not yet occurred. If device is not capable of updating
76       ``stored`` versions when new software is flashed, it must not report
77       them.
78
79Each version can be reported at most once in each version group. Firmware
80components stored on the flash should feature in both the ``running`` and
81``stored`` sections, if device is capable of reporting ``stored`` versions
82(see :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
83In case software/firmware components are loaded from the disk (e.g.
84``/lib/firmware``) only the running version should be reported via
85the kernel API.
86
87Generic Versions
88================
89
90It is expected that drivers use the following generic names for exporting
91version information. If a generic name for a given component doesn't exist yet,
92driver authors should consult existing driver-specific versions and attempt
93reuse. As last resort, if a component is truly unique, using driver-specific
94names is allowed, but these should be documented in the driver-specific file.
95
96All versions should try to use the following terminology:
97
98.. list-table:: List of common version suffixes
99   :widths: 10 90
100
101   * - Name
102     - Description
103   * - ``id``, ``revision``
104     - Identifiers of designs and revision, mostly used for hardware versions.
105
106   * - ``api``
107     - Version of API between components. API items are usually of limited
108       value to the user, and can be inferred from other versions by the vendor,
109       so adding API versions is generally discouraged as noise.
110
111   * - ``bundle_id``
112     - Identifier of a distribution package which was flashed onto the device.
113       This is an attribute of a firmware package which covers multiple versions
114       for ease of managing firmware images (see
115       :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
116
117       ``bundle_id`` can appear in both ``running`` and ``stored`` versions,
118       but it must not be reported if any of the components covered by the
119       ``bundle_id`` was changed and no longer matches the version from
120       the bundle.
121
122board.id
123--------
124
125Unique identifier of the board design.
126
127board.rev
128---------
129
130Board design revision.
131
132asic.id
133-------
134
135ASIC design identifier.
136
137asic.rev
138--------
139
140ASIC design revision/stepping.
141
142board.manufacture
143-----------------
144
145An identifier of the company or the facility which produced the part.
146
147fw
148--
149
150Overall firmware version, often representing the collection of
151fw.mgmt, fw.app, etc.
152
153fw.mgmt
154-------
155
156Control unit firmware version. This firmware is responsible for house
157keeping tasks, PHY control etc. but not the packet-by-packet data path
158operation.
159
160fw.mgmt.api
161-----------
162
163Firmware interface specification version of the software interfaces between
164driver and firmware.
165
166fw.app
167------
168
169Data path microcode controlling high-speed packet processing.
170
171fw.undi
172-------
173
174UNDI software, may include the UEFI driver, firmware or both.
175
176fw.ncsi
177-------
178
179Version of the software responsible for supporting/handling the
180Network Controller Sideband Interface.
181
182fw.psid
183-------
184
185Unique identifier of the firmware parameter set. These are usually
186parameters of a particular board, defined at manufacturing time.
187
188fw.roce
189-------
190
191RoCE firmware version which is responsible for handling roce
192management.
193
194fw.bundle_id
195------------
196
197Unique identifier of the entire firmware bundle.
198
199Future work
200===========
201
202The following extensions could be useful:
203
204 - product serial number - NIC boards often get labeled with a board serial
205   number rather than ASIC serial number; it'd be useful to add board serial
206   numbers to the API if they can be retrieved from the device;
207
208 - on-disk firmware file names - drivers list the file names of firmware they
209   may need to load onto devices via the ``MODULE_FIRMWARE()`` macro. These,
210   however, are per module, rather than per device. It'd be useful to list
211   the names of firmware files the driver will try to load for a given device,
212   in order of priority.
213