2013-05-03 18:25:37 +04:00
<?xml version="1.0" encoding="UTF-8"?>
2017-07-26 20:01:25 +03:00
<!DOCTYPE html>
2013-05-03 18:25:37 +04:00
< html xmlns = "http://www.w3.org/1999/xhtml" >
2008-04-23 21:08:31 +04:00
< body >
< h1 > Node devices XML format< / h1 >
2011-09-27 21:04:52 +04:00
< ul id = "toc" > < / ul >
2017-07-26 17:52:42 +03:00
< h2 > < a id = "NodedevAttributes" > Node Device XML< / a > < / h2 >
2011-09-27 21:04:52 +04:00
< 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
2013-06-28 21:06:30 +04:00
in < a href = "formatdomain.html#elementsHostDev" > the domain XML< / a > .
2011-09-27 21:04:52 +04:00
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 >
2017-02-15 00:04:10 +03:00
< 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 >
2011-09-27 21:04:52 +04:00
< 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 >
2019-02-19 15:41:37 +03:00
< dt > < code > class< / code > < / dt >
2019-03-21 10:12:40 +03:00
< dd > Optional element for combined class, subclass and
2019-02-19 15:41:37 +03:00
programming interface codes as 6-digit hexadecimal number.
< span class = "since" > Since 5.2.0< / span > < / dd >
2011-09-27 21:04:52 +04:00
< 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 >
2013-06-23 22:01:00 +04:00
< 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
2016-03-15 14:22:03 +03:00
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 >
2013-06-23 22:01:00 +04:00
< / dd >
2014-05-07 20:07:12 +04:00
< 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 >
2014-05-15 12:13:45 +04:00
< 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.
2015-06-03 13:10:36 +03:00
While a device has its own capabilities
2014-05-15 12:13:45 +04:00
(< 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 >
2011-09-27 21:04:52 +04:00
< / 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 >
2013-08-15 13:36:11 +04:00
< dt > < code > class< / code > < / dt >
2011-09-27 21:04:52 +04:00
< dd > The device class.< / dd >
2013-08-15 13:36:11 +04:00
< dt > < code > subclass< / code > < / dt >
2011-09-27 21:04:52 +04:00
< dd > The device subclass.< / dd >
2013-08-15 13:36:11 +04:00
< dt > < code > protocol< / code > < / dt >
2011-09-27 21:04:52 +04:00
< 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 >
2014-06-05 19:36:31 +04:00
< 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 >
2015-02-23 18:38:29 +03:00
< 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 >
2015-07-19 13:11:07 +03:00
< dt > < code > rdma< / code > < / dt > < dd > remote-direct-memory-access< / dd >
< dt > < code > txudptnl< / code > < / dt > < dd > tx-udp-tunnel-segmentation< / dd >
2017-08-21 12:19:53 +03:00
< dt > < code > switchdev< / code > < / dt > < dd > kernel-forward-plane-offload< / dd >
2015-02-23 18:38:29 +03:00
< / dl >
< / dd >
2011-09-27 21:04:52 +04:00
< 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.
2011-12-06 16:09:03 +04:00
< / dd >
2011-09-27 21:04:52 +04:00
< / 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 >
2014-06-05 21:17:05 +04:00
< 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 >
2011-12-06 16:09:03 +04:00
< dt > < code > capability< / code > < / dt >
< dd > Current capabilities include "vports_ops" (indicates
2013-01-07 21:05:32 +04:00
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
2017-01-16 16:27:34 +03:00
optionally < code > fabric_wwn< / code > .
2011-12-06 16:09:03 +04:00
< / dd >
2011-09-27 21:04:52 +04:00
< / dl >
< / dd >
< dt > < code > scsi< / code > < / dt >
2012-08-22 22:29:18 +04:00
< dd > Describes a SCSI device. Sub-elements include:
2011-09-27 21:04:52 +04:00
< 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
2012-08-22 22:29:18 +04:00
the attribute < code > type< / code > . Current capabilities
2011-09-27 21:04:52 +04:00
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 >
2017-02-15 00:04:12 +03:00
< 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 >
2017-05-22 09:38:23 +03:00
< 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 >
2011-09-27 21:04:52 +04:00
< / dl >
< / dd >
< / dl >
2017-07-26 17:52:42 +03:00
< h2 > < a id = "nodeExample" > Examples< / a > < / h2 >
2011-09-27 21:04:52 +04:00
< 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>
2013-06-23 22:01:00 +04:00
< /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'>
2019-02-19 15:41:37 +03:00
< class> 0x020000< /class>
2013-06-23 22:01:00 +04:00
< 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>
2014-05-15 12:13:45 +04:00
< pci-express>
< link validity='cap' port='1' speed='2.5' width='1'/>
< link validity='sta' speed='2.5' width='1'/>
< /pci-express>
2013-06-23 22:01:00 +04:00
< /capability>
< /device>
< / pre >
2011-09-27 21:04:52 +04:00
2008-04-23 21:08:31 +04:00
< / body >
< / html >
