<?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". </dd> <dt><code>parent</code></dt> <dd>If this element is present, it names the parent device (that is, a controller to which this node belongs). </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>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>physical_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>virtual_function</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_maxvfs" 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 curently 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> </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><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> </dl> </dd> </dl> <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'> <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>