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

Peter Krempa pkrempa at redhat.com
Thu Jul 23 13:21:16 UTC 2020


Start splitting out part of <devices> into smaller sections.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 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




More information about the libvir-list mailing list