[libvirt PATCH v7 4/5] Add PCI VPD Capability Documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Describes the format of the newly added VPD capability and gives and
example for a real-world device.

Signed-off-by: Dmitrii Shcherbakov <dmitrii.shcherbakov@xxxxxxxxxxxxx>
---
 docs/drvnodedev.html.in | 69 +++++++++++++++++++++++++++++++++++++++++
 docs/formatnode.html.in | 63 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 131 insertions(+), 1 deletion(-)

diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
index 70f7e6717d..ee75eeb25c 100644
--- a/docs/drvnodedev.html.in
+++ b/docs/drvnodedev.html.in
@@ -185,6 +185,75 @@
   &lt;/capability&gt;
 &lt;/device&gt;</pre>
 
+    <h3><a id="VPDCap">VPD capability</a></h3>
+    <p>
+      A device that exposes a PCI/PCIe VPD capability will include a nested
+      capability <code>vpd</code> which presents data stored in the Vital Product
+      Data (VPD). VPD provides a device name and a number of other standard-defined
+      read-only fields (change level, manufacture id, part number, serial number) and
+      vendor-specific read-only fields. Additionally, if a device supports it,
+      read-write fields (asset tag, vendor-specific fields or system fields) may
+      also be present. The VPD capability is optional for PCI/PCIe devices and the
+      set of exposed fields may vary depending on a device. The XML format follows
+      the binary format described in "I.3. VPD Definitions" in PCI Local Bus (2.2+)
+      and the identical format in PCIe 4.0+. At the time of writing, the support for
+      exposing this capability is only present on Linux-based systems (kernel version
+      v2.6.26 is the first one to expose VPD via sysfs which Libvirt relies on).
+      Reading the VPD contents requires root privileges, therefore,
+      <code>virsh nodedev-dumpxml</code> must be executed accordingly.
+      A description of the XML format for the <code>vpd</code> capability can
+      be found <a href="formatnode.html#VPDCap">here</a>.
+    </p>
+    <p>
+      The following example shows a VPD representation for a device that exposes the
+      VPD capability with read-only and read-write fields. Among other things,
+      the VPD of this particular device includes a unique board serial number.
+    </p>
+<pre>
+&lt;device&gt;
+  &lt;name&gt;pci_0000_42_00_0&lt;/name&gt;
+  &lt;capability type=&apos;pci&apos;&gt;
+    &lt;class&gt;0x020000&lt;/class&gt;
+    &lt;domain&gt;0&lt;/domain&gt;
+    &lt;bus&gt;66&lt;/bus&gt;
+    &lt;slot&gt;0&lt;/slot&gt;
+    &lt;function&gt;0&lt;/function&gt;
+    &lt;product id=&apos;0xa2d6&apos;&gt;MT42822 BlueField-2 integrated ConnectX-6 Dx network controller&lt;/product&gt;
+    &lt;vendor id=&apos;0x15b3&apos;&gt;Mellanox Technologies&lt;/vendor&gt;
+    &lt;capability type=&apos;virt_functions&apos; maxCount=&apos;16&apos;/&gt;
+    &lt;capability type=&apos;vpd&apos;&gt;
+      &lt;name&gt;BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB on-board DDR, 1GbE OOB management, Tall Bracket&lt;/name&gt;
+      &lt;fields access=&apos;readonly&apos;&gt;
+        &lt;change_level&gt;B1&lt;/change_level&gt;
+        &lt;manufacture_id&gt;foobar&lt;/manufacture_id&gt;
+        &lt;part_number&gt;MBF2H332A-AEEOT&lt;/part_number&gt;
+        &lt;serial_number&gt;MT2113X00000&lt;/serial_number&gt;
+        &lt;vendor_field index=&apos;0&apos;&gt;PCIeGen4 x8&lt;/vendor_field&gt;
+        &lt;vendor_field index=&apos;2&apos;&gt;MBF2H332A-AEEOT&lt;/vendor_field&gt;
+        &lt;vendor_field index=&apos;3&apos;&gt;3c53d07eec484d8aab34dabd24fe575aa&lt;/vendor_field&gt;
+        &lt;vendor_field index=&apos;A&apos;&gt;MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A&lt;/vendor_field&gt;
+      &lt;/fields&gt;
+      &lt;fields access=&apos;readwrite&apos;&gt;
+        &lt;asset_tag&gt;fooasset&lt;/asset_tag&gt;
+        &lt;vendor_field index=&apos;0&apos;&gt;vendorfield0&lt;/vendor_field&gt;
+        &lt;vendor_field index=&apos;2&apos;&gt;vendorfield2&lt;/vendor_field&gt;
+        &lt;vendor_field index=&apos;A&apos;&gt;vendorfieldA&lt;/vendor_field&gt;
+        &lt;system_field index=&apos;B&apos;&gt;systemfieldB&lt;/system_field&gt;
+        &lt;system_field index=&apos;0&apos;&gt;systemfield0&lt;/system_field&gt;
+      &lt;/fields&gt;
+    &lt;/capability&gt;
+    &lt;iommuGroup number=&apos;65&apos;&gt;
+      &lt;address domain=&apos;0x0000&apos; bus=&apos;0x42&apos; slot=&apos;0x00&apos; function=&apos;0x0&apos;/&gt;
+    &lt;/iommuGroup&gt;
+    &lt;numa node=&apos;0&apos;/&gt;
+    &lt;pci-express&gt;
+      &lt;link validity=&apos;cap&apos; port=&apos;0&apos; speed=&apos;16&apos; width=&apos;8&apos;/&gt;
+      &lt;link validity=&apos;sta&apos; speed=&apos;8&apos; width=&apos;8&apos;/&gt;
+    &lt;/pci-express&gt;
+  &lt;/capability&gt;
+&lt;/device&gt;
+</pre>
+
     <h2><a id="MDEV">Mediated devices (MDEVs)</a></h2>
     <p>
       Mediated devices (<span class="since">Since 3.2.0</span>) are software
diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in
index 3b3c3105d4..fb2f356396 100644
--- a/docs/formatnode.html.in
+++ b/docs/formatnode.html.in
@@ -162,7 +162,13 @@
                     This device is capable of creating mediated devices.
                     The sub-elements are summarized in
                     <a href="#MDEVTypesCap">mdev_types capability</a>.
-                 </dd>
+                  </dd>
+                  <dt><code><a id="VPDCapPCI">vpd</a></code></dt>
+                  <dd>
+                    This device exposes a VPD PCI/PCIe capability.
+                    The sub-elements are summarized in
+                    <a href="#VPDCap">vpd capability</a>.
+                  </dd>
                 </dl>
               </dd>
 
@@ -592,5 +598,60 @@
 &lt;/device&gt;
     </pre>
 
+    <h3><a id="VPDCap">vpd capability</a></h3>
+
+    <p>
+      <a href="#VPDCapPCI">PCI</a> devices can expose a VPD capability which
+      is optional per PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If
+      the VPD capability is present, then the parent <code>capability</code>
+      element with the <code>vpd</code> type will contain a <code>name</code>
+      element (containing a manufacturer-provided device name) and optionally
+      one or two <code>fields</code> elements with an <code>access</code>
+      attribute set to <code>readonly</code> or <code>readwrite</code>.
+    </p>
+    <p>
+      The read-only <code>fields</code> element may contain the following elements:
+      <dl>
+        <dt><code>change_level</code></dt>
+        <dd>An engineering change level for this add-in card.</dd>
+        <dt><code>manufacture_id</code></dt>
+        <dd>An extension to the Vendor ID (or Subsystem Vendor ID) in the
+          Configuration Space header which allows vendors the flexibility to identify
+          an additional level of detail pertaining to the sourcing of a PCI device.</dd>
+        <dt><code>part_number</code></dt>
+        <dd>An extension to the Device ID (or Subsystem ID) in the Configuration
+          Space header specifying a part number of an add-in card.</dd>
+        <dt><code>serial_number</code></dt>
+        <dd>A unique add-in card Serial Number.</dd>
+        <dt><code>vendor_field</code></dt>
+        <dd>Zero or many of those elements with an <code>index</code> attribute
+          (since-character upper-case ASCII alphanumeric indexes). Contents will vary
+          depending on a vendor.</dd>
+      </dl>
+      All fields are optional and are not guaranteed to be present for a generic PCI device.
+    </p>
+    <p>
+      The read-write <code>fields</code> element may contain the following elements:
+      <dl>
+        <dt><code>asset_tag</code></dt>
+        <dd>A system asset identifier provided by the system owner.</dd>
+        <dt><code>vendor_field</code></dt>
+        <dd>Zero or many of those elements with an <code>index</code> attribute
+          (since-character upper-case ASCII alphanumeric indexes). Contents will vary depending
+          on a vendor.</dd>
+        <dt><code>system_field</code></dt>
+        <dd>Zero or many of those elements with an <code>index</code> attribute (since-character
+          upper-case ASCII alphanumeric indexes, except for letter 'A'). May store system-specific
+          data related to a PCI device.</dd>
+      </dl>
+      All fields are optional and are not guaranteed to be present for a generic PCI device.
+      Read-write fields are not possible to alter via Libvirt at the time of writing but their
+      content is refreshed on each invocation in case this is done by means external to Libvirt.
+    </p>
+    <p>
+      The device name and all fields may contain only the following characters:
+      <code>[0-9a-zA-F -_,.:;=]</code>.
+      The device name may be as large as 65535 bytes while fields are limited with 255 bytes.
+    </p>
   </body>
 </html>
-- 
2.32.0





[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux