[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.shcherba...@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 @@
   &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 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>
+&lt;device&gt;
+  &lt;!-- ... --&gt;
+  &lt;driver&gt;
+    &lt;name&gt;mlx5_core&lt;/name&gt;
+  &lt;/driver&gt;
+  &lt;capability type=&apos;pci&apos;&gt;
+    &lt;!-- ... --&gt;
+    &lt;capability type=&apos;vpd&apos;&gt;
+      &lt;resource type=&apos;string&apos;&gt;BlueField-2 DPU 25GbE Dual-Port 
SFP56, 16GB on-board DDR, 1GbE OOB management, Tall Bracket&lt;/resource&gt;
+      &lt;resource type=&apos;vpd-r&apos;&gt;
+        &lt;field keyword=&apos;SN&apos;&gt;MT2113X00000&lt;/field&gt;
+        &lt;field 
keyword=&apos;V3&apos;&gt;d644e35a61d0eb11e000e8cef671bf3e&lt;/field&gt;
+        &lt;field 
keyword=&apos;VA&apos;&gt;MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A&lt;/field&gt;
+        &lt;field keyword=&apos;PN&apos;&gt;MBF2H332A-AEEOT&lt;/field&gt;
+        &lt;field keyword=&apos;V2&apos;&gt;MBF2H332A-AEEOT&lt;/field&gt;
+        &lt;field keyword=&apos;EC&apos;&gt;B1&lt;/field&gt;
+        &lt;field keyword=&apos;V0&apos;&gt;PCIeGen4 x8&lt;/field&gt;
+      &lt;/resource&gt;
+    &lt;/capability&gt;
+  &lt;!-- ... --&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..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 @@
 &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 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