NuKVM/libvirt
3
0
Fork 0
mirror of https://github.com/libvirt/libvirt.git synced 2025-02-25 18:55:26 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add PCI VPD Capability Documentation

Browse Source 
Describes the format of the newly added VPD capability and gives and
example for a real-world device.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Dmitrii Shcherbakov <dmitrii.shcherbakov@canonical.com>
This commit is contained in:
Dmitrii Shcherbakov
2021-10-20 11:30:34 +03:00
committed by Daniel P. Berrangé
parent 3954378d06
commit fab3513bf0
2 changed files with 131 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/drvnodedev.html.in
View File

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