[libvirt PATCH v5 7/7] Add PCI VPD Capability Documentation

[Dmitrii Shcherbakov]

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 at canonical.com>
---
 docs/drvnodedev.html.in | 46 +++++++++++++++++++++++++++++++++++++++++
 docs/formatnode.html.in | 24 ++++++++++++++++++++-
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
index 70f7e6717d..438d20f2dd 100644
--- a/docs/drvnodedev.html.in
+++ b/docs/drvnodedev.html.in
@@ -185,6 +185,52 @@
   </capability>
 </device></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 all resources (string, read-only
+      and read-write keyword resources) that may be contained in a valid VPD
+      entry. 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 a string resource and a VPD-R resource. Among other things,
+      the VPD of this particular device includes a unique board serial number in the
+      "SN" field.
+    </p>
+<pre>
+<device>
+  <!-- ... -->
+  <driver>
+    <name>mlx5_core</name>
+  </driver>
+  <capability type='pci'>
+    <!-- ... -->
+    <capability type='vpd'>
+      <resource type='string'>BlueField-2 DPU 25GbE Dual-Port SFP56, 16GB on-board DDR, 1GbE OOB management, Tall Bracket</resource>
+      <resource type='vpd-r'>
+        <field keyword='SN'>MT2113X00000</field>
+        <field keyword='V3'>d644e35a61d0eb11e000e8cef671bf3e</field>
+        <field keyword='VA'>MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A</field>
+        <field keyword='PN'>MBF2H332A-AEEOT</field>
+        <field keyword='V2'>MBF2H332A-AEEOT</field>
+        <field keyword='EC'>B1</field>
+        <field keyword='V0'>PCIeGen4 x8</field>
+      </resource>
+    </capability>
+  <!-- ... -->
+  </capability>
+</device>
+</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..3e8c771398 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,21 @@
 </device>
     </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 list of
+      <code>resource</code> elements with contents applicable to a
+      particular resource type (string or keyword resources). The
+      <code>resource</code> element will either contain a string
+      resource value or a list of <code>field</code> elements in
+      the case of keyword resources. <code>field</code> elements
+      contain a <code>keyword</code> attribute corresponding to the
+      2-byte VPD keyword and text as element data representing the
+      field value.
+    </p>
   </body>
 </html>
-- 
2.30.2