libvirt: Node devices XML format
Description: libvirt, virtualization, virtualization API

# Node devices XML format

- Node Device XML
- Examples

## 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).
`devnode`
  This node appears for each associated `/dev` special file. A mandatory attribute `type` specify the kind of file path, which may be either `dev` for the main name, or `link` for additional symlinks.
`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.
    `iommuGroup`
      This optional element describes the "IOMMU group" this device belongs to. If the element exists, it has a mandatory `number` 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 `address` subelements, each containing the PCI address of a device in the same group. The toplevel device will itself be included in this list.
    `capability`
      This optional element can occur multiple times. If it exists, it has a mandatory `type` attribute which will be set to:
      `physical_function`
        That means there will be a single `address` 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)).
      `virtual_function`
        In this case this device is an SRIOV PF, and the capability element will have a list of `address` 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 `maxCount` 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 since 1.3.0; in this case, even if there are currently no active VFs the virtual_functions capabililty will still be shown.
      `pci-bridge` or `cardbus-bridge`
        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. Since 1.3.3
    `numa`
      This optional element contains information on the PCI device with respect to NUMA. For example, the optional `node` attribute tells which NUMA node is the PCI device associated with.
    `pci-express`
      This optional element contains information on PCI Express part of the device. For example, it can contain a child element `link` which addresses the PCI Express device's link. While a device has its own capabilities (`validity='cap'`), the actual run time capabilities are negotiated on the device initialization (`validity='sta'`). The `link` element then contains three attributes: `port` which says in which port is the device plugged in, `speed` (in GigaTransfers per second) and `width` for the number of lanes used. Since the port can't be negotiated, it's not exposed in `./pci-express/link/[@validity='sta']`.
  `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.
    `class`
      The device class.
    `subclass`
      The device subclass.
    `protocol`
      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.
    `link`
      Optional to reflect the status of the link. It has two optional attributes: `speed` in Mbits per second and `state` to tell the state of the link. So far, the whole element is just for output, not setting.
    `feature`
      If present, the hw offloads supported by this network interface. Possible features are:
      `rx`
        rx-checksumming
      `tx`
        tx-checksumming
      `sg`
        scatter-gather
      `tso`
        tcp-segmentation-offload
      `ufo`
        udp-fragmentation-offload
      `gso`
        generic-segmentation-offload
      `gro`
        generic-receive-offload
      `lro`
        large-receive-offload
      `rxvlan`
        rx-vlan-offload
      `txvlan`
        tx-vlan-offload
      `ntuple`
        ntuple-filters
      `rxhash`
        receive-hashing
      `rdma`
        remote-direct-memory-access
      `txudptnl`
        tx-udp-tunnel-segmentation
      `switchdev`
        kernel-forward-plane-offload
    `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.
    `unique_id`
      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 `find -H /sys/class/scsi_host/host{0..9}/unique_id | xargs grep '[0-9]'`. 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 Storage Pool. Since 1.2.7
    `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 optionally `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`.
  `drm`
    Describes a Direct Rendering Manager (DRM) device. Sub-elements include:
    `type`
      The type of DRM device. Could be `primary`, `control` or `render`.
  `ccw`
    Describes a Command Channel Word (CCW) device commonly found on the S390 architecture. Sub-elements include:
    `cssid`
      The channel subsystem identifier.
    `ssid`
      The subchannel-set identifier.
    `devno`
      The device number.

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

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