Describes the format of the newly added VPD capability and gives and
example for a real-world device.
---
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
