Node devices XML format

Node Device XML

There are several libvirt functions, all with the prefix virNodeDevice, which deal with management of host devices that can be handed to guests via passthrough as <hostdev> elements in the domain XML. 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".

When represented in XML, a node device uses the top-level device element, with the following elements present according to the type of device:

name
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".
parent
If this element is present, it names the parent device (that is, a controller to which this node belongs).
capability
This node appears for each capability that libvirt associates with a node. A mandatory attribute type lists which category the device belongs to, and controls which further subelements will be present to describe the node:
system
Describes the overall host. Sub-elements include:
product
If present, a simple text string giving the product name of the system.
hardware
Describes the hardware of the system, including sub-elements for vendor, version, serial, and uuid.
firmware
Describes the firmware of the system, including sub-elements for vendor, version, and release_date.
pci
Describes a device on the host's PCI bus. Sub-elements include:
domain
Which domain the device belongs to.
bus
Which bus within the domain.
slot
Which slot within the bus.
function
Which function within the slot.
product
Product details from the device ROM, including an attribute id with the hexadecimal product id, and an optional text description of that id.
vendor
Vendor details from the device ROM, including an attribute id with the hexadecimal vendor id, and an optional text name of that vendor.
usb_device
Describes a device on the host's USB bus, based on its location within the bus. Sub-elements include:
bus
Which bus the device belongs to.
device
Which device within the bus.
product
Product details from the device ROM, including an attribute id with the hexadecimal product id, and an optional text description of that id.
vendor
Vendor details from the device ROM, including an attribute id with the hexadecimal vendor id, and an optional text name of that vendor.
usb
Describes a USB device, based on its advertised driver interface. Sub-elements include:
number
The device number.
number
The device class.
number
The device subclass.
number
The device protocol.
description
If present, a description of the device.
net
Describes a device capable for use as a network interface. Sub-elements include:
interface
The interface name tied to this device.
address
If present, the MAC address of the device.
capability
A network protocol exposed by the device, where the attribute type can be "80203" for IEEE 802.3, or "80211" for various flavors of IEEE 802.11.
scsi_host
Describes a SCSI host device. Sub-elements include:
host
The SCSI host number.
capability
Current capabilities include "vports_ops" (indicates vport operations are supported) and "fc_host". "vport_ops" could contain two optional sub-elements: vports, and max_vports. vports shows the number of vport in use. max_vports shows the maximum vports the HBA supports. "fc_host" implies following sub-elements: wwnn, wwpn, and fabric_wwn.
scsi
Describes a SCSI device. Sub-elements include:
host
The SCSI host containing the device.
bus
The bus within the host.
target
The target within the bus.
lun
The lun within the target.
type
The type of SCSI device.
storage
Describes a device usable for storage. Sub-elements include:
block
A block device file name that accesses the storage present on the device.
bus
If present, the name of the bus the device is found on.
drive_type
The type of the drive, such as "disk" or "cdrom".
model
Any model information available from the device.
vendor
Any vendor information available from the device.
serial
Any serial number information available from the device.
size
For fixed-size storage, the amount of storage available.
capability
If present, an additional capability is listed via the attribute type. Current capabilities include "hotpluggable" and "removable", with the latter implying the following sub-elements: media_available (0 or 1), media_size, and media_label.

Examples

The following are some example node device XML outputs:

<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>