[PATCH] docs: Soften language around use of virtio model name
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
participants (2)
-
Andrea Bolognani -
Daniel P. Berrangé