From nobody Mon Feb 9 09:28:52 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510704; cv=none; d=zohomail.com; s=zohoarc; b=glk1Jfa3DgSLh7IVZFNT3GIc4J3dJAZwEbT3eXYQ83UzYBW2frtw4tRqXMVXG9978egDoJg/QK+/kehjzfRJJb2t+0tJqrDRzsH+zwrbQ+Z7eevhX/WudgZIDkIK9sHmiYU+LGJikz8tY6fg+Y9sAKqB8gHgj+y4VMi2jgf/Yvw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510704; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=eHp4aAgYhhtZuwXfvJEqKr9s/+8AOJHEE/FyNBjG1y0=; b=YpMBtt8cdWKt+a2QMyED2ZCVquO+Z+GCYfwQfPXnt/V8ze6PZeFKUHzI5YI5tRpNsCw2LqS4h4bYeE2xDxXdR/sRaeiIgWztfYV8LlGAbV/G38NweMNAnjbPYSXlYdxlgjXabUbkXAr9ENKZ/tD1fPXMiZH6AckzvP3vuI3cMPs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 1595510704970607.3414863273847; Thu, 23 Jul 2020 06:25:04 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-32-SPSFzSBeOIuAkMlE10ZT3A-1; Thu, 23 Jul 2020 09:22:25 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 936E280332F; Thu, 23 Jul 2020 13:22:14 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5D9965D9E2; Thu, 23 Jul 2020 13:22:14 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 1CF64A3586; Thu, 23 Jul 2020 13:22:14 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDMCrh028534 for ; Thu, 23 Jul 2020 09:22:12 -0400 Received: by smtp.corp.redhat.com (Postfix) id 883FC19D7D; Thu, 23 Jul 2020 13:22:12 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id D44911A922 for ; Thu, 23 Jul 2020 13:22:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510703; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=eHp4aAgYhhtZuwXfvJEqKr9s/+8AOJHEE/FyNBjG1y0=; b=Mo7szB0ChDSlvbMt17yhK0nVzrunQR4dGuQBPlew5sdfLS3XaBdUfKZcB5Iz8cXPnKvRHP rK+VdFSL8WdZFKMf5KNkutzu8K+BFOujc9Kd05OTeF1Ft4F3zrbmbxAKkS6eXZD5lXJyUD V2zV+XpANwmxssMplQabIwCPDAQbkos= X-MC-Unique: SPSFzSBeOIuAkMlE10ZT3A-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 11/32] docs: formatdomain-devices: Split out Date: Thu, 23 Jul 2020 15:21:16 +0200 Message-Id: <81b1d9632c2d96b0c92887710484ef65b78ea437.1595510131.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Start splitting out part of into smaller sections. Signed-off-by: Peter Krempa --- 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-d= evices-controller.rst new file mode 100644 index 0000000000..23985271de --- /dev/null +++ b/docs/formatdomain-devices-controller.rst @@ -0,0 +1,305 @@ +:anchor:`` + +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. Normal= ly, +libvirt can automatically infer such controllers without requiring explici= t XML +markup, but sometimes it is necessary to provide an explicit controller el= ement, +notably when planning the `PCI topology `__ for guests w= here +device hotplug is expected. + +:: + + ... + + + + +
+ + + +
+ + + ... + + ... + +Each controller has a mandatory attribute ``type``, which must be one of '= ide', +'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mand= atory +attribute ``index`` which is the decimal integer describing in which order= the +bus controller is encountered (for use in ``controller`` attributes of +``
`` 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 con= trol +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 connec= ted + 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-transitio= nal'. + See `Virtio transitional devices <#elementsVirtioTransitional>`__ for m= ore + details. +``usb`` + A ``usb`` controller has an optional attribute ``model``, which is one = of + "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-u= hci2", + "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pv= usb + 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 t= he USB + bus needs to be explicitly disabled for the guest, ``model=3D'none'`` m= ay 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 attrib= ute + ``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 contro= ller. + +For controllers that are themselves devices on a PCI or USB bus, an option= al +sub-element ``
`` can specify the exact relationship of the contro= ller +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 com= mand. + 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 s= hould + use `I/O asynchronous handling `__ + 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 IOTh= read. + If a specific IOThread is desired for a specific SCSI ``disk``, then mu= ltiple + controllers must be defined each having a specific ``iothread`` value. = The + ``iothread`` value must be within the range 1 to the domain iothreads v= alue. +virtio options + For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ c= an + also be set. ( :since:`Since 3.5.0` ) + +USB companion controllers have an optional sub-element ```` to spe= cify +the exact relationship of the companion to its master controller. A compan= ion +controller is on the same bus as its master, so the companion ``index`` va= lue +should be equal. Not all controller models can be used as companion contro= llers +and libvirt might provide some sensible defaults (settings of +``master startport`` and ``function`` of an address) for some particular m= odels. +Preferred companion controllers are ``ich-uhci[123]``. + +:: + + ... + + +
+ + + +
+ + ... + + ... + +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 spe= cified +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 disa= bled +(set to 0). :since:`Since 1.1.2 (QEMU only)` + +PCI controllers also have an optional subelement ```` with an attri= bute +``name``. The name attribute holds the name of the specific device that qe= mu 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 eleme= nt's +model **attribute**. In almost all cases, you should not manually add a +```` 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 ```` 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 compatibili= ty, +and 2) are usually left to default values or derived automatically by libv= irt. +In almost all cases, you should not manually add a ```` subelement= to a +controller, nor should you modify the values in the those that are automat= ically +generated by libvirt. :since:`Since 1.2.19 (QEMU only).` + +``chassisNr`` + PCI controllers that have attribute model=3D"pci-bridge", can also have= a + ``chassisNr`` attribute in the ```` 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 attribut= e 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 hav= e a + ``chassis`` attribute in the ```` 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 hav= e a + ``port`` attribute in the ```` 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 hav= e a + ``hotplug`` attribute in the ```` subelement, which is used to + disable hotplug/unplug of devices on a particular controller. The defau= lt + 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, w= hich + provides one bus number for the pci-expander-bus and one for the pci-br= idge + that is automatically attached to it (if you plan on adding more pci-br= idges + to the hierarchy of the bus, you should manually set busNr to a lower v= alue). + + A similar algorithm is used for automatically determining the busNr att= ribute + 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 dev= ices + 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 c= ourse + 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-expande= r-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 ```` + subelement within the ```` subelement, which is used to set the= NUMA + node reported to the guest OS for that bus - the guest OS will then kno= w 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 controll= er +with index=3D0 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 o= n 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 controlle= rs. +Leaving gaps in the PCI controller indexes might lead to an invalid +configuration. + +:: + + ... + + + +
+ + + ... + +For machine types which provide an implicit PCI Express (PCIe) bus (for ex= ample, +the machine types based on the Q35 chipset), the pcie-root controller with +index=3D0 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 wi= ll +automatically be added: this controller, which plugs into a ``pcie-root-po= rt``, +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 def= acto +standard location of slot=3D0x1e. A dmi-to-pci-bridge controller plugs int= o 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 automatica= lly +created and connected to one of the slots of the auto-created dmi-to-pci-b= ridge +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=3D'pcie-root-port'``, ``model=3D'pcie-switch-upstream-port'``, and +``model=3D'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-roo= t bus +on its upstream side, and makes a single (PCIe, hotpluggable) port availab= le on +the downstream side (at slot=3D'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) devic= e 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-plugg= able), +and provides 32 ports on the downstream side (slot=3D'0' - slot=3D'31') th= at 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` ) + +:: + + ... + + + +
+ + +
+ + + ... 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:`` - -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. Normal= ly, -libvirt can automatically infer such controllers without requiring explici= t XML -markup, but sometimes it is necessary to provide an explicit controller el= ement, -notably when planning the `PCI topology `__ for guests w= here -device hotplug is expected. - -:: - - ... - - - - -
- - - -
- - - ... - - ... - -Each controller has a mandatory attribute ``type``, which must be one of '= ide', -'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mand= atory -attribute ``index`` which is the decimal integer describing in which order= the -bus controller is encountered (for use in ``controller`` attributes of -``
`` 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 con= trol -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 connec= ted - 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-transitio= nal'. - See `Virtio transitional devices <#elementsVirtioTransitional>`__ for m= ore - details. -``usb`` - A ``usb`` controller has an optional attribute ``model``, which is one = of - "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-u= hci2", - "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pv= usb - 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 t= he USB - bus needs to be explicitly disabled for the guest, ``model=3D'none'`` m= ay 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 attrib= ute - ``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 contro= ller. - -For controllers that are themselves devices on a PCI or USB bus, an option= al -sub-element ``
`` can specify the exact relationship of the contro= ller -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 com= mand. - 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 s= hould - use `I/O asynchronous handling `__ - 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 IOTh= read. - If a specific IOThread is desired for a specific SCSI ``disk``, then mu= ltiple - controllers must be defined each having a specific ``iothread`` value. = The - ``iothread`` value must be within the range 1 to the domain iothreads v= alue. -virtio options - For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ c= an - also be set. ( :since:`Since 3.5.0` ) - -USB companion controllers have an optional sub-element ```` to spe= cify -the exact relationship of the companion to its master controller. A compan= ion -controller is on the same bus as its master, so the companion ``index`` va= lue -should be equal. Not all controller models can be used as companion contro= llers -and libvirt might provide some sensible defaults (settings of -``master startport`` and ``function`` of an address) for some particular m= odels. -Preferred companion controllers are ``ich-uhci[123]``. - -:: - - ... - - -
- - - -
- - ... - - ... - -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 spe= cified -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 disa= bled -(set to 0). :since:`Since 1.1.2 (QEMU only)` - -PCI controllers also have an optional subelement ```` with an attri= bute -``name``. The name attribute holds the name of the specific device that qe= mu 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 eleme= nt's -model **attribute**. In almost all cases, you should not manually add a -```` 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 ```` 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 compatibili= ty, -and 2) are usually left to default values or derived automatically by libv= irt. -In almost all cases, you should not manually add a ```` subelement= to a -controller, nor should you modify the values in the those that are automat= ically -generated by libvirt. :since:`Since 1.2.19 (QEMU only).` - -``chassisNr`` - PCI controllers that have attribute model=3D"pci-bridge", can also have= a - ``chassisNr`` attribute in the ```` 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 attribut= e 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 hav= e a - ``chassis`` attribute in the ```` 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 hav= e a - ``port`` attribute in the ```` 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 hav= e a - ``hotplug`` attribute in the ```` subelement, which is used to - disable hotplug/unplug of devices on a particular controller. The defau= lt - 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, w= hich - provides one bus number for the pci-expander-bus and one for the pci-br= idge - that is automatically attached to it (if you plan on adding more pci-br= idges - to the hierarchy of the bus, you should manually set busNr to a lower v= alue). - - A similar algorithm is used for automatically determining the busNr att= ribute - 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 dev= ices - 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 c= ourse - 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-expande= r-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 ```` - subelement within the ```` subelement, which is used to set the= NUMA - node reported to the guest OS for that bus - the guest OS will then kno= w 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 controll= er -with index=3D0 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 o= n 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 controlle= rs. -Leaving gaps in the PCI controller indexes might lead to an invalid -configuration. - -:: - - ... - - - -
- - - ... - -For machine types which provide an implicit PCI Express (PCIe) bus (for ex= ample, -the machine types based on the Q35 chipset), the pcie-root controller with -index=3D0 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 wi= ll -automatically be added: this controller, which plugs into a ``pcie-root-po= rt``, -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 def= acto -standard location of slot=3D0x1e. A dmi-to-pci-bridge controller plugs int= o 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 automatica= lly -created and connected to one of the slots of the auto-created dmi-to-pci-b= ridge -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=3D'pcie-root-port'``, ``model=3D'pcie-switch-upstream-port'``, and -``model=3D'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-roo= t bus -on its upstream side, and makes a single (PCIe, hotpluggable) port availab= le on -the downstream side (at slot=3D'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) devic= e 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-plugg= able), -and provides 32 ports on the downstream side (slot=3D'0' - slot=3D'31') th= at 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` ) - -:: - - ... - - - -
- - -
- - - ... +.. include:: formatdomain-devices-controller.rst :anchor:`` 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 =3D [ 'formatdomain-devices-filesystem.rst', 'formatdomain-devices-address.rst', 'formatdomain-devices-virtio.rst', + 'formatdomain-devices-controller.rst', ] }, { 'name': 'hacking' }, --=20 2.26.2