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:
namepathparentname element or computer if the device does
not have any parent.
driverdevnode/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.
capabilitytype lists which category the device
belongs to, and controls which further subelements will be
present to describe the node:
systemproducthardwarevendor, version,
serial, and uuid.firmwarevendor, version,
and release_date.pciclassdomainbusslotfunctionproductid with the hexadecimal product
id, and an optional text description of that id.vendorid with the hexadecimal vendor
id, and an optional text name of that vendor.iommuGroupnumber 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.
capabilitytype attribute
which will be set to:
phys_functionaddress
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)).
virt_functionsaddress
subelements, one for each VF on this PF. If the host system
supports reporting it (via the "sriov_totalvfs" 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 currently
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-bridgemdev_typesvpdnumanode attribute tells which NUMA node is the PCI
device associated with.
pci-expresslink 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_devicebusdeviceproductid with the hexadecimal product
id, and an optional text description of that id.vendorid with the hexadecimal vendor
id, and an optional text name of that vendor.usbnumberclasssubclassprotocoldescriptionnetinterfaceaddresslinkspeed in Mbits per
second and state to tell the state of the
link. So far, the whole element is just for output,
not setting.
featurerxtxsgtsoufogsogrolrorxvlantxvlanntuplerxhashrdmatxudptnlswitchdevcapabilitytype can be "80203" for IEEE
802.3, or "80211" for various flavors of IEEE 802.11.
scsi_hosthostunique_idfind -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
capabilityvports,
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.
scsihostbustargetluntypestorageblockbusdrive_typemodelvendorserialsizecapabilitytype. Current capabilities
include "hotpluggable" and "removable", with the
latter implying the following
sub-elements: media_available (0 or
1), media_size,
and media_label.drmtypeprimary, control or
render.mdevtypeid which holds an official vendor-supplied
identifier for the type.
iommuGroupnumber
which holds the IOMMU group number to which the mediated device
belongs. This is a read-only field that is reported by the
device driver.
attrname and value. Note that the order
in which attributes are set may be important for some devices.
The order that they appear in the xml definition determines the
order that they will be written to the device.
uuidccwcssidssiddevnocsscssidssiddevnocapabilitytype attribute
which will be set to:
mdev_typesvdpachardevap_cardap-adapterap_queueap-adapterap-domainap_matrixcapabilitytype attribute
which will be set to:
mdev_types
PCI, CSS
and AP Matrix
devices can be capable of creating mediated devices.
If they indeed are capable, then the parent capability
element for mdev_types type will contain a list of
type elements, which list all mdev types supported
on the physical device. Since 3.4.0
Each type element has a single id
attribute that holds an official vendor-supplied identifier
for the type. It supports the following sub-elements:
namename element holds a vendor-supplied
code name for the given mediated device type. This is
an optional element.
deviceAPIavailableInstances
PCI devices can expose a VPD capability which
is optional per PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If
the VPD capability is present, then the parent capability
element with the vpd type will contain a name
element (containing a manufacturer-provided device name) and optionally
one or two fields elements with an access
attribute set to readonly or readwrite.
The read-only fields element may contain the following elements:
change_levelmanufacture_idpart_numberserial_numbervendor_fieldindex attribute
(since-character upper-case ASCII alphanumeric indexes). Contents will vary
depending on a vendor.
The read-write fields element may contain the following elements:
asset_tagvendor_fieldindex attribute
(since-character upper-case ASCII alphanumeric indexes). Contents will vary depending
on a vendor.system_fieldindex attribute (since-character
upper-case ASCII alphanumeric indexes, except for letter 'A'). May store system-specific
data related to a PCI device.
The device name and all fields may contain only the following characters:
[0-9a-zA-F -_,.:;=].
The device name may be as large as 65535 bytes while fields are limited with 255 bytes.
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'>
<class>0x020000</class>
<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>