mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-03 20:01:16 +00:00
fab3513bf0
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>
658 lines
30 KiB
XML
658 lines
30 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Node devices XML format</h1>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a id="NodedevAttributes">Node Device XML</a></h2>
|
|
|
|
<p>
|
|
There are several libvirt functions, all with the
|
|
prefix <code>virNodeDevice</code>, which deal with management of
|
|
host devices that can be handed to guests via passthrough as
|
|
<hostdev> elements
|
|
in <a href="formatdomain.html#elementsHostDev">the domain XML</a>.
|
|
These devices are represented as a hierarchy, where a device on
|
|
a bus has a parent of the bus controller device; the root of the
|
|
hierarchy is the node named "computer".
|
|
</p>
|
|
|
|
<p>
|
|
When represented in XML, a node device uses the
|
|
top-level <code>device</code> element, with the following
|
|
elements present according to the type of device:
|
|
</p>
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>The name for this device. The name will be alphanumeric,
|
|
with words separated by underscore. For many devices, the
|
|
name is just the bus type and address, as in
|
|
"pci_0000_00_02_1" or "usb_1_5_3", but some devices are able
|
|
to provide more specific names, such as
|
|
"net_eth1_00_27_13_6a_fe_00". This is a read-only field that is
|
|
reported by the device driver. If this element is set when defining a
|
|
new device, it will be ignored.
|
|
|
|
</dd>
|
|
<dt><code>path</code></dt>
|
|
<dd>
|
|
Fully qualified sysfs path to the device. This is a read-only field
|
|
that is reported by the device driver. If this element is set when
|
|
defining a new device, it will be ignored.
|
|
</dd>
|
|
<dt><code>parent</code></dt>
|
|
<dd>
|
|
This element identifies the parent node in the device hierarchy. The
|
|
value of the element will correspond with the device parent's
|
|
<code>name</code> element or <code>computer</code> if the device does
|
|
not have any parent.
|
|
</dd>
|
|
<dt><code>driver</code></dt>
|
|
<dd>
|
|
This elements reports the driver in use for this device. The presence
|
|
of this element in the output XML depends on whether the underlying
|
|
device manager (most likely udev) exposes information about the
|
|
driver.
|
|
</dd>
|
|
<dt><code>devnode</code></dt>
|
|
<dd>This node appears for each associated <code>/dev</code>
|
|
special file. A mandatory attribute <code>type</code> specify
|
|
the kind of file path, which may be either <code>dev</code> for
|
|
the main name, or <code>link</code> for additional symlinks.
|
|
</dd>
|
|
<dt><code>capability</code></dt>
|
|
<dd>This node appears for each capability that libvirt
|
|
associates with a node. A mandatory
|
|
attribute <code>type</code> lists which category the device
|
|
belongs to, and controls which further subelements will be
|
|
present to describe the node:
|
|
<dl>
|
|
<dt><code>system</code></dt>
|
|
<dd>Describes the overall host. Sub-elements include:
|
|
<dl>
|
|
<dt><code>product</code></dt>
|
|
<dd>If present, a simple text string giving the product
|
|
name of the system.</dd>
|
|
<dt><code>hardware</code></dt>
|
|
<dd>Describes the hardware of the system, including
|
|
sub-elements for <code>vendor</code>, <code>version</code>,
|
|
<code>serial</code>, and <code>uuid</code>.</dd>
|
|
<dt><code>firmware</code></dt>
|
|
<dd>Describes the firmware of the system, including
|
|
sub-elements for <code>vendor</code>, <code>version</code>,
|
|
and <code>release_date</code>.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>pci</code></dt>
|
|
<dd>Describes a device on the host's PCI bus. Sub-elements
|
|
include:
|
|
<dl>
|
|
<dt><code>class</code></dt>
|
|
<dd>Optional element for combined class, subclass and
|
|
programming interface codes as 6-digit hexadecimal number.
|
|
<span class="since">Since 5.2.0</span></dd>
|
|
<dt><code>domain</code></dt>
|
|
<dd>Which domain the device belongs to.</dd>
|
|
<dt><code>bus</code></dt>
|
|
<dd>Which bus within the domain.</dd>
|
|
<dt><code>slot</code></dt>
|
|
<dd>Which slot within the bus.</dd>
|
|
<dt><code>function</code></dt>
|
|
<dd>Which function within the slot.</dd>
|
|
<dt><code>product</code></dt>
|
|
<dd>Product details from the device ROM, including an
|
|
attribute <code>id</code> with the hexadecimal product
|
|
id, and an optional text description of that id.</dd>
|
|
<dt><code>vendor</code></dt>
|
|
<dd>Vendor details from the device ROM, including an
|
|
attribute <code>id</code> with the hexadecimal vendor
|
|
id, and an optional text name of that vendor.</dd>
|
|
<dt><code>iommuGroup</code></dt>
|
|
<dd>
|
|
This optional element describes the "IOMMU group" this
|
|
device belongs to. If the element exists, it has a
|
|
mandatory <code>number</code> attribute which tells
|
|
the group number used for management of the group (all
|
|
devices in group "n" will be found in
|
|
"/sys/kernel/iommu_groups/n"). It will also have a
|
|
list of <code>address</code> subelements, each
|
|
containing the PCI address of a device in the same
|
|
group. The toplevel device will itself be included in
|
|
this list.
|
|
</dd>
|
|
<dt><code>capability</code></dt>
|
|
<dd>
|
|
This optional element can occur multiple times. If it
|
|
exists, it has a mandatory <code>type</code> attribute
|
|
which will be set to:
|
|
<dl>
|
|
<dt><code>phys_function</code></dt>
|
|
<dd>
|
|
That means there will be a single <code>address</code>
|
|
subelement which contains the PCI address of the SRIOV
|
|
Physical Function (PF) that is the parent of this device
|
|
(and this device is, by implication, an SRIOV Virtual
|
|
Function (VF)).
|
|
</dd>
|
|
<dt><code>virt_functions</code></dt>
|
|
<dd>
|
|
In this case this device is an SRIOV PF, and the capability
|
|
element will have a list of <code>address</code>
|
|
subelements, one for each VF on this PF. If the host system
|
|
supports reporting it (via the "sriov_totalvfs" file in the
|
|
device's sysfs directory) the capability element will also
|
|
have an attribute named <code>maxCount</code> which is the
|
|
maximum number of SRIOV VFs supported by this device, which
|
|
could be higher than the number of VFs that are currently
|
|
active <span class="since">since 1.3.0</span>; in this case,
|
|
even if there are currently no active VFs the
|
|
virtual_functions capabililty will still be shown.
|
|
</dd>
|
|
<dt><code>pci-bridge</code> or <code>cardbus-bridge</code></dt>
|
|
<dd>
|
|
This shows merely that the lower 7 bits of PCI header type
|
|
have either value of 1 or 2 respectively. Usually this
|
|
means such device cannot be used for PCI passthrough.
|
|
<span class="since">Since 1.3.3</span>
|
|
</dd>
|
|
<dt><code><a id="MDEVTypesCapPCI">mdev_types</a></code></dt>
|
|
<dd>
|
|
This device is capable of creating mediated devices.
|
|
The sub-elements are summarized in
|
|
<a href="#MDEVTypesCap">mdev_types capability</a>.
|
|
</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>
|
|
|
|
<dt><code>numa</code></dt>
|
|
<dd>
|
|
This optional element contains information on the PCI device
|
|
with respect to NUMA. For example, the optional
|
|
<code>node</code> attribute tells which NUMA node is the PCI
|
|
device associated with.
|
|
</dd>
|
|
<dt><code>pci-express</code></dt>
|
|
<dd>
|
|
This optional element contains information on PCI Express part of
|
|
the device. For example, it can contain a child element
|
|
<code>link</code> which addresses the PCI Express device's link.
|
|
While a device has its own capabilities
|
|
(<code>validity='cap'</code>), the actual run time capabilities
|
|
are negotiated on the device initialization
|
|
(<code>validity='sta'</code>). The <code>link</code> element then
|
|
contains three attributes: <code>port</code> which says in which
|
|
port is the device plugged in, <code>speed</code> (in
|
|
GigaTransfers per second) and <code>width</code> for the number
|
|
of lanes used. Since the port can't be negotiated, it's not
|
|
exposed in <code>./pci-express/link/[@validity='sta']</code>.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>usb_device</code></dt>
|
|
<dd>Describes a device on the host's USB bus, based on its
|
|
location within the bus. Sub-elements include:
|
|
<dl>
|
|
<dt><code>bus</code></dt>
|
|
<dd>Which bus the device belongs to.</dd>
|
|
<dt><code>device</code></dt>
|
|
<dd>Which device within the bus.</dd>
|
|
<dt><code>product</code></dt>
|
|
<dd>Product details from the device ROM, including an
|
|
attribute <code>id</code> with the hexadecimal product
|
|
id, and an optional text description of that id.</dd>
|
|
<dt><code>vendor</code></dt>
|
|
<dd>Vendor details from the device ROM, including an
|
|
attribute <code>id</code> with the hexadecimal vendor
|
|
id, and an optional text name of that vendor.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>usb</code></dt>
|
|
<dd>Describes a USB device, based on its advertised driver
|
|
interface. Sub-elements include:
|
|
<dl>
|
|
<dt><code>number</code></dt>
|
|
<dd>The device number.</dd>
|
|
<dt><code>class</code></dt>
|
|
<dd>The device class.</dd>
|
|
<dt><code>subclass</code></dt>
|
|
<dd>The device subclass.</dd>
|
|
<dt><code>protocol</code></dt>
|
|
<dd>The device protocol.</dd>
|
|
<dt><code>description</code></dt>
|
|
<dd>If present, a description of the device.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>net</code></dt>
|
|
<dd>Describes a device capable for use as a network
|
|
interface. Sub-elements include:
|
|
<dl>
|
|
<dt><code>interface</code></dt>
|
|
<dd>The interface name tied to this device.</dd>
|
|
<dt><code>address</code></dt>
|
|
<dd>If present, the MAC address of the device.</dd>
|
|
<dt><code>link</code></dt>
|
|
<dd>Optional to reflect the status of the link. It has
|
|
two optional attributes: <code>speed</code> in Mbits per
|
|
second and <code>state</code> to tell the state of the
|
|
link. So far, the whole element is just for output,
|
|
not setting.
|
|
</dd>
|
|
<dt><code>feature</code></dt>
|
|
<dd>If present, the hw offloads supported by this network
|
|
interface. Possible features are:
|
|
<dl>
|
|
<dt><code>rx</code></dt><dd>rx-checksumming</dd>
|
|
<dt><code>tx</code></dt><dd>tx-checksumming</dd>
|
|
<dt><code>sg</code></dt><dd>scatter-gather</dd>
|
|
<dt><code>tso</code></dt><dd>tcp-segmentation-offload</dd>
|
|
<dt><code>ufo</code></dt><dd>udp-fragmentation-offload</dd>
|
|
<dt><code>gso</code></dt><dd>generic-segmentation-offload</dd>
|
|
<dt><code>gro</code></dt><dd>generic-receive-offload</dd>
|
|
<dt><code>lro</code></dt><dd>large-receive-offload</dd>
|
|
<dt><code>rxvlan</code></dt><dd>rx-vlan-offload</dd>
|
|
<dt><code>txvlan</code></dt><dd>tx-vlan-offload</dd>
|
|
<dt><code>ntuple</code></dt><dd>ntuple-filters</dd>
|
|
<dt><code>rxhash</code></dt><dd>receive-hashing</dd>
|
|
<dt><code>rdma</code></dt><dd>remote-direct-memory-access</dd>
|
|
<dt><code>txudptnl</code></dt><dd>tx-udp-tunnel-segmentation</dd>
|
|
<dt><code>switchdev</code></dt><dd>kernel-forward-plane-offload</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>capability</code></dt>
|
|
<dd>A network protocol exposed by the device, where the
|
|
attribute <code>type</code> can be "80203" for IEEE
|
|
802.3, or "80211" for various flavors of IEEE 802.11.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>scsi_host</code></dt>
|
|
<dd>Describes a SCSI host device. Sub-elements include:
|
|
<dl>
|
|
<dt><code>host</code></dt>
|
|
<dd>The SCSI host number.</dd>
|
|
<dt><code>unique_id</code></dt>
|
|
<dd>On input, this optionally provides the value from the
|
|
'unique_id' file found in the scsi_host's directory. To
|
|
view the values of all 'unique_id' files, use <code>find -H
|
|
/sys/class/scsi_host/host{0..9}/unique_id |
|
|
xargs grep '[0-9]'</code>. On output, if the unique_id
|
|
file exists, the value from the file will be displayed.
|
|
This can be used in order to help uniquely identify the
|
|
scsi_host adapter in a <a href="formatstorage.html">
|
|
Storage Pool</a>. <span class="since">Since 1.2.7</span>
|
|
</dd>
|
|
<dt><code>capability</code></dt>
|
|
<dd>Current capabilities include "vports_ops" (indicates
|
|
vport operations are supported) and "fc_host". "vport_ops"
|
|
could contain two optional sub-elements: <code>vports</code>,
|
|
and <code>max_vports</code>. <code>vports</code> shows the
|
|
number of vport in use. <code>max_vports</code> shows the
|
|
maximum vports the HBA supports. "fc_host" implies following
|
|
sub-elements: <code>wwnn</code>, <code>wwpn</code>, and
|
|
optionally <code>fabric_wwn</code>.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>scsi</code></dt>
|
|
<dd>Describes a SCSI device. Sub-elements include:
|
|
<dl>
|
|
<dt><code>host</code></dt>
|
|
<dd>The SCSI host containing the device.</dd>
|
|
<dt><code>bus</code></dt>
|
|
<dd>The bus within the host.</dd>
|
|
<dt><code>target</code></dt>
|
|
<dd>The target within the bus.</dd>
|
|
<dt><code>lun</code></dt>
|
|
<dd>The lun within the target.</dd>
|
|
<dt><code>type</code></dt>
|
|
<dd>The type of SCSI device.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>storage</code></dt>
|
|
<dd>Describes a device usable for storage. Sub-elements
|
|
include:
|
|
<dl>
|
|
<dt><code>block</code></dt>
|
|
<dd>A block device file name that accesses the storage
|
|
present on the device.</dd>
|
|
<dt><code>bus</code></dt>
|
|
<dd>If present, the name of the bus the device is found
|
|
on.</dd>
|
|
<dt><code>drive_type</code></dt>
|
|
<dd>The type of the drive, such as "disk" or
|
|
"cdrom".</dd>
|
|
<dt><code>model</code></dt>
|
|
<dd>Any model information available from the
|
|
device.</dd>
|
|
<dt><code>vendor</code></dt>
|
|
<dd>Any vendor information available from the
|
|
device.</dd>
|
|
<dt><code>serial</code></dt>
|
|
<dd>Any serial number information available from the
|
|
device.</dd>
|
|
<dt><code>size</code></dt>
|
|
<dd>For fixed-size storage, the amount of storage
|
|
available.</dd>
|
|
<dt><code>capability</code></dt>
|
|
<dd>If present, an additional capability is listed via
|
|
the attribute <code>type</code>. Current capabilities
|
|
include "hotpluggable" and "removable", with the
|
|
latter implying the following
|
|
sub-elements: <code>media_available</code> (0 or
|
|
1), <code>media_size</code>,
|
|
and <code>media_label</code>.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>drm</code></dt>
|
|
<dd>Describes a Direct Rendering Manager (DRM) device.
|
|
Sub-elements include:
|
|
<dl>
|
|
<dt><code>type</code></dt>
|
|
<dd>The type of DRM device. Could be
|
|
<code>primary</code>, <code>control</code> or
|
|
<code>render</code>.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><a id="mdev"><code>mdev</code></a></dt>
|
|
<dd>Describes a mediated device. <span class="since">Since
|
|
3.4.0</span> Sub-elements include:
|
|
<dl>
|
|
<dt><code>type</code></dt>
|
|
<dd>
|
|
Describes a mediated device type which acts as an abstract
|
|
template defining a resource allocation for instances
|
|
of this device type. The element has one attribute
|
|
<code>id</code> which holds an official vendor-supplied
|
|
identifier for the type.
|
|
</dd>
|
|
<dt><code>iommuGroup</code></dt>
|
|
<dd>
|
|
This element supports a single attribute <code>number</code>
|
|
which holds the IOMMU group number to which the mediated device
|
|
belongs. This is a read-only field that is reported by the
|
|
device driver.
|
|
</dd>
|
|
<dt><code>attr</code></dt>
|
|
<dd>
|
|
This optional element can occur multiple times. It represents a
|
|
vendor-specific attribute that is used to configure this
|
|
mediated device. It has two required attributes:
|
|
<code>name</code> and <code>value</code>. Note that the order
|
|
in which attributes are set may be important for some devices.
|
|
The order that they appear in the xml definition determines the
|
|
order that they will be written to the device.
|
|
</dd>
|
|
<dt><code>uuid</code></dt>
|
|
<dd>
|
|
This element represents the UUID of the mediated device.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>ccw</code></dt>
|
|
<dd>Describes a Command Channel Word (CCW) device commonly found on
|
|
the S390 architecture. Sub-elements include:
|
|
<dl>
|
|
<dt><code>cssid</code></dt>
|
|
<dd>The channel subsystem identifier.</dd>
|
|
<dt><code>ssid</code></dt>
|
|
<dd>The subchannel-set identifier.</dd>
|
|
<dt><code>devno</code></dt>
|
|
<dd>The device number.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>css</code></dt>
|
|
<dd>Describes a subchannel in the Channel SubSystem (CSS) commonly
|
|
found on the S390 architecture. Sub-elements include:
|
|
<dl>
|
|
<dt><code>cssid</code></dt>
|
|
<dd>The channel subsystem identifier.</dd>
|
|
<dt><code>ssid</code></dt>
|
|
<dd>The subchannel-set identifier.</dd>
|
|
<dt><code>devno</code></dt>
|
|
<dd>The subchannel number.</dd>
|
|
<dt><code>capability</code></dt>
|
|
<dd>
|
|
This optional element can occur multiple times. If it
|
|
exists, it has a mandatory <code>type</code> attribute
|
|
which will be set to:
|
|
<dl>
|
|
<dt><code><a id="MDEVTypesCapCSS">mdev_types</a></code></dt>
|
|
<dd>
|
|
<span class="since">Since 6.10.0</span>
|
|
This device is capable of creating mediated devices.
|
|
The sub-elements are summarized in
|
|
<a href="#MDevTypesCap">mdev_types capability</a>.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>vdpa</code></dt>
|
|
<dd>Describes a virtual datapath acceleration (vDPA) network device.
|
|
<span class="since">Since 6.9.0</span>. Sub-elements include:
|
|
<dl>
|
|
<dt><code>chardev</code></dt>
|
|
<dd>The path to the character device that is used to access the
|
|
device.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>ap_card</code></dt>
|
|
<dd>Describes the Adjunct Processor (AP) Card device on a S390 host.
|
|
Sub-elements include:
|
|
<dl>
|
|
<dt><code>ap-adapter</code></dt>
|
|
<dd>AP Card identifier.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>ap_queue</code></dt>
|
|
<dd>Describes the AP queue on a s390 host. An AP queue is
|
|
an AP domain on an AP adapter which is specified by an
|
|
adapter identifier and a domain identifier.
|
|
Sub-elements include:
|
|
<dl>
|
|
<dt><code>ap-adapter</code></dt>
|
|
<dd>The ap-adapter of an AP queue identifies the AP
|
|
card to which this AP queue belongs.</dd>
|
|
<dt><code>ap-domain</code></dt>
|
|
<dd>The ap-domain of an AP queue identifies the AP
|
|
domain to which this AP queue belongs.</dd>
|
|
<dd>AP Queue identifier.</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>ap_matrix</code></dt>
|
|
<dd>Describes an AP Matrix device on a S390 architecture providing
|
|
cryptographic host resources usable for virtualization.
|
|
Sub-elements include:
|
|
<dl>
|
|
<dt><code>capability</code></dt>
|
|
<dd>
|
|
This optional element can occur multiple times. If it
|
|
exists, it has a mandatory <code>type</code> attribute
|
|
which will be set to:
|
|
<dl>
|
|
<dt><code><a id="MDEVTypesCapAP">mdev_types</a></code></dt>
|
|
<dd>
|
|
<span class="since">Since 6.10.0</span>
|
|
This device is capable of creating mediated devices.
|
|
The sub-elements are summarized in
|
|
<a href="#MDEVTypesCap">mdev_types capability</a>.
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a id="MDEVTypesCap">mdev_types capability</a></h3>
|
|
|
|
<p>
|
|
<a href="#MDEVTypesCapPCI">PCI</a>, <a href="#MDEVTypesCapCSS">CSS</a>
|
|
and <a href="#MDEVTypesCapAP">AP Matrix</a>
|
|
devices can be capable of creating mediated devices.
|
|
If they indeed are capable, then the parent <code>capability</code>
|
|
element for <code>mdev_types</code> type will contain a list of
|
|
<code>type</code> elements, which list all mdev types supported
|
|
on the physical device. <span class="since">Since 3.4.0</span>
|
|
Each <code>type</code> element has a single <code>id</code>
|
|
attribute that holds an official vendor-supplied identifier
|
|
for the type. It supports the following sub-elements:
|
|
<dl>
|
|
<dt><code>name</code></dt>
|
|
<dd>
|
|
The <code>name</code> element holds a vendor-supplied
|
|
code name for the given mediated device type. This is
|
|
an optional element.
|
|
</dd>
|
|
<dt><code>deviceAPI</code></dt>
|
|
<dd>
|
|
The value of this element describes how an instance of
|
|
the given type will be presented to the guest by the
|
|
VFIO framework.
|
|
</dd>
|
|
<dt><code>availableInstances</code></dt>
|
|
<dd>
|
|
This element reports the current state of resource
|
|
allocation. In other words, how many instances of the
|
|
given type can still be successfully created on the
|
|
physical device.
|
|
</dd>
|
|
</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>
|
|
|
|
<p>The following are some example node device XML outputs:</p>
|
|
<pre>
|
|
<device>
|
|
<name>computer</name>
|
|
<capability type='system'>
|
|
<product>2241B36</product>
|
|
<hardware>
|
|
<vendor>LENOVO</vendor>
|
|
<version>ThinkPad T500</version>
|
|
<serial>R89055N</serial>
|
|
<uuid>c9488981-5049-11cb-9c1c-993d0230b4cd</uuid>
|
|
</hardware>
|
|
<firmware>
|
|
<vendor>LENOVO</vendor>
|
|
<version>6FET82WW (3.12 )</version>
|
|
<release_date>11/26/2009</release_date>
|
|
</firmware>
|
|
</capability>
|
|
</device>
|
|
|
|
<device>
|
|
<name>net_eth1_00_27_13_6a_fe_00</name>
|
|
<parent>pci_0000_00_19_0</parent>
|
|
<capability type='net'>
|
|
<interface>eth1</interface>
|
|
<address>00:27:13:6a:fe:00</address>
|
|
<capability type='80203'/>
|
|
</capability>
|
|
</device>
|
|
|
|
<device>
|
|
<name>pci_0000_02_00_0</name>
|
|
<path>/sys/devices/pci0000:00/0000:00:04.0/0000:02:00.0</path>
|
|
<parent>pci_0000_00_04_0</parent>
|
|
<driver>
|
|
<name>igb</name>
|
|
</driver>
|
|
<capability type='pci'>
|
|
<class>0x020000</class>
|
|
<domain>0</domain>
|
|
<bus>2</bus>
|
|
<slot>0</slot>
|
|
<function>0</function>
|
|
<product id='0x10c9'>82576 Gigabit Network Connection</product>
|
|
<vendor id='0x8086'>Intel Corporation</vendor>
|
|
<capability type='virt_functions'>
|
|
<address domain='0x0000' bus='0x02' slot='0x10' function='0x0'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x10' function='0x2'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x10' function='0x4'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x10' function='0x6'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x11' function='0x0'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x11' function='0x2'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x11' function='0x4'/>
|
|
</capability>
|
|
<iommuGroup number='12'>
|
|
<address domain='0x0000' bus='0x02' slot='0x00' function='0x0'/>
|
|
<address domain='0x0000' bus='0x02' slot='0x00' function='0x1'/>
|
|
</iommuGroup>
|
|
<pci-express>
|
|
<link validity='cap' port='1' speed='2.5' width='1'/>
|
|
<link validity='sta' speed='2.5' width='1'/>
|
|
</pci-express>
|
|
</capability>
|
|
</device>
|
|
</pre>
|
|
|
|
</body>
|
|
</html>
|