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@redhat.com>
---
 docs/formatdomain.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index c50744b57b..b404ea8773 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -3931,7 +3931,7 @@ machine types, accept the following ``model`` values:
    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.
+   necessary or if you're unsure which of the other two options to pick.
 
 While the information outlined above applies to most virtio devices, there are a
 few exceptions:
-- 
2.47.0

On Thu, Nov 07, 2024 at 04:46:07PM +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.
> 
> Tweak the documentation so that it hopefully carries the
> desired message across.
> 
> Signed-off-by: Andrea Bolognani <abologna@redhat.com>
> ---
>  docs/formatdomain.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index c50744b57b..b404ea8773 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -3931,7 +3931,7 @@ machine types, accept the following ``model`` values:
>     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.
> +   necessary or if you're unsure which of the other two options to pick.

I would go even further than this.

IMHO the list should be re-ordered to put 'virtio' first, and then say

   This is the recommended choice, in the absence of any guest OS
   specific constraints, providing compatibility with libvirt
   versions older than 5.2.0.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Thu, Nov 07, 2024 at 03:54:34PM +0000, Daniel P. Berrangé wrote:
> On Thu, Nov 07, 2024 at 04:46:07PM +0100, Andrea Bolognani wrote:
> > +++ b/docs/formatdomain.rst
> > @@ -3931,7 +3931,7 @@ machine types, accept the following ``model`` values:
> >     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.
> > +   necessary or if you're unsure which of the other two options to pick.
>
> I would go even further than this.
>
> IMHO the list should be re-ordered to put 'virtio' first, and then say
>
>    This is the recommended choice, in the absence of any guest OS
>    specific constraints, providing compatibility with libvirt
>    versions older than 5.2.0.

I toyed with that idea before ultimately going for the version I
posted. Given your support for that approach, I'll take another stab
at it.

-- 
Andrea Bolognani / Red Hat / Virtualization