docs/formatnode.rst

   1 .. role:: since
   2
   3 =======================
   4 Node devices XML format
   5 =======================
   6
   7 .. contents::
   8
   9 Node Device XML
  10 ---------------
  11
  12 There are several libvirt functions, all with the prefix ``virNodeDevice``,
  13 which deal with management of host devices that can be handed to guests via
  14 passthrough as <hostdev> elements in `the domain
  15 XML <formatdomain.html#host-device-assignment>`__. These devices are represented as a
  16 hierarchy, where a device on a bus has a parent of the bus controller device;
  17 the root of the hierarchy is the node named "computer".
  18
  19 When represented in XML, a node device uses the top-level ``device`` element,
  20 with the following elements present according to the type of device:
  21
  22 ``name``
  23    The name for this device. The name will be alphanumeric, with words separated
  24    by underscore. For many devices, the name is just the bus type and address,
  25    as in "pci_0000_00_02_1" or "usb_1_5_3", but some devices are able to provide
  26    more specific names, such as "net_eth1_00_27_13_6a_fe_00". This is a
  27    read-only field that is reported by the device driver. If this element is set
  28    when defining a new device, it will be ignored.
  29 ``path``
  30    Fully qualified sysfs path to the device. This is a read-only field that is
  31    reported by the device driver. If this element is set when defining a new
  32    device, it will be ignored.
  33 ``parent``
  34    This element identifies the parent node in the device hierarchy. The value of
  35    the element will correspond with the device parent's ``name`` element or
  36    ``computer`` if the device does not have any parent.
  37 ``driver``
  38    This elements reports the driver in use for this device. The presence of this
  39    element in the output XML depends on whether the underlying device manager
  40    (most likely udev) exposes information about the driver.
  41 ``devnode``
  42    This node appears for each associated ``/dev`` special file. A mandatory
  43    attribute ``type`` specify the kind of file path, which may be either ``dev``
  44    for the main name, or ``link`` for additional symlinks.
  45 ``capability``
  46    This node appears for each capability that libvirt associates with a node. A
  47    mandatory attribute ``type`` lists which category the device belongs to.
  48    The `capability types`_ section below describes them further.
  49
  50 ``capability`` types
  51 ~~~~~~~~~~~~~~~~~~~~
  52
  53 Based on the capbility type there are further more specific attributes to a
  54 device described below.
  55
  56 ``system``
  57 ^^^^^^^^^^
  58
  59 Describes the overall host. Sub-elements include:
  60
  61 ``product``
  62     If present, a simple text string giving the product name of the system.
  63 ``hardware``
  64     Describes the hardware of the system, including sub-elements for
  65     ``vendor``, ``version``, ``serial``, and ``uuid``.
  66 ``firmware``
  67     Describes the firmware of the system, including sub-elements for
  68     ``vendor``, ``version``, and ``release_date``.
  69
  70 ``pci``
  71 ^^^^^^^
  72
  73 Describes a device on the host's PCI bus. Sub-elements include:
  74
  75 ``class``
  76    Optional element for combined class, subclass and programming interface
  77    codes as 6-digit hexadecimal number. :since:`Since 5.2.0`
  78 ``domain``
  79    Which domain the device belongs to.
  80 ``bus``
  81    Which bus within the domain.
  82 ``slot``
  83    Which slot within the bus.
  84 ``function``
  85    Which function within the slot.
  86 ``product``
  87    Product details from the device ROM, including an attribute ``id`` with
  88    the hexadecimal product id, and an optional text description of that
  89    id.
  90 ``vendor``
  91    Vendor details from the device ROM, including an attribute ``id`` with
  92    the hexadecimal vendor id, and an optional text name of that vendor.
  93 ``iommuGroup``
  94    This optional element describes the "IOMMU group" this device belongs
  95    to. If the element exists, it has a mandatory ``number`` attribute
  96    which tells the group number used for management of the group (all
  97    devices in group "n" will be found in "/sys/kernel/iommu_groups/n"). It
  98    will also have a list of ``address`` subelements, each containing the
  99    PCI address of a device in the same group. The toplevel device will
 100    itself be included in this list.
 101 ``capability``
 102    This optional element can occur multiple times. If it exists, it has a
 103    mandatory ``type`` attribute which will be set to:
 104
 105    ``phys_function``
 106       That means there will be a single ``address`` subelement which
 107       contains the PCI address of the SRIOV Physical Function (PF) that is
 108       the parent of this device (and this device is, by implication, an
 109       SRIOV Virtual Function (VF)).
 110    ``virt_functions``
 111       In this case this device is an SRIOV PF, and the capability element
 112       will have a list of ``address`` subelements, one for each VF on this
 113       PF. If the host system supports reporting it (via the
 114       "sriov_totalvfs" file in the device's sysfs directory) the
 115       capability element will also have an attribute named ``maxCount``
 116       which is the maximum number of SRIOV VFs supported by this device,
 117       which could be higher than the number of VFs that are currently
 118       active :since:`since 1.3.0`; in this case, even if there are
 119       currently no active VFs the virtual_functions capabililty will still
 120       be shown.
 121    ``pci-bridge`` or ``cardbus-bridge``
 122       This shows merely that the lower 7 bits of PCI header type have
 123       either value of 1 or 2 respectively. Usually this means such device
 124       cannot be used for PCI passthrough. :since:`Since 1.3.3`
 125    ``mdev_types``
 126       This device is capable of creating mediated devices. The
 127       sub-elements are summarized in `mdev_types capability`_.
 128    ``vpd``
 129       This device exposes a VPD PCI/PCIe capability. The sub-elements are
 130       summarized in `vpd capability`_.
 131 ``numa``
 132    This optional element contains information on the PCI device with
 133    respect to NUMA. For example, the optional ``node`` attribute tells
 134    which NUMA node is the PCI device associated with.
 135 ``pci-express``
 136    This optional element contains information on PCI Express part of the
 137    device. For example, it can contain a child element ``link`` which
 138    addresses the PCI Express device's link. While a device has its own
 139    capabilities (``validity='cap'``), the actual run time capabilities are
 140    negotiated on the device initialization (``validity='sta'``). The
 141    ``link`` element then contains three attributes: ``port`` which says in
 142    which port is the device plugged in, ``speed`` (in GigaTransfers per
 143    second) and ``width`` for the number of lanes used. Since the port
 144    can't be negotiated, it's not exposed in
 145    ``./pci-express/link/[`validity='sta']``.
 146
 147 ``usb_device``
 148 ^^^^^^^^^^^^^^
 149
 150 Describes a device on the host's USB bus, based on its location within the bus.
 151 Sub-elements include:
 152
 153 ``bus``
 154    Which bus the device belongs to.
 155 ``device``
 156    Which device within the bus.
 157 ``product``
 158    Product details from the device ROM, including an attribute ``id`` with
 159    the hexadecimal product id, and an optional text description of that
 160    id.
 161 ``vendor``
 162    Vendor details from the device ROM, including an attribute ``id`` with
 163    the hexadecimal vendor id, and an optional text name of that vendor.
 164
 165 ``usb``
 166 ^^^^^^^
 167
 168 Describes a USB device, based on its advertised driver interface.  Sub-elements
 169 include:
 170
 171 ``number``
 172    The device number.
 173 ``class``
 174    The device class.
 175 ``subclass``
 176    The device subclass.
 177 ``protocol``
 178    The device protocol.
 179 ``description``
 180    If present, a description of the device.
 181
 182 ``net``
 183 ^^^^^^^
 184
 185 Describes a device capable for use as a network interface. Sub-elements
 186 include:
 187
 188 ``interface``
 189    The interface name tied to this device.
 190 ``address``
 191    If present, the MAC address of the device.
 192 ``link``
 193    Optional to reflect the status of the link. It has two optional
 194    attributes: ``speed`` in Mbits per second and ``state`` to tell the
 195    state of the link. So far, the whole element is just for output, not
 196    setting.
 197 ``feature``
 198    If present, the hw offloads supported by this network interface.
 199    Possible features are:
 200
 201    ``rx``
 202       rx-checksumming
 203    ``tx``
 204       tx-checksumming
 205    ``sg``
 206       scatter-gather
 207    ``tso``
 208       tcp-segmentation-offload
 209    ``ufo``
 210       udp-fragmentation-offload
 211    ``gso``
 212       generic-segmentation-offload
 213    ``gro``
 214       generic-receive-offload
 215    ``lro``
 216       large-receive-offload
 217    ``rxvlan``
 218       rx-vlan-offload
 219    ``txvlan``
 220       tx-vlan-offload
 221    ``ntuple``
 222       ntuple-filters
 223    ``rxhash``
 224       receive-hashing
 225    ``rdma``
 226       remote-direct-memory-access
 227    ``txudptnl``
 228       tx-udp-tunnel-segmentation
 229    ``switchdev``
 230       kernel-forward-plane-offload
 231 ``capability``
 232    A network protocol exposed by the device, where the attribute ``type``
 233    can be "80203" for IEEE 802.3, or "80211" for various flavors of IEEE
 234    802.11.
 235
 236 ``scsi_host``
 237 ^^^^^^^^^^^^^
 238
 239 Describes a SCSI host device. Sub-elements include:
 240
 241 ``host``
 242    The SCSI host number.
 243 ``unique_id``
 244    On input, this optionally provides the value from the 'unique_id' file
 245    found in the scsi_host's directory. To view the values of all
 246    'unique_id' files, use
 247    ``find -H /sys/class/scsi_host/host{0..9}/unique_id | xargs grep '[0-9]'``.
 248    On output, if the unique_id file exists, the value from the file will
 249    be displayed. This can be used in order to help uniquely identify the
 250    scsi_host adapter in a `Storage Pool <formatstorage.html>`__.
 251    :since:`Since 1.2.7`
 252 ``capability``
 253    Current capabilities include "vport_ops" (indicates vport operations
 254    are supported) and "fc_host". "vport_ops" could contain two optional
 255    sub-elements: ``vports``, and ``max_vports``. ``vports`` shows the
 256    number of vport in use. ``max_vports`` shows the maximum vports the HBA
 257    supports. "fc_host" implies following sub-elements: ``wwnn``, ``wwpn``,
 258    and optionally ``fabric_wwn``.
 259
 260 ``scsi``
 261 ^^^^^^^^
 262
 263 Describes a SCSI device. Sub-elements include:
 264
 265 ``host``
 266    The SCSI host containing the device.
 267 ``bus``
 268    The bus within the host.
 269 ``target``
 270    The target within the bus.
 271 ``lun``
 272    The lun within the target.
 273 ``type``
 274    The type of SCSI device.
 275
 276 ``storage``
 277 ^^^^^^^^^^^
 278
 279 Describes a device usable for storage. Sub-elements include:
 280
 281 ``block``
 282    A block device file name that accesses the storage present on the
 283    device.
 284 ``bus``
 285    If present, the name of the bus the device is found on.
 286 ``drive_type``
 287    The type of the drive, such as "disk" or "cdrom".
 288 ``model``
 289    Any model information available from the device.
 290 ``vendor``
 291    Any vendor information available from the device.
 292 ``serial``
 293    Any serial number information available from the device.
 294 ``size``
 295    For fixed-size storage, the amount of storage available.
 296 ``capability``
 297    If present, an additional capability is listed via the attribute
 298    ``type``. Current capabilities include "hotpluggable" and "removable",
 299    with the latter implying the following sub-elements:
 300    ``media_available`` (0 or 1), ``media_size``, and ``media_label``.
 301
 302 ``drm``
 303 ^^^^^^^
 304
 305 Describes a Direct Rendering Manager (DRM) device. Sub-elements include:
 306
 307 ``type``
 308    The type of DRM device. Could be ``primary``, ``control`` or ``render``.
 309
 310 ``mdev``
 311 ^^^^^^^^
 312
 313 Describes a mediated device. :since:`Since 3.4.0` Sub-elements include:
 314
 315 ``type``
 316    Describes a mediated device type which acts as an abstract template
 317    defining a resource allocation for instances of this device type. The
 318    element has one attribute ``id`` which holds an official
 319    vendor-supplied identifier for the type.
 320 ``iommuGroup``
 321    This element supports a single attribute ``number`` which holds the
 322    IOMMU group number to which the mediated device belongs. This is a
 323    read-only field that is reported by the device driver.
 324 ``attr``
 325    This optional element can occur multiple times. It represents a
 326    vendor-specific attribute that is used to configure this mediated
 327    device. It has two required attributes: ``name`` and ``value``. Note
 328    that the order in which attributes are set may be important for some
 329    devices. The order that they appear in the xml definition determines
 330    the order that they will be written to the device.
 331 ``uuid``
 332    This element represents the UUID of the mediated device.
 333
 334 ``ccw``
 335 ^^^^^^^
 336
 337 Describes a Command Channel Word (CCW) device commonly found on the S390
 338 architecture. Sub-elements include:
 339
 340 ``cssid``
 341    The channel subsystem identifier.
 342 ``ssid``
 343    The subchannel-set identifier.
 344 ``devno``
 345    The device number.
 346
 347 ``css``
 348 ^^^^^^^
 349
 350 Describes a subchannel in the Channel SubSystem (CSS) commonly found on the
 351 S390 architecture. Sub-elements include:
 352
 353 ``cssid``
 354    The channel subsystem identifier.
 355 ``ssid``
 356    The subchannel-set identifier.
 357 ``devno``
 358    The subchannel number.
 359 ``capability``
 360    This optional element can occur multiple times. If it exists, it has a
 361    mandatory ``type`` attribute which will be set to:
 362
 363    ``mdev_types``
 364       :since:`Since 6.10.0` This device is capable of creating mediated
 365       devices. The sub-elements are summarized in `mdev_types capability`_.
 366
 367 ``vdpa``
 368 ^^^^^^^^
 369
 370 Describes a virtual datapath acceleration (vDPA) network device.
 371 :since:`Since 6.9.0`. Sub-elements include:
 372
 373 ``chardev``
 374    The path to the character device that is used to access the device.
 375
 376 ``ap_card``
 377 ^^^^^^^^^^^
 378
 379 Describes the Adjunct Processor (AP) Card device on a S390 host.  Sub-elements
 380 include:
 381
 382 ``ap-adapter``
 383    AP Card identifier.
 384
 385 ``ap_queue``
 386 ^^^^^^^^^^^^
 387
 388 Describes the AP queue on a s390 host. An AP queue is an AP domain on an AP
 389 adapter which is specified by an adapter identifier and a domain identifier.
 390 Sub-elements include:
 391
 392 ``ap-adapter``
 393    The ap-adapter of an AP queue identifies the AP card to which this AP
 394    queue belongs.
 395 ``ap-domain``
 396    The ap-domain of an AP queue identifies the AP domain to which this AP
 397    queue belongs.
 398    AP Queue identifier.
 399
 400 ``ap_matrix``
 401 ^^^^^^^^^^^^^
 402
 403 Describes an AP Matrix device on a S390 architecture providing cryptographic
 404 host resources usable for virtualization. Sub-elements include:
 405
 406 ``capability``
 407    This optional element can occur multiple times. If it exists, it has a
 408    mandatory ``type`` attribute which will be set to:
 409
 410    ``mdev_types``
 411       :since:`Since 6.10.0` This device is capable of creating mediated
 412       devices. The sub-elements are summarized in `mdev_types capability`_
 413
 414 ``mdev_types`` capability
 415 ~~~~~~~~~~~~~~~~~~~~~~~~~
 416
 417 `pci`_, `css`_ and `ap_matrix`_ devices can be capable of creating mediated
 418 devices. If they indeed are capable, then the parent ``capability`` element for
 419 ``mdev_types`` type will contain a list of ``type`` elements, which list all
 420 mdev types supported on the physical device. :since:`Since 3.4.0` Each ``type``
 421 element has a single ``id`` attribute that holds an official vendor-supplied
 422 identifier for the type. It supports the following sub-elements:
 423
 424 ``name``
 425    The ``name`` element holds a vendor-supplied code name for the given mediated
 426    device type. This is an optional element.
 427 ``deviceAPI``
 428    The value of this element describes how an instance of the given type will be
 429    presented to the guest by the VFIO framework.
 430 ``availableInstances``
 431    This element reports the current state of resource allocation. In other
 432    words, how many instances of the given type can still be successfully created
 433    on the physical device.
 434
 435 ``vpd`` capability
 436 ~~~~~~~~~~~~~~~~~~
 437
 438 `pci`_ devices can expose a VPD capability which is optional per
 439 PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If the VPD capability is
 440 present, then the parent ``capability`` element with the ``vpd`` type will
 441 contain a ``name`` element (containing a manufacturer-provided device name) and
 442 optionally one or two ``fields`` elements with an ``access`` attribute set to
 443 ``readonly`` or ``readwrite``.
 444
 445 The read-only ``fields`` element may contain the following elements:
 446
 447 ``change_level``
 448    An engineering change level for this add-in card.
 449 ``manufacture_id``
 450    An extension to the Vendor ID (or Subsystem Vendor ID) in the Configuration
 451    Space header which allows vendors the flexibility to identify an additional
 452    level of detail pertaining to the sourcing of a PCI device.
 453 ``part_number``
 454    An extension to the Device ID (or Subsystem ID) in the Configuration Space
 455    header specifying a part number of an add-in card.
 456 ``serial_number``
 457    A unique add-in card Serial Number.
 458 ``vendor_field``
 459    Zero or many of those elements with an ``index`` attribute (since-character
 460    upper-case ASCII alphanumeric indexes). Contents will vary depending on a
 461    vendor.
 462
 463 All fields are optional and are not guaranteed to be present for a generic PCI
 464 device.
 465
 466 The read-write ``fields`` element may contain the following elements:
 467
 468 ``asset_tag``
 469    A system asset identifier provided by the system owner.
 470 ``vendor_field``
 471    Zero or many of those elements with an ``index`` attribute (since-character
 472    upper-case ASCII alphanumeric indexes). Contents will vary depending on a
 473    vendor.
 474 ``system_field``
 475    Zero or many of those elements with an ``index`` attribute (since-character
 476    upper-case ASCII alphanumeric indexes, except for letter 'A'). May store
 477    system-specific data related to a PCI device.
 478
 479 All fields are optional and are not guaranteed to be present for a generic PCI
 480 device. Read-write fields are not possible to alter via Libvirt at the time of
 481 writing but their content is refreshed on each invocation in case this is done
 482 by means external to Libvirt.
 483
 484 The device name and all fields may contain only the following characters:
 485 ``[0-9a-zA-F -_,.:;=]``. The device name may be as large as 65535 bytes while
 486 fields are limited with 255 bytes.
 487
 488 Examples
 489 --------
 490
 491 The following are some example node device XML outputs:
 492
 493 ::
 494
 495    <device>
 496      <name>computer</name>
 497      <capability type='system'>
 498        <product>2241B36</product>
 499        <hardware>
 500          <vendor>LENOVO</vendor>
 501          <version>ThinkPad T500</version>
 502          <serial>R89055N</serial>
 503          <uuid>c9488981-5049-11cb-9c1c-993d0230b4cd</uuid>
 504        </hardware>
 505        <firmware>
 506          <vendor>LENOVO</vendor>
 507          <version>6FET82WW (3.12 )</version>
 508          <release_date>11/26/2009</release_date>
 509        </firmware>
 510      </capability>
 511    </device>
 512
 513    <device>
 514      <name>net_eth1_00_27_13_6a_fe_00</name>
 515      <parent>pci_0000_00_19_0</parent>
 516      <capability type='net'>
 517        <interface>eth1</interface>
 518        <address>00:27:13:6a:fe:00</address>
 519        <capability type='80203'/>
 520      </capability>
 521    </device>
 522
 523    <device>
 524      <name>pci_0000_02_00_0</name>
 525      <path>/sys/devices/pci0000:00/0000:00:04.0/0000:02:00.0</path>
 526      <parent>pci_0000_00_04_0</parent>
 527      <driver>
 528        <name>igb</name>
 529      </driver>
 530      <capability type='pci'>
 531        <class>0x020000</class>
 532        <domain>0</domain>
 533        <bus>2</bus>
 534        <slot>0</slot>
 535        <function>0</function>
 536        <product id='0x10c9'>82576 Gigabit Network Connection</product>
 537        <vendor id='0x8086'>Intel Corporation</vendor>
 538        <capability type='virt_functions'>
 539          <address domain='0x0000' bus='0x02' slot='0x10' function='0x0'/>
 540          <address domain='0x0000' bus='0x02' slot='0x10' function='0x2'/>
 541          <address domain='0x0000' bus='0x02' slot='0x10' function='0x4'/>
 542          <address domain='0x0000' bus='0x02' slot='0x10' function='0x6'/>
 543          <address domain='0x0000' bus='0x02' slot='0x11' function='0x0'/>
 544          <address domain='0x0000' bus='0x02' slot='0x11' function='0x2'/>
 545          <address domain='0x0000' bus='0x02' slot='0x11' function='0x4'/>
 546        </capability>
 547        <iommuGroup number='12'>
 548          <address domain='0x0000' bus='0x02' slot='0x00' function='0x0'/>
 549          <address domain='0x0000' bus='0x02' slot='0x00' function='0x1'/>
 550        </iommuGroup>
 551        <pci-express>
 552          <link validity='cap' port='1' speed='2.5' width='1'/>
 553          <link validity='sta' speed='2.5' width='1'/>
 554        </pci-express>
 555      </capability>
 556    </device>