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