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 @@
</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 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>
+<device>
+ <name>pci_0000_42_00_0</name>
+ <capability type='pci'>
+ <class>0x020000</class>
+ <domain>0</domain>
+ <bus>66</bus>
+ <slot>0</slot>
+ <function>0</function>
+ <product id='0xa2d6'>MT42822 BlueField-2 integrated ConnectX-6 Dx network controller</product>
+ <vendor id='0x15b3'>Mellanox Technologies</vendor>
+ <capability type='virt_functions' maxCount='16'/>
+ <capability type='vpd'>
+ <name>BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB on-board DDR, 1GbE OOB management, Tall Bracket</name>
+ <fields access='readonly'>
+ <change_level>B1</change_level>
+ <manufacture_id>foobar</manufacture_id>
+ <part_number>MBF2H332A-AEEOT</part_number>
+ <serial_number>MT2113X00000</serial_number>
+ <vendor_field index='0'>PCIeGen4 x8</vendor_field>
+ <vendor_field index='2'>MBF2H332A-AEEOT</vendor_field>
+ <vendor_field index='3'>3c53d07eec484d8aab34dabd24fe575aa</vendor_field>
+ <vendor_field index='A'>MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A</vendor_field>
+ </fields>
+ <fields access='readwrite'>
+ <asset_tag>fooasset</asset_tag>
+ <vendor_field index='0'>vendorfield0</vendor_field>
+ <vendor_field index='2'>vendorfield2</vendor_field>
+ <vendor_field index='A'>vendorfieldA</vendor_field>
+ <system_field index='B'>systemfieldB</system_field>
+ <system_field index='0'>systemfield0</system_field>
+ </fields>
+ </capability>
+ <iommuGroup number='65'>
+ <address domain='0x0000' bus='0x42' slot='0x00' function='0x0'/>
+ </iommuGroup>
+ <numa node='0'/>
+ <pci-express>
+ <link validity='cap' port='0' speed='16' width='8'/>
+ <link validity='sta' speed='8' width='8'/>
+ </pci-express>
+ </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..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 @@
</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 <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
