[PATCH 09/32] docs: formatdomain-devices: Split out address information
Peter Krempa
pkrempa at redhat.com
Thu Jul 23 13:21:14 UTC 2020
Start splitting out part of <devices> into smaller sections.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatdomain-devices-address.rst | 92 ++++++++++++++++++++++++++
docs/formatdomain-devices.rst | 94 +--------------------------
docs/meson.build | 1 +
3 files changed, 94 insertions(+), 93 deletions(-)
create mode 100644 docs/formatdomain-devices-address.rst
diff --git a/docs/formatdomain-devices-address.rst b/docs/formatdomain-devices-address.rst
new file mode 100644
index 0000000000..902dc94ae1
--- /dev/null
+++ b/docs/formatdomain-devices-address.rst
@@ -0,0 +1,92 @@
+:anchor:`<a id="elementsAddress"/>`
+
+Device Addresses
+~~~~~~~~~~~~~~~~
+
+Many devices have an optional ``<address>`` sub-element to describe where the
+device is placed on the virtual bus presented to the guest. If an address (or
+any optional attribute within an address) is omitted on input, libvirt will
+generate an appropriate address; but an explicit address is required if more
+control over layout is required. See below for device examples including an
+address element.
+
+Every address has a mandatory attribute ``type`` that describes which bus the
+device is on. The choice of which address to use for a given device is
+constrained in part by the device and the architecture of the guest. For
+example, a ``<disk>`` device uses ``type='drive'``, while a ``<console>`` device
+would use ``type='pci'`` on i686 or x86_64 guests, or ``type='spapr-vio'`` on
+PowerPC64 pseries guests. Each address type has further optional attributes that
+control where on the bus the device will be placed:
+
+``pci``
+ PCI addresses have the following additional attributes: ``domain`` (a 2-byte
+ hex integer, not currently used by qemu), ``bus`` (a hex value between 0 and
+ 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive), and
+ ``function`` (a value between 0 and 7, inclusive). Also available is the
+ ``multifunction`` attribute, which controls turning on the multifunction bit
+ for a particular slot/function in the PCI control register ( :since:`since
+ 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but should
+ be set to 'on' for function 0 of a slot that will have multiple functions
+ used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the
+ architecture are supported. For example, PCI addresses for S390 guests will
+ have a ``zpci`` child element, with two attributes: ``uid`` (a hex value
+ between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between
+ 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for
+ User-defined Identifiers and Function Identifiers.
+ :since:`Since 1.3.5` , some hypervisor drivers may accept an
+ ``<address type='pci'/>`` element with no other attributes as an explicit
+ request to assign a PCI address for the device rather than some other type of
+ address that may also be appropriate for that same device (e.g. virtio-mmio).
+ The relationship between the PCI addresses configured in the domain XML and
+ those seen by the guest OS can sometime seem confusing: a separate document
+ describes `how PCI addresses work <pci-addresses.html>`__ in more detail.
+``drive``
+ Drive addresses have the following additional attributes: ``controller`` (a
+ 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` (a
+ 2-digit target number), and ``unit`` (a 2-digit unit number on the bus).
+``virtio-serial``
+ Each virtio-serial address has the following additional attributes:
+ ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus number),
+ and ``slot`` (a 2-digit slot within the bus).
+``ccid``
+ A CCID address, for smart-cards, has the following additional attributes:
+ ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot within
+ the bus). :since:`Since 0.8.8.`
+``usb``
+ USB addresses have the following additional attributes: ``bus`` (a hex value
+ between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up to
+ four octets, such as 1.2 or 2.1.3.1).
+``spapr-vio``
+ On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It
+ has a flat 32-bit address space; by convention, devices are generally
+ assigned at a non-zero multiple of 0x00001000, but other addresses are valid
+ and permitted by libvirt. Each address has the following additional
+ attribute: ``reg`` (the hex value address of the starting register).
+ :since:`Since 0.9.9.`
+``ccw``
+ S390 guests with a ``machine`` value of s390-ccw-virtio use the native CCW
+ bus for I/O devices. CCW bus addresses have the following additional
+ attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ssid``
+ (a value between 0 and 3, inclusive) and ``devno`` (a hex value between 0 and
+ 0xffff, inclusive). Partially specified bus addresses are not allowed. If
+ omitted, libvirt will assign a free bus address with cssid=0xfe and ssid=0.
+ Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0.4`
+``virtio-mmio``
+ This places the device on the virtio-mmio transport, which is currently only
+ available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-mmio
+ addresses do not have any additional attributes. :since:`Since 1.1.3`
+ If the guest architecture is ``aarch64`` and the machine type is ``virt``,
+ libvirt will automatically assign PCI addresses to devices; however, the
+ presence of a single device with virtio-mmio address in the guest
+ configuration will cause libvirt to assign virtio-mmio addresses to all
+ further devices. :since:`Since 3.0.0`
+``isa``
+ ISA addresses have the following additional attributes: ``iobase`` and
+ ``irq``. :since:`Since 1.2.1`
+``unassigned``
+ For PCI hostdevs, ``<address type='unassigned'/>`` allows the admin to
+ include a PCI hostdev in the domain XML definition, without making it
+ available for the guest. This allows for configurations in which Libvirt
+ manages the device as a regular PCI hostdev, regardless of whether the guest
+ will have access to it. ``<address type='unassigned'/>`` is an invalid
+ address type for all other device types. :since:`Since 6.0.0`
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index 564ce4caca..c789495e5d 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -41,99 +41,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
.. include:: formatdomain-devices-disk.rst
.. include:: formatdomain-devices-filesystem.rst
-
-:anchor:`<a id="elementsAddress"/>`
-
-Device Addresses
-~~~~~~~~~~~~~~~~
-
-Many devices have an optional ``<address>`` sub-element to describe where the
-device is placed on the virtual bus presented to the guest. If an address (or
-any optional attribute within an address) is omitted on input, libvirt will
-generate an appropriate address; but an explicit address is required if more
-control over layout is required. See below for device examples including an
-address element.
-
-Every address has a mandatory attribute ``type`` that describes which bus the
-device is on. The choice of which address to use for a given device is
-constrained in part by the device and the architecture of the guest. For
-example, a ``<disk>`` device uses ``type='drive'``, while a ``<console>`` device
-would use ``type='pci'`` on i686 or x86_64 guests, or ``type='spapr-vio'`` on
-PowerPC64 pseries guests. Each address type has further optional attributes that
-control where on the bus the device will be placed:
-
-``pci``
- PCI addresses have the following additional attributes: ``domain`` (a 2-byte
- hex integer, not currently used by qemu), ``bus`` (a hex value between 0 and
- 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive), and
- ``function`` (a value between 0 and 7, inclusive). Also available is the
- ``multifunction`` attribute, which controls turning on the multifunction bit
- for a particular slot/function in the PCI control register ( :since:`since
- 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but should
- be set to 'on' for function 0 of a slot that will have multiple functions
- used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the
- architecture are supported. For example, PCI addresses for S390 guests will
- have a ``zpci`` child element, with two attributes: ``uid`` (a hex value
- between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between
- 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for
- User-defined Identifiers and Function Identifiers.
- :since:`Since 1.3.5` , some hypervisor drivers may accept an
- ``<address type='pci'/>`` element with no other attributes as an explicit
- request to assign a PCI address for the device rather than some other type of
- address that may also be appropriate for that same device (e.g. virtio-mmio).
- The relationship between the PCI addresses configured in the domain XML and
- those seen by the guest OS can sometime seem confusing: a separate document
- describes `how PCI addresses work <pci-addresses.html>`__ in more detail.
-``drive``
- Drive addresses have the following additional attributes: ``controller`` (a
- 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` (a
- 2-digit target number), and ``unit`` (a 2-digit unit number on the bus).
-``virtio-serial``
- Each virtio-serial address has the following additional attributes:
- ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus number),
- and ``slot`` (a 2-digit slot within the bus).
-``ccid``
- A CCID address, for smart-cards, has the following additional attributes:
- ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot within
- the bus). :since:`Since 0.8.8.`
-``usb``
- USB addresses have the following additional attributes: ``bus`` (a hex value
- between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up to
- four octets, such as 1.2 or 2.1.3.1).
-``spapr-vio``
- On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It
- has a flat 32-bit address space; by convention, devices are generally
- assigned at a non-zero multiple of 0x00001000, but other addresses are valid
- and permitted by libvirt. Each address has the following additional
- attribute: ``reg`` (the hex value address of the starting register).
- :since:`Since 0.9.9.`
-``ccw``
- S390 guests with a ``machine`` value of s390-ccw-virtio use the native CCW
- bus for I/O devices. CCW bus addresses have the following additional
- attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ssid``
- (a value between 0 and 3, inclusive) and ``devno`` (a hex value between 0 and
- 0xffff, inclusive). Partially specified bus addresses are not allowed. If
- omitted, libvirt will assign a free bus address with cssid=0xfe and ssid=0.
- Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0.4`
-``virtio-mmio``
- This places the device on the virtio-mmio transport, which is currently only
- available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-mmio
- addresses do not have any additional attributes. :since:`Since 1.1.3`
- If the guest architecture is ``aarch64`` and the machine type is ``virt``,
- libvirt will automatically assign PCI addresses to devices; however, the
- presence of a single device with virtio-mmio address in the guest
- configuration will cause libvirt to assign virtio-mmio addresses to all
- further devices. :since:`Since 3.0.0`
-``isa``
- ISA addresses have the following additional attributes: ``iobase`` and
- ``irq``. :since:`Since 1.2.1`
-``unassigned``
- For PCI hostdevs, ``<address type='unassigned'/>`` allows the admin to
- include a PCI hostdev in the domain XML definition, without making it
- available for the guest. This allows for configurations in which Libvirt
- manages the device as a regular PCI hostdev, regardless of whether the guest
- will have access to it. ``<address type='unassigned'/>`` is an invalid
- address type for all other device types. :since:`Since 6.0.0`
+.. include:: formatdomain-devices-address.rst
:anchor:`<a id="elementsVirtio"/>`
diff --git a/docs/meson.build b/docs/meson.build
index e4e7cf4c89..e30f213739 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -126,6 +126,7 @@ docs_rst_files = [
'includes': [ 'formatdomain-devices.rst',
'formatdomain-devices-disk.rst',
'formatdomain-devices-filesystem.rst',
+ 'formatdomain-devices-address.rst',
]
},
{ 'name': 'hacking' },
--
2.26.2
More information about the libvir-list
mailing list