Orange Pi5 kernel

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