[PATCH 11/32] docs: formatdomain-devices: Split out <controller>

Start splitting out part of <devices> into smaller sections. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-controller.rst | 305 ++++++++++++++++++++++ docs/formatdomain-devices.rst | 307 +---------------------- docs/meson.build | 1 + 3 files changed, 307 insertions(+), 306 deletions(-) create mode 100644 docs/formatdomain-devices-controller.rst diff --git a/docs/formatdomain-devices-controller.rst b/docs/formatdomain-devices-controller.rst new file mode 100644 index 0000000000..23985271de --- /dev/null +++ b/docs/formatdomain-devices-controller.rst @@ -0,0 +1,305 @@ +:anchor:`<a id="elementsControllers"/>` + +Controllers +~~~~~~~~~~~ + +Depending on the guest 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 sometimes it is necessary to provide an explicit controller element, +notably when planning the `PCI topology <pci-hotplug.html>`__ for guests where +device hotplug is expected. + +:: + + ... + <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> + <controller type='scsi' index='0' model='virtio-scsi'> + <driver iothread='4'/> + <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/> + </controller> + <controller type='xenbus' maxGrantFrames='64' maxEventChannels='2047'/> + ... + </devices> + ... + +Each controller has a mandatory attribute ``type``, which must be one of 'ide', +'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mandatory +attribute ``index`` which is the decimal integer describing in which order the +bus controller is encountered (for use in ``controller`` attributes of +``<address>`` elements). :since:`Since 1.3.5` the index is optional; if not +specified, it will be auto-assigned to be the lowest unused index for the given +controller type. Some controller types have additional attributes that control +specific features, such as: + +``virtio-serial`` + The ``virtio-serial`` controller has two additional optional attributes + ``ports`` and ``vectors``, which control how many devices can be connected + through the controller. :since:`Since 5.2.0` , it supports an optional + attribute ``model`` which can be 'virtio', 'virtio-transitional', or + 'virtio-non-transitional'. See `Virtio transitional + devices <#elementsVirtioTransitional>`__ for more details. +``scsi`` + A ``scsi`` controller has an optional attribute ``model``, which is one of + 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', + 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. + See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more + details. +``usb`` + A ``usb`` controller has an optional attribute ``model``, which is one of + "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", + "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb + with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu backend, + version 2.0) or "qemu-xhci". Additionally, :since:`since 0.10.0` , if the USB + bus needs to be explicitly disabled for the guest, ``model='none'`` may be + used. :since:`Since 1.0.5` , no default USB controller will be built on s390. + :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to + configure how many devices can be connected to the controller. +``ide`` + :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an + optional attribute ``model``, which is one of "piix3", "piix4" or "ich6". +``xenbus`` + :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attribute + ``maxGrantFrames``, which specifies the maximum number of grant frames the + controller makes available for connected devices. :since:`Since 6.3.0` , the + xenbus controller supports the optional ``maxEventChannels`` attribute, which + specifies maximum number of event channels (PV interrupts) that can be used + by the guest. + +Note: The PowerPC64 "spapr-vio" addresses do not have an associated controller. + +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 `given above <#elementsAddress>`__. + +An optional sub-element ``driver`` can specify the driver specific options: + +``queues`` + The optional ``queues`` attribute specifies the number of queues for the + controller. For best performance, it's recommended to specify a value + matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` +``cmd_per_lun`` + The optional ``cmd_per_lun`` attribute specifies the maximum number of + commands that can be queued on devices controlled by the host. :since:`Since + 1.2.7 (QEMU and KVM only)` +``max_sectors`` + The optional ``max_sectors`` attribute specifies the maximum amount of data + in bytes that will be transferred to or from the device in a single command. + The transfer length is measured in sectors, where a sector is 512 bytes. + :since:`Since 1.2.7 (QEMU and KVM only)` +``ioeventfd`` + The optional ``ioeventfd`` attribute specifies whether the controller should + use `I/O asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__ + or not. Accepted values are "on" and "off". :since:`Since 1.2.18` +``iothread`` + Supported for controller type ``scsi`` using model ``virtio-scsi`` for + ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` . The + optional ``iothread`` attribute assigns the controller to an IOThread as + defined by the range for the domain + `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` + assigned to use the specified ``controller`` will utilize the same IOThread. + If a specific IOThread is desired for a specific SCSI ``disk``, then multiple + controllers must be defined each having a specific ``iothread`` value. The + ``iothread`` value must be within the range 1 to the domain iothreads value. +virtio options + For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ can + also be set. ( :since:`Since 3.5.0` ) + +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 ``index`` value +should be equal. Not all controller models can be used as companion controllers +and libvirt might provide some sensible defaults (settings of +``master startport`` and ``function`` of an address) for some particular models. +Preferred companion controllers are ``ich-uhci[123]``. + +:: + + ... + <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> + ... + +PCI controllers have an optional ``model`` attribute; possible values for this +attribute are + +- ``pci-root``, ``pci-bridge`` ( :since:`since 1.0.5` ) +- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` ) +- ``pcie-root-port``, ``pcie-switch-upstream-port``, + ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` ) +- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` ) +- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` ) + +The root controllers (``pci-root`` and ``pcie-root``) have an optional +``pcihole64`` element specifying how big (in kilobytes, or in the unit specified +by ``pcihole64``'s ``unit`` attribute) the 64-bit PCI hole should be. Some +guests (like Windows XP or Windows Server 2003) might crash when QEMU and +Seabios are recent enough to support 64-bit PCI holes, unless this is disabled +(set to 0). :since:`Since 1.1.2 (QEMU only)` + +PCI controllers also have an optional subelement ``<model>`` with an attribute +``name``. The name attribute holds the name of the specific device that qemu is +emulating (e.g. "i82801b11-bridge") rather than simply the class of device +("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller element's +model **attribute**. In almost all cases, you should not manually add a +``<model>`` subelement to a controller, nor should you modify one that is +automatically generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +PCI controllers also have an optional subelement ``<target>`` with the +attributes and subelements listed below. These are configurable items that 1) +are visible to the guest OS so must be preserved for guest ABI compatibility, +and 2) are usually left to default values or derived automatically by libvirt. +In almost all cases, you should not manually add a ``<target>`` subelement to a +controller, nor should you modify the values in the those that are automatically +generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +``chassisNr`` + PCI controllers that have attribute model="pci-bridge", can also have a + ``chassisNr`` attribute in the ``<target>`` subelement, which is used to + control QEMU's "chassis_nr" option for the pci-bridge device (normally + libvirt automatically sets this to the same value as the index attribute of + the pci controller). If set, chassisNr must be between 1 and 255. +``chassis`` + pcie-root-port and pcie-switch-downstream-port controllers can also have a + ``chassis`` attribute in the ``<target>`` subelement, which is used to set + the controller's "chassis" configuration value, which is visible to the + virtual machine. If set, chassis must be between 0 and 255. +``port`` + pcie-root-port and pcie-switch-downstream-port controllers can also have a + ``port`` attribute in the ``<target>`` subelement, which is used to set the + controller's "port" configuration value, which is visible to the virtual + machine. If set, port must be between 0 and 255. +``hotplug`` + pcie-root-port and pcie-switch-downstream-port controllers can also have a + ``hotplug`` attribute in the ``<target>`` subelement, which is used to + disable hotplug/unplug of devices on a particular controller. The default + setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable + hotplug/unplug of devices on a particular controller. :since:`Since 6.3.0` +``busNr`` + pci-expander-bus and pcie-expander-bus controllers can have an optional + ``busNr`` attribute (1-254). This will be the bus number of the new bus; All + bus numbers between that specified and 255 will be available only for + assignment to PCI/PCIe controllers plugged into the hierarchy starting with + this expander bus, and bus numbers less than the specified value will be + available to the next lower expander-bus (or the root-bus if there are no + lower expander buses). If you do not specify a busNumber, libvirt will find + the lowest existing busNumber in all other expander buses (or use 256 if + there are no others) and auto-assign the busNr of that found bus - 2, which + provides one bus number for the pci-expander-bus and one for the pci-bridge + that is automatically attached to it (if you plan on adding more pci-bridges + to the hierarchy of the bus, you should manually set busNr to a lower value). + + A similar algorithm is used for automatically determining the busNr attribute + for pcie-expander-bus, but since the pcie-expander-bus doesn't have any + built-in pci-bridge, the 2nd bus-number is just being reserved for the + pcie-root-port that must necessarily be connected to the bus in order to + actually plug in an endpoint device. If you intend to plug multiple devices + into a pcie-expander-bus, you must connect a pcie-switch-upstream-port to the + pcie-root-port that is plugged into the pcie-expander-bus, and multiple + pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of course + for this to work properly, you will need to decrease the pcie-expander-bus' + busNr accordingly so that there are enough unused bus numbers above it to + accommodate giving out one bus number for the upstream-port and one for each + downstream-port (in addition to the pcie-root-port and the pcie-expander-bus + itself). + +``node`` + Some PCI controllers (``pci-expander-bus`` for the pc machine type, + ``pcie-expander-bus`` for the q35 machine type and, :since:`since 3.6.0` , + ``pci-root`` for the pseries machine type) can have an optional ``<node>`` + subelement within the ``<target>`` subelement, which is used to set the NUMA + node reported to the guest OS for that bus - the guest OS will then know that + all devices on that bus are a part of the specified NUMA node (it is up to + the user of the libvirt API to attach host devices to the correct + pci-expander-bus when assigning them to the domain). +``index`` + pci-root controllers for pSeries guests use this attribute to record the + order they will show up in the guest. :since:`Since 3.6.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 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. + +:: + + ... + <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> + ... + +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, provides 31 slots (numbered 1-31) that can be used to attach PCIe or +PCI devices (although libvirt will never auto-assign a PCI device to a PCIe +slot, it will allow manual specification of such an assignment). Devices +connected to pcie-root cannot be hotplugged. If traditional PCI devices are +present in the guest configuration, a ``pcie-to-pci-bridge`` controller will +automatically be added: this controller, which plugs into a ``pcie-root-port``, +provides 31 usable PCI slots (1-31) with hotplug support ( :since:`since 4.3.0` +). If the QEMU binary doesn't support the corresponding device, then a +``dmi-to-pci-bridge`` controller will be added instead, usually at the defacto +standard location of slot=0x1e. A dmi-to-pci-bridge controller plugs into a PCIe +slot (as provided by pcie-root), and itself provides 31 standard PCI slots +(which also do not support device hotplug). 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 PCI devices with addresses that are auto-determined by +libvirt will be placed on this pci-bridge device. ( :since:`since 1.1.2` ). + +Domains with an implicit pcie-root can also add controllers with +``model='pcie-root-port'``, ``model='pcie-switch-upstream-port'``, and +``model='pcie-switch-downstream-port'``. pcie-root-port is a simple type of +bridge device that can connect only to one of the 31 slots on the pcie-root bus +on its upstream side, and makes a single (PCIe, hotpluggable) port available on +the downstream side (at slot='0'). pcie-root-port can be used to provide a +single slot to later hotplug a PCIe device (but is not itself hotpluggable - it +must be in the configuration when the domain is started). ( :since:`since +1.2.19` ) + +pcie-switch-upstream-port is a more flexible (but also more complex) device that +can only plug into a pcie-root-port or pcie-switch-downstream-port on the +upstream side (and only before the domain is started - it is not hot-pluggable), +and provides 32 ports on the downstream side (slot='0' - slot='31') that accept +only pcie-switch-downstream-port devices; each pcie-switch-downstream-port +device can only plug into a pcie-switch-upstream-port on its upstream side +(again, not hot-pluggable), and on its downstream side provides a single +hotpluggable pcie port that can accept any standard pci or pcie device (or +another pcie-switch-upstream-port), i.e. identical in function to a +pcie-root-port. ( :since:`since 1.2.19` ) + +:: + + ... + <devices> + <controller type='pci' index='0' model='pcie-root'/> + <controller type='pci' index='1' model='pcie-root-port'> + <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/> + </controller> + <controller type='pci' index='2' model='pcie-to-pci-bridge'> + <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/> + </controller> + </devices> + ... diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index 16be7883b6..e65020330d 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -43,312 +43,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-filesystem.rst .. include:: formatdomain-devices-address.rst .. include:: formatdomain-devices-virtio.rst - -:anchor:`<a id="elementsControllers"/>` - -Controllers -~~~~~~~~~~~ - -Depending on the guest 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 sometimes it is necessary to provide an explicit controller element, -notably when planning the `PCI topology <pci-hotplug.html>`__ for guests where -device hotplug is expected. - -:: - - ... - <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> - <controller type='scsi' index='0' model='virtio-scsi'> - <driver iothread='4'/> - <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/> - </controller> - <controller type='xenbus' maxGrantFrames='64' maxEventChannels='2047'/> - ... - </devices> - ... - -Each controller has a mandatory attribute ``type``, which must be one of 'ide', -'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mandatory -attribute ``index`` which is the decimal integer describing in which order the -bus controller is encountered (for use in ``controller`` attributes of -``<address>`` elements). :since:`Since 1.3.5` the index is optional; if not -specified, it will be auto-assigned to be the lowest unused index for the given -controller type. Some controller types have additional attributes that control -specific features, such as: - -``virtio-serial`` - The ``virtio-serial`` controller has two additional optional attributes - ``ports`` and ``vectors``, which control how many devices can be connected - through the controller. :since:`Since 5.2.0` , it supports an optional - attribute ``model`` which can be 'virtio', 'virtio-transitional', or - 'virtio-non-transitional'. See `Virtio transitional - devices <#elementsVirtioTransitional>`__ for more details. -``scsi`` - A ``scsi`` controller has an optional attribute ``model``, which is one of - 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', - 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'. - See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more - details. -``usb`` - A ``usb`` controller has an optional attribute ``model``, which is one of - "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", - "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb - with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu backend, - version 2.0) or "qemu-xhci". Additionally, :since:`since 0.10.0` , if the USB - bus needs to be explicitly disabled for the guest, ``model='none'`` may be - used. :since:`Since 1.0.5` , no default USB controller will be built on s390. - :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to - configure how many devices can be connected to the controller. -``ide`` - :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an - optional attribute ``model``, which is one of "piix3", "piix4" or "ich6". -``xenbus`` - :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attribute - ``maxGrantFrames``, which specifies the maximum number of grant frames the - controller makes available for connected devices. :since:`Since 6.3.0` , the - xenbus controller supports the optional ``maxEventChannels`` attribute, which - specifies maximum number of event channels (PV interrupts) that can be used - by the guest. - -Note: The PowerPC64 "spapr-vio" addresses do not have an associated controller. - -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 `given above <#elementsAddress>`__. - -An optional sub-element ``driver`` can specify the driver specific options: - -``queues`` - The optional ``queues`` attribute specifies the number of queues for the - controller. For best performance, it's recommended to specify a value - matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` -``cmd_per_lun`` - The optional ``cmd_per_lun`` attribute specifies the maximum number of - commands that can be queued on devices controlled by the host. :since:`Since - 1.2.7 (QEMU and KVM only)` -``max_sectors`` - The optional ``max_sectors`` attribute specifies the maximum amount of data - in bytes that will be transferred to or from the device in a single command. - The transfer length is measured in sectors, where a sector is 512 bytes. - :since:`Since 1.2.7 (QEMU and KVM only)` -``ioeventfd`` - The optional ``ioeventfd`` attribute specifies whether the controller should - use `I/O asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__ - or not. Accepted values are "on" and "off". :since:`Since 1.2.18` -``iothread`` - Supported for controller type ``scsi`` using model ``virtio-scsi`` for - ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` . The - optional ``iothread`` attribute assigns the controller to an IOThread as - defined by the range for the domain - `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` - assigned to use the specified ``controller`` will utilize the same IOThread. - If a specific IOThread is desired for a specific SCSI ``disk``, then multiple - controllers must be defined each having a specific ``iothread`` value. The - ``iothread`` value must be within the range 1 to the domain iothreads value. -virtio options - For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ can - also be set. ( :since:`Since 3.5.0` ) - -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 ``index`` value -should be equal. Not all controller models can be used as companion controllers -and libvirt might provide some sensible defaults (settings of -``master startport`` and ``function`` of an address) for some particular models. -Preferred companion controllers are ``ich-uhci[123]``. - -:: - - ... - <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> - ... - -PCI controllers have an optional ``model`` attribute; possible values for this -attribute are - -- ``pci-root``, ``pci-bridge`` ( :since:`since 1.0.5` ) -- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` ) -- ``pcie-root-port``, ``pcie-switch-upstream-port``, - ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` ) -- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` ) -- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` ) - -The root controllers (``pci-root`` and ``pcie-root``) have an optional -``pcihole64`` element specifying how big (in kilobytes, or in the unit specified -by ``pcihole64``'s ``unit`` attribute) the 64-bit PCI hole should be. Some -guests (like Windows XP or Windows Server 2003) might crash when QEMU and -Seabios are recent enough to support 64-bit PCI holes, unless this is disabled -(set to 0). :since:`Since 1.1.2 (QEMU only)` - -PCI controllers also have an optional subelement ``<model>`` with an attribute -``name``. The name attribute holds the name of the specific device that qemu is -emulating (e.g. "i82801b11-bridge") rather than simply the class of device -("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller element's -model **attribute**. In almost all cases, you should not manually add a -``<model>`` subelement to a controller, nor should you modify one that is -automatically generated by libvirt. :since:`Since 1.2.19 (QEMU only).` - -PCI controllers also have an optional subelement ``<target>`` with the -attributes and subelements listed below. These are configurable items that 1) -are visible to the guest OS so must be preserved for guest ABI compatibility, -and 2) are usually left to default values or derived automatically by libvirt. -In almost all cases, you should not manually add a ``<target>`` subelement to a -controller, nor should you modify the values in the those that are automatically -generated by libvirt. :since:`Since 1.2.19 (QEMU only).` - -``chassisNr`` - PCI controllers that have attribute model="pci-bridge", can also have a - ``chassisNr`` attribute in the ``<target>`` subelement, which is used to - control QEMU's "chassis_nr" option for the pci-bridge device (normally - libvirt automatically sets this to the same value as the index attribute of - the pci controller). If set, chassisNr must be between 1 and 255. -``chassis`` - pcie-root-port and pcie-switch-downstream-port controllers can also have a - ``chassis`` attribute in the ``<target>`` subelement, which is used to set - the controller's "chassis" configuration value, which is visible to the - virtual machine. If set, chassis must be between 0 and 255. -``port`` - pcie-root-port and pcie-switch-downstream-port controllers can also have a - ``port`` attribute in the ``<target>`` subelement, which is used to set the - controller's "port" configuration value, which is visible to the virtual - machine. If set, port must be between 0 and 255. -``hotplug`` - pcie-root-port and pcie-switch-downstream-port controllers can also have a - ``hotplug`` attribute in the ``<target>`` subelement, which is used to - disable hotplug/unplug of devices on a particular controller. The default - setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable - hotplug/unplug of devices on a particular controller. :since:`Since 6.3.0` -``busNr`` - pci-expander-bus and pcie-expander-bus controllers can have an optional - ``busNr`` attribute (1-254). This will be the bus number of the new bus; All - bus numbers between that specified and 255 will be available only for - assignment to PCI/PCIe controllers plugged into the hierarchy starting with - this expander bus, and bus numbers less than the specified value will be - available to the next lower expander-bus (or the root-bus if there are no - lower expander buses). If you do not specify a busNumber, libvirt will find - the lowest existing busNumber in all other expander buses (or use 256 if - there are no others) and auto-assign the busNr of that found bus - 2, which - provides one bus number for the pci-expander-bus and one for the pci-bridge - that is automatically attached to it (if you plan on adding more pci-bridges - to the hierarchy of the bus, you should manually set busNr to a lower value). - - A similar algorithm is used for automatically determining the busNr attribute - for pcie-expander-bus, but since the pcie-expander-bus doesn't have any - built-in pci-bridge, the 2nd bus-number is just being reserved for the - pcie-root-port that must necessarily be connected to the bus in order to - actually plug in an endpoint device. If you intend to plug multiple devices - into a pcie-expander-bus, you must connect a pcie-switch-upstream-port to the - pcie-root-port that is plugged into the pcie-expander-bus, and multiple - pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of course - for this to work properly, you will need to decrease the pcie-expander-bus' - busNr accordingly so that there are enough unused bus numbers above it to - accommodate giving out one bus number for the upstream-port and one for each - downstream-port (in addition to the pcie-root-port and the pcie-expander-bus - itself). - -``node`` - Some PCI controllers (``pci-expander-bus`` for the pc machine type, - ``pcie-expander-bus`` for the q35 machine type and, :since:`since 3.6.0` , - ``pci-root`` for the pseries machine type) can have an optional ``<node>`` - subelement within the ``<target>`` subelement, which is used to set the NUMA - node reported to the guest OS for that bus - the guest OS will then know that - all devices on that bus are a part of the specified NUMA node (it is up to - the user of the libvirt API to attach host devices to the correct - pci-expander-bus when assigning them to the domain). -``index`` - pci-root controllers for pSeries guests use this attribute to record the - order they will show up in the guest. :since:`Since 3.6.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 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. - -:: - - ... - <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> - ... - -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, provides 31 slots (numbered 1-31) that can be used to attach PCIe or -PCI devices (although libvirt will never auto-assign a PCI device to a PCIe -slot, it will allow manual specification of such an assignment). Devices -connected to pcie-root cannot be hotplugged. If traditional PCI devices are -present in the guest configuration, a ``pcie-to-pci-bridge`` controller will -automatically be added: this controller, which plugs into a ``pcie-root-port``, -provides 31 usable PCI slots (1-31) with hotplug support ( :since:`since 4.3.0` -). If the QEMU binary doesn't support the corresponding device, then a -``dmi-to-pci-bridge`` controller will be added instead, usually at the defacto -standard location of slot=0x1e. A dmi-to-pci-bridge controller plugs into a PCIe -slot (as provided by pcie-root), and itself provides 31 standard PCI slots -(which also do not support device hotplug). 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 PCI devices with addresses that are auto-determined by -libvirt will be placed on this pci-bridge device. ( :since:`since 1.1.2` ). - -Domains with an implicit pcie-root can also add controllers with -``model='pcie-root-port'``, ``model='pcie-switch-upstream-port'``, and -``model='pcie-switch-downstream-port'``. pcie-root-port is a simple type of -bridge device that can connect only to one of the 31 slots on the pcie-root bus -on its upstream side, and makes a single (PCIe, hotpluggable) port available on -the downstream side (at slot='0'). pcie-root-port can be used to provide a -single slot to later hotplug a PCIe device (but is not itself hotpluggable - it -must be in the configuration when the domain is started). ( :since:`since -1.2.19` ) - -pcie-switch-upstream-port is a more flexible (but also more complex) device that -can only plug into a pcie-root-port or pcie-switch-downstream-port on the -upstream side (and only before the domain is started - it is not hot-pluggable), -and provides 32 ports on the downstream side (slot='0' - slot='31') that accept -only pcie-switch-downstream-port devices; each pcie-switch-downstream-port -device can only plug into a pcie-switch-upstream-port on its upstream side -(again, not hot-pluggable), and on its downstream side provides a single -hotpluggable pcie port that can accept any standard pci or pcie device (or -another pcie-switch-upstream-port), i.e. identical in function to a -pcie-root-port. ( :since:`since 1.2.19` ) - -:: - - ... - <devices> - <controller type='pci' index='0' model='pcie-root'/> - <controller type='pci' index='1' model='pcie-root-port'> - <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/> - </controller> - <controller type='pci' index='2' model='pcie-to-pci-bridge'> - <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/> - </controller> - </devices> - ... +.. include:: formatdomain-devices-controller.rst :anchor:`<a id="elementsLease"/>` diff --git a/docs/meson.build b/docs/meson.build index f7c8f12579..fb65cef2e5 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -128,6 +128,7 @@ docs_rst_files = [ 'formatdomain-devices-filesystem.rst', 'formatdomain-devices-address.rst', 'formatdomain-devices-virtio.rst', + 'formatdomain-devices-controller.rst', ] }, { 'name': 'hacking' }, -- 2.26.2