<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <!-- This file is autogenerated from formatnode.html.in Do not edit this file. Changes will be lost. --> <!-- This page was generated at Mon Nov 13 21:46:26 UTC 2017. --> <head> <meta charset="UTF-8"/> <meta name="viewport" content="width=device-width, initial-scale=1"/> <link rel="stylesheet" type="text/css" href="main.css"/> <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/> <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/> <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/> <link rel="manifest" href="/manifest.json"/> <meta name="theme-color" content="#ffffff"/> <title>libvirt: Node devices XML format</title> <meta name="description" content="libvirt, virtualization, virtualization API"/> <script type="text/javascript"> <!-- function init() { window.addEventListener('scroll', function(e){ var distanceY = window.pageYOffset || document.documentElement.scrollTop, shrinkOn = 94 home = document.getElementById("home"); links = document.getElementById("jumplinks"); search = document.getElementById("search"); body = document.getElementById("body"); if (distanceY > shrinkOn) { if (home.className != "navhide") { body.className = "navhide" home.className = "navhide" links.className = "navhide" search.className = "navhide" } } else { if (home.className == "navhide") { body.className = "" home.className = "" links.className = "" search.className = "" } } }); } window.onload = init(); --> </script> </head> <body> <div id="body"> <div id="content"> <h1>Node devices XML format</h1> <ul> <li> <a href="#NodedevAttributes">Node Device XML</a> </li> <li> <a href="#nodeExample">Examples</a> </li> </ul> <h2> <a id="NodedevAttributes">Node Device XML</a> <a class="headerlink" href="#NodedevAttributes" title="Permalink to this headline">¶</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> <a class="headerlink" href="#nodeExample" title="Permalink to this headline">¶</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> </div> </div> <div id="nav"> <div id="home"> <a href="index.html">Home</a> </div> <div id="jumplinks"> <ul> <li> <a href="downloads.html">Download</a> </li> <li> <a href="contribute.html">Contribute</a> </li> <li> <a href="docs.html">Docs</a> </li> </ul> </div> <div id="search"> <form action="search.php" enctype="application/x-www-form-urlencoded" method="get"> <div> <input name="query" type="text" size="12" value=""/> <input name="submit" type="submit" value="Go"/> </div> </form> </div> </div> <div id="footer"> <div id="contact"> <h3>Contact</h3> <ul> <li> <a href="contact.html#email">email</a> </li> <li> <a href="contact.html#irc">irc</a> </li> </ul> </div> <div id="community"> <h3>Community</h3> <ul> <li> <a href="https://twitter.com/hashtag/libvirt">twitter</a> </li> <li> <a href="https://plus.google.com/communities/109522598353007505282">google+</a> </li> <li> <a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a> </li> <li> <a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a> </li> </ul> </div> <div id="conduct"> Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div> <br class="clear"/> </div> </body> </html>