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

On Thu, Nov 07, 2024 at 06:34:49PM +0100, Andrea Bolognani wrote: > 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. > I wonder who reviewed the harsh language back then 🤔 =D > 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): > I think that you cannot specify model='virtio' before 5.2.0. Maybe what Daniel suggested, keeping the mention of compatibility with older versions is the better way to go. From the above one might think that model='virtio' will work on older libvirt, and it will look like it does, but it won't get parsed.