<?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>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
13f578376e4e807e78e7ef322e364e58
>
files
>
105
