Re: [PATCH v2] docs: Recommend virtio instead of virtio-(non-)transitional

When virtio-(non-)transitional models were introduced, the documentation was updated to include them; at the same time, language was introduced indicating that using the existing virtio model is no longer recommended. This is unnecessarily harsh, and has resulted in people incorrectly believing (through no fault of their own) that the virtio model has been deprecated. In reality, it's perfectly fine to use the virtio model as the stress-free option that, while often not producing the ideal PCI topology, will generally get the job done and work reliably across libvirt versions and machine types.

Tweak the documentation so that it hopefully carries the desired message across. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- docs/formatdomain.rst | 55 ++++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index c50744b57b..75dff5a153 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst

@@ -3910,11 +3909,20 @@ Note: In general you should leave this option alone, unless you are very certain you know what you are doing. -Virtio transitional devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Virtio device models +~~~~~~~~~~~~~~~~~~~~ + +Virtio devices come in several variants, some of which are only applicable to +certain machine types or scenarios. The variant can be chosen via the ``model`` +attribute, which supports the following values: -:since:`Since 5.2.0`, some of QEMU's virtio devices, when used with PCI/PCIe -machine types, accept the following ``model`` values: +``virtio`` + This is the recommended choice in the absence of guest OS specific + constraints, as it will will generally work correctly across a large range + of architectures, machine types and libvirt versions. + +:since:`Since 5.2.0`, the following values can additionally be used with machine +types based on PCI (either conventional PCI or PCI Express):