mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-08-27 11:01:19 +00:00
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:
parent
3954378d06
commit
fab3513bf0
@ -185,6 +185,75 @@
|
|||||||
</capability>
|
</capability>
|
||||||
</device></pre>
|
</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>
|
<h2><a id="MDEV">Mediated devices (MDEVs)</a></h2>
|
||||||
<p>
|
<p>
|
||||||
Mediated devices (<span class="since">Since 3.2.0</span>) are software
|
Mediated devices (<span class="since">Since 3.2.0</span>) are software
|
||||||
|
@ -162,7 +162,13 @@
|
|||||||
This device is capable of creating mediated devices.
|
This device is capable of creating mediated devices.
|
||||||
The sub-elements are summarized in
|
The sub-elements are summarized in
|
||||||
<a href="#MDEVTypesCap">mdev_types capability</a>.
|
<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>
|
</dl>
|
||||||
</dd>
|
</dd>
|
||||||
|
|
||||||
@ -523,6 +529,61 @@
|
|||||||
</dl>
|
</dl>
|
||||||
</p>
|
</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>
|
<h2><a id="nodeExample">Examples</a></h2>
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user