docs: formatdomain: Clarify configuration of iothread <-> virtqueue mapping

Add an example for the automatic/round-robin mapping of iothreads which
users should preferrably use. Until now the example contained even the
full mapping which could push users to use that instead.

Mention that the queues are then automatically distributed among the
iothreads.

Also clarify the need to set 'queues' when mapping threads explicitly
and how the queues are identified.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 3bbf94e192c9883cab0d5e9304bc6d31c825183c..543b36cb2ef4d7998c5e22cfa8eb73690be31524 100644 (file)
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -3464,10 +3464,27 @@ paravirtualized driver is specified via the ``disk`` element.
       *Note:* ``iothread`` is mutually exclusive with ``iothreads``.
    -  The optional ``iothreads`` sub-element allows specifying multiple IOThreads
       via the ``iothread`` sub-element with attribute ``id``  the disk will use
-      for I/O operations. Optionally the ``iothread`` element can have multiple
-      ``queue`` subelements specifying that given iothread should be used to
-      handle given queues. :since:`Since 10.0.0 (QEMU 9.0, virtio disks only)`.
-      Example::
+      for I/O operations. The virt queues (see ``queues`` attribute below) are
+      automatically distributed among the configured iothreads.
+
+      Optionally the ``iothread`` element can have multiple ``queue``
+      subelements with mandatory ``id`` atribute specifying that the iothread
+      should be used to handle given virt queue. If queue mapping is present
+      the ``queues`` attribute of  ``driver`` must be configured and all
+      configured virt queues must be included in the mapping. The
+      ``virtio-blk`` device exposes request virt queues ``0`` to ``N-1`` where
+      N is the number of queues configured for the device.
+
+      :since:`Since 10.0.0 (QEMU 9.0, virtio disks only)`.
+
+      Examples::
+
+        <driver name='qemu' queues='4'>
+          <iothreads>
+            <iothread id='2'/>
+            <iothread id='3'/>
+          </iothreads>
+        </driver>
 
         <driver name='qemu' queues='3'>
           <iothreads>