# 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).
`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", the later implies following sub-elements: `wwnn`, `wwpn`, `fabric_wwn`.
  `scsi`
    Desribes 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 capabilites 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>