[PATCH 10/32] docs: formatdomain-devices: Split out virtio information

Thu Jul 23 13:21:15 UTC 2020

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

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatdomain-devices-virtio.rst | 59 +++++++++++++++++++++++++++
 docs/formatdomain-devices.rst        | 61 +---------------------------
 docs/meson.build                     |  1 +
 3 files changed, 61 insertions(+), 60 deletions(-)
 create mode 100644 docs/formatdomain-devices-virtio.rst

diff --git a/docs/formatdomain-devices-virtio.rst b/docs/formatdomain-devices-virtio.rst
new file mode 100644
index 0000000000..21a0603984
--- /dev/null
+++ b/docs/formatdomain-devices-virtio.rst
@@ -0,0 +1,59 @@
+:anchor:`<a id="elementsVirtio"/>`
+
+Virtio-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU's virtio devices have some attributes related to the virtio transport under
+the ``driver`` element: The ``iommu`` attribute enables the use of emulated
+IOMMU by the device. The attribute ``ats`` controls the Address Translation
+Service support for PCIe devices. This is needed to make use of IOTLB support
+(see `IOMMU device <#elementsIommu>`__). Possible values are ``on`` or ``off``.
+:since:`Since 3.5.0`
+
+The attribute ``packed`` controls if QEMU should try to use packed virtqueues.
+Compared to regular split queues, packed queues consist of only a single
+descriptor ring replacing available and used ring, index and descriptor buffer.
+This can result in better cache utilization and performance. If packed
+virtqueues are actually used depends on the feature negotiation between QEMU,
+vhost backends and guest drivers. Possible values are ``on`` or ``off``.
+:since:`Since 6.3.0 (QEMU and KVM only)`
+
+:anchor:`<a id="elementsVirtioTransitional"/>`
+
+Virtio transitional devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/PCIe
+machine types, accept the following ``model`` values:
+
+``virtio-transitional``
+   This device can work both with virtio 0.9 and virtio 1.0 guest drivers, so
+   it's the best choice when compatibility with older guest operating systems is
+   desired. libvirt will plug the device into a conventional PCI slot.
+``virtio-non-transitional``
+   This device can only work with virtio 1.0 guest drivers, and it's the
+   recommended option unless compatibility with older guest operating systems is
+   necessary. libvirt will plug the device into either a PCI Express slot or a
+   conventional PCI slot based on the machine type, resulting in a more
+   optimized PCI topology.
+``virtio``
+   This device will work like a ``virtio-non-transitional`` device when plugged
+   into a PCI Express slot, and like a ``virtio-transitional`` device otherwise;
+   libvirt will pick one or the other based on the machine type. This is the
+   best choice when compatibility with libvirt versions older than 5.2.0 is
+   necessary, but it's otherwise not recommended to use it.
+
+While the information outlined above applies to most virtio devices, there are a
+few exceptions:
+
+-  for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`` for
+   backwards compatibility reasons;
+-  some devices, such as GPUs and input devices (keyboard, tablet and mouse),
+   are only defined in the virtio 1.0 spec and as such don't have a transitional
+   variant: the only accepted model is ``virtio``, which will result in a
+   non-transitional device.
+
+For more details see the `qemu patch
+posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__
+and the `virtio-1.0
+spec <http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__.
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index c789495e5d..16be7883b6 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -42,66 +42,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
 .. include:: formatdomain-devices-disk.rst
 .. include:: formatdomain-devices-filesystem.rst
 .. include:: formatdomain-devices-address.rst
-
-:anchor:`<a id="elementsVirtio"/>`
-
-Virtio-related options
-~~~~~~~~~~~~~~~~~~~~~~
-
-QEMU's virtio devices have some attributes related to the virtio transport under
-the ``driver`` element: The ``iommu`` attribute enables the use of emulated
-IOMMU by the device. The attribute ``ats`` controls the Address Translation
-Service support for PCIe devices. This is needed to make use of IOTLB support
-(see `IOMMU device <#elementsIommu>`__). Possible values are ``on`` or ``off``.
-:since:`Since 3.5.0`
-
-The attribute ``packed`` controls if QEMU should try to use packed virtqueues.
-Compared to regular split queues, packed queues consist of only a single
-descriptor ring replacing available and used ring, index and descriptor buffer.
-This can result in better cache utilization and performance. If packed
-virtqueues are actually used depends on the feature negotiation between QEMU,
-vhost backends and guest drivers. Possible values are ``on`` or ``off``.
-:since:`Since 6.3.0 (QEMU and KVM only)`
-
-:anchor:`<a id="elementsVirtioTransitional"/>`
-
-Virtio transitional devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/PCIe
-machine types, accept the following ``model`` values:
-
-``virtio-transitional``
-   This device can work both with virtio 0.9 and virtio 1.0 guest drivers, so
-   it's the best choice when compatibility with older guest operating systems is
-   desired. libvirt will plug the device into a conventional PCI slot.
-``virtio-non-transitional``
-   This device can only work with virtio 1.0 guest drivers, and it's the
-   recommended option unless compatibility with older guest operating systems is
-   necessary. libvirt will plug the device into either a PCI Express slot or a
-   conventional PCI slot based on the machine type, resulting in a more
-   optimized PCI topology.
-``virtio``
-   This device will work like a ``virtio-non-transitional`` device when plugged
-   into a PCI Express slot, and like a ``virtio-transitional`` device otherwise;
-   libvirt will pick one or the other based on the machine type. This is the
-   best choice when compatibility with libvirt versions older than 5.2.0 is
-   necessary, but it's otherwise not recommended to use it.
-
-While the information outlined above applies to most virtio devices, there are a
-few exceptions:
-
--  for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`` for
-   backwards compatibility reasons;
--  some devices, such as GPUs and input devices (keyboard, tablet and mouse),
-   are only defined in the virtio 1.0 spec and as such don't have a transitional
-   variant: the only accepted model is ``virtio``, which will result in a
-   non-transitional device.
-
-For more details see the `qemu patch
-posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__
-and the `virtio-1.0
-spec <http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__.
+.. include:: formatdomain-devices-virtio.rst

 :anchor:`<a id="elementsControllers"/>`

diff --git a/docs/meson.build b/docs/meson.build
index e30f213739..f7c8f12579 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -127,6 +127,7 @@ docs_rst_files = [
                   'formatdomain-devices-disk.rst',
                   'formatdomain-devices-filesystem.rst',
                   'formatdomain-devices-address.rst',
+                  'formatdomain-devices-virtio.rst',
                 ]
   },
   { 'name': 'hacking' },
-- 
2.26.2


