openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add PCI VPD Capability Documentation 

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
Show Stats 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

63
docs/formatnode.html.in
View File

@ -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>
@ -523,6 +529,61 @@
</dl>
</p>
<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>
<h2><a id="nodeExample">Examples</a></h2>