<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <h1>Node devices XML format</h1>

    <ul id="toc"></ul>

    <h2><a id="NodedevAttributes">Node Device XML</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
      &lt;hostdev&gt; 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>class</code></dt>
              <dd>Optional element for combined class, subclass and
                programming interface codes as 6-digit hexadecimal number.
                <span class="since">Since 5.2.0</span></dd>
              <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></h2>

    <p>The following are some example node device XML outputs:</p>
    <pre>
&lt;device&gt;
  &lt;name&gt;computer&lt;/name&gt;
  &lt;capability type='system'&gt;
    &lt;product&gt;2241B36&lt;/product&gt;
    &lt;hardware&gt;
      &lt;vendor&gt;LENOVO&lt;/vendor&gt;
      &lt;version&gt;ThinkPad T500&lt;/version&gt;
      &lt;serial&gt;R89055N&lt;/serial&gt;
      &lt;uuid&gt;c9488981-5049-11cb-9c1c-993d0230b4cd&lt;/uuid&gt;
    &lt;/hardware&gt;
    &lt;firmware&gt;
      &lt;vendor&gt;LENOVO&lt;/vendor&gt;
      &lt;version&gt;6FET82WW (3.12 )&lt;/version&gt;
      &lt;release_date&gt;11/26/2009&lt;/release_date&gt;
    &lt;/firmware&gt;
  &lt;/capability&gt;
&lt;/device&gt;

&lt;device&gt;
  &lt;name&gt;net_eth1_00_27_13_6a_fe_00&lt;/name&gt;
  &lt;parent&gt;pci_0000_00_19_0&lt;/parent&gt;
  &lt;capability type='net'&gt;
    &lt;interface&gt;eth1&lt;/interface&gt;
    &lt;address&gt;00:27:13:6a:fe:00&lt;/address&gt;
    &lt;capability type='80203'/&gt;
  &lt;/capability&gt;
&lt;/device&gt;

&lt;device&gt;
  &lt;name&gt;pci_0000_02_00_0&lt;/name&gt;
  &lt;path&gt;/sys/devices/pci0000:00/0000:00:04.0/0000:02:00.0&lt;/path&gt;
  &lt;parent&gt;pci_0000_00_04_0&lt;/parent&gt;
  &lt;driver&gt;
    &lt;name&gt;igb&lt;/name&gt;
  &lt;/driver&gt;
  &lt;capability type='pci'&gt;
    &lt;class&gt;0x020000&lt;/class&gt;
    &lt;domain&gt;0&lt;/domain&gt;
    &lt;bus&gt;2&lt;/bus&gt;
    &lt;slot&gt;0&lt;/slot&gt;
    &lt;function&gt;0&lt;/function&gt;
    &lt;product id='0x10c9'&gt;82576 Gigabit Network Connection&lt;/product&gt;
    &lt;vendor id='0x8086'&gt;Intel Corporation&lt;/vendor&gt;
    &lt;capability type='virt_functions'&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x10' function='0x0'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x10' function='0x2'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x10' function='0x4'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x10' function='0x6'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x11' function='0x0'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x11' function='0x2'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x11' function='0x4'/&gt;
    &lt;/capability&gt;
    &lt;iommuGroup number='12'&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x00' function='0x0'/&gt;
      &lt;address domain='0x0000' bus='0x02' slot='0x00' function='0x1'/&gt;
    &lt;/iommuGroup&gt;
    &lt;pci-express&gt;
      &lt;link validity='cap' port='1' speed='2.5' width='1'/&gt;
      &lt;link validity='sta' speed='2.5' width='1'/&gt;
    &lt;/pci-express&gt;
  &lt;/capability&gt;
&lt;/device&gt;
    </pre>

  </body>
</html>
