9.3. Configuring Device Controllers
Depending on the guest virtual machine architecture, some device buses can appear more than once, with a group of virtual devices tied to a virtual controller. Normally, libvirt can automatically infer such controllers without requiring explicit XML markup, but in some cases it is better to explicitly set a virtual controller element.
... <devices> <controller type='ide' index='0'/> <controller type='virtio-serial' index='0' ports='16' vectors='4'/> <controller type='virtio-serial' index='1'> <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/> </controller> ... </devices> ...
Figure 9.11. Domain XML example for virtual controllers
Each controller has a mandatory attribute
<controller type>, which must be one of:
<controller>element has a mandatory attribute
<controller index>which is the decimal integer describing in which order the bus controller is encountered (for use in controller attributes of
<controller type ='virtio-serial'>there are two additional optional attributes (named
vectors), which control how many devices can be connected through the controller. Note that Red Hat Enterprise Linux 6 does not support the use of more than 32 vectors per device. Using more vectors will cause failures in migrating the guest virtual machine.
<controller type ='scsi'>, there is an optional attribute
modelmodel, which can have the following values:
<controller type ='usb'>, there is an optional attribute
modelmodel, which can have the following values:
If the USB bus needs to be explicitly disabled for the guest virtual machine,
<model='none'>may be used. .
For controllers that are themselves devices on a PCI or USB bus, an optional sub-element
<address>can specify the exact relationship of the controller to its master bus, with semantics as shown in Section 9.4, “Setting Addresses for Devices”.
An optional sub-element
<driver>can specify the driver specific options. Currently it only supports attribute queues, which specifies the number of queues for the controller. For best performance, it is recommended to specify a value matching the number of vCPUs.
USB companion controllers have an optional sub-element
<master>to specify the exact relationship of the companion to its master controller. A companion controller is on the same bus as its master, so the companion
indexvalue should be equal.
An example XML which can be used is as follows:
... <devices> <controller type='usb' index='0' model='ich9-ehci1'> <address type='pci' domain='0' bus='0' slot='4' function='7'/> </controller> <controller type='usb' index='0' model='ich9-uhci1'> <master startport='0'/> <address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/> </controller> ... </devices> ...
Figure 9.12. Domain XML example for USB controllers
PCI controllers have an optional
modelattribute with the following possible values:
The root controllers (
pcie-root) have an optional
pcihole64element specifying how big (in kilobytes, or in the unit specified by
unitattribute) the 64-bit PCI hole should be. Some guest virtual machines (such as Windows Server 2003) may cause a crash, unless
unitis disabled (set to 0
For machine types which provide an implicit PCI bus, the pci-root controller with
index='0'is auto-added and required to use PCI devices. pci-root has no address. PCI bridges are auto-added if there are too many devices to fit on the one bus provided by
model='pci-root', or a PCI bus number greater than zero was specified. PCI bridges can also be specified manually, but their addresses should only refer to PCI buses provided by already specified PCI controllers. Leaving gaps in the PCI controller indexes might lead to an invalid configuration. The following XML example can be added to the
... <devices> <controller type='pci' index='0' model='pci-root'/> <controller type='pci' index='1' model='pci-bridge'> <address type='pci' domain='0' bus='0' slot='5' function='0' multifunction='off'/> </controller> </devices> ...
Figure 9.13. Domain XML example for PCI bridge
For machine types which provide an implicit PCI Express (PCIe) bus (for example, the machine types based on the Q35 chipset), the pcie-root controller with
index='0'is auto-added to the domain's configuration. pcie-root has also no address, but provides 31 slots (numbered 1-31) and can only be used to attach PCIe devices. In order to connect standard PCI devices on a system which has a pcie-root controller, a pci controller with
model='dmi-to-pci-bridge'is automatically added. A dmi-to-pci-bridge controller plugs into a PCIe slot (as provided by pcie-root), and itself provides 31 standard PCI slots (which are not hot-pluggable). In order to have hot-pluggable PCI slots in the guest system, a pci-bridge controller will also be automatically created and connected to one of the slots of the auto-created dmi-to-pci-bridge controller; all guest devices with PCI addresses that are auto-determined by libvirt will be placed on this pci-bridge device.
... <devices> <controller type='pci' index='0' model='pcie-root'/> <controller type='pci' index='1' model='dmi-to-pci-bridge'> <address type='pci' domain='0' bus='0' slot='0xe' function='0'/> </controller> <controller type='pci' index='2' model='pci-bridge'> <address type='pci' domain='0' bus='1' slot='1' function='0'/> </controller> </devices> ...
Figure 9.14. Domain XML example for PCIe (PCI express)