networking/devlink/devlink-info.rst

1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
7 The ``devlink-info`` mechanism enables device drivers to report device
10 The original motivation for the ``devlink-info`` API was twofold:
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
18 ``devlink-info`` supports reporting multiple types of objects. Reporting driver
19 versions is generally discouraged - here, and via any other Linux API.
21 .. list-table:: List of top level info objects
24    * - Name
25      - Description
26    * - ``driver``
27      - Name of the currently used device driver, also available through sysfs.
29    * - ``serial_number``
30      - Serial number of the device.
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*
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
42        or interface ID, and report only the part of the serial number
44        reported for two ports of the same device or on two hosts of
45        a multi-host device should be identical.
47    * - ``board.serial_number``
48      - Board serial number of the device.
50        This is usually the serial number of the board, often available in
53    * - ``fixed``
54      - Group for hardware identifiers, and versions of components
55        which are not field-updatable.
59        Data in ``devlink-info`` should be broken into the smallest logical
61        to form the Part Number string, while in ``devlink-info`` all parts
66        :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`
69    * - ``running``
70      - Group for information about currently running software/firmware.
73    * - ``stored``
74      - Group for software/firmware versions in device flash.
77        if reboot has not yet occurred. If device is not capable of updating
83 ``stored`` sections, if device is capable of reporting ``stored`` versions
84 (see :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
92 It is expected that drivers use the following generic names for exporting
94 driver authors should consult existing driver-specific versions and attempt
95 reuse. As last resort, if a component is truly unique, using driver-specific
96 names is allowed, but these should be documented in the driver-specific file.
98 All versions should try to use the following terminology:
100 .. list-table:: List of common version suffixes
103    * - Name
104      - Description
105    * - ``id``, ``revision``
106      - Identifiers of designs and revision, mostly used for hardware versions.
108    * - ``api``
109      - Version of API between components. API items are usually of limited
113    * - ``bundle_id``
114      - Identifier of a distribution package which was flashed onto the device.
115        This is an attribute of a firmware package which covers multiple versions
116        for ease of managing firmware images (see
117        :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`).
120        but it must not be reported if any of the components covered by the
125 --------
127 Unique identifier of the board design.
130 ---------
135 -------
140 --------
145 -----------------
147 An identifier of the company or the facility which produced the part.
150 -----------------
152 Part number of the board and its components.
155 --
157 Overall firmware version, often representing the collection of
161 -------
164 keeping tasks, PHY control etc. but not the packet-by-packet data path
168 -----------
170 Firmware interface specification version of the software interfaces between
174 ------
176 Data path microcode controlling high-speed packet processing.
179 -------
184 -------
186 Version of the software responsible for supporting/handling the
190 -------
192 Unique identifier of the firmware parameter set. These are usually
193 parameters of a particular board, defined at manufacturing time.
196 -------
202 ------------
204 Unique identifier of the entire firmware bundle.
207 -------------
209 Version of the bootloader.
216  - on-disk firmware file names - drivers list the file names of firmware they
219    the names of firmware files the driver will try to load for a given device,
220    in order of priority.