Documentation/networking/devlink/devlink-info.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/devlink/devlink-info.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/devlink/devlink-info.rst
Extension
.rst
Size
7240 bytes
Lines
225
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

============
Devlink Info
============

The ``devlink-info`` mechanism enables device drivers to report device
(hardware and firmware) information in a standard, extensible fashion.

The original motivation for the ``devlink-info`` API was twofold:

 - making it possible to automate device and firmware management in a fleet
   of machines in a vendor-independent fashion (see also
   :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`);
 - name the per component FW versions (as opposed to the crowded ethtool
   version string).

``devlink-info`` supports reporting multiple types of objects. Reporting driver
versions is generally discouraged - here, and via any other Linux API.

.. list-table:: List of top level info objects
   :widths: 5 95

   * - Name
     - Description
   * - ``driver``
     - Name of the currently used device driver, also available through sysfs.

   * - ``serial_number``
     - Serial number of the device.

       This is usually the serial number of the ASIC, also often available
       in PCI config space of the device in the *Device Serial Number*
       capability.

       The serial number should be unique per physical device.
       Sometimes the serial number of the device is only 48 bits long (the
       length of the Ethernet MAC address), and since PCI DSN is 64 bits long
       devices pad or encode additional information into the serial number.
       One example is adding port ID or PCI interface ID in the extra two bytes.
       Drivers should make sure to strip or normalize any such padding
       or interface ID, and report only the part of the serial number
       which uniquely identifies the hardware. In other words serial number
       reported for two ports of the same device or on two hosts of
       a multi-host device should be identical.

   * - ``board.serial_number``
     - Board serial number of the device.

       This is usually the serial number of the board, often available in
       PCI *Vital Product Data*.

   * - ``fixed``
     - Group for hardware identifiers, and versions of components
       which are not field-updatable.

       Versions in this section identify the device design. For example,
       component identifiers or the board version reported in the PCI VPD.
       Data in ``devlink-info`` should be broken into the smallest logical
       components, e.g. PCI VPD may concatenate various information
       to form the Part Number string, while in ``devlink-info`` all parts
       should be reported as separate items.

       This group must not contain any frequently changing identifiers,
       such as serial numbers. See
       :ref:`Documentation/networking/devlink/devlink-flash.rst <devlink_flash>`
       to understand why.

   * - ``running``
     - Group for information about currently running software/firmware.

Annotation

Implementation Notes