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> +

VPD capability

+

+ A device that exposes a PCI/PCIe VPD capability will include a nested + capability vpd 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, + virsh nodedev-dumpxml must be executed accordingly. + A description of the XML format for the vpd capability can + be found here. +

+

+ 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. +

+
+<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>
+
+

Mediated devices (MDEVs)

Mediated devices (Since 3.2.0) are software diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in index 3b3c3105d4..5a34a356ce 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 mdev_types capability. - + +

vpd
+
+ This device exposes a VPD PCI/PCIe capability. + The sub-elements are summarized in + vpd capability. +
@@ -523,6 +529,61 @@

+

vpd capability

+ +

+ PCI 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 capability + element with the vpd type will contain a name + element (containing a manufacturer-provided device name) and optionally + one or two fields elements with an access + attribute set to readonly or readwrite. +

+

+ The read-only fields element may contain the following elements: +

+
change_level
+
An engineering change level for this add-in card.
+
manufacture_id
+
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.
+
part_number
+
An extension to the Device ID (or Subsystem ID) in the Configuration + Space header specifying a part number of an add-in card.
+
serial_number
+
A unique add-in card Serial Number.
+
vendor_field
+
Zero or many of those elements with an index attribute + (since-character upper-case ASCII alphanumeric indexes). Contents will vary + depending on a vendor.
+
+ All fields are optional and are not guaranteed to be present for a generic PCI device. +

+

+ The read-write fields element may contain the following elements: +

+
asset_tag
+
A system asset identifier provided by the system owner.
+
vendor_field
+
Zero or many of those elements with an index attribute + (since-character upper-case ASCII alphanumeric indexes). Contents will vary depending + on a vendor.
+
system_field
+
Zero or many of those elements with an index attribute (since-character + upper-case ASCII alphanumeric indexes, except for letter 'A'). May store system-specific + data related to a PCI device.
+
+ 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. +

+

+ The device name and all fields may contain only the following characters: + [0-9a-zA-F -_,.:;=]. + The device name may be as large as 65535 bytes while fields are limited with 255 bytes. +

Examples