From nobody Sun Feb 8 20:50:54 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1731000931480125.06660520041567; Thu, 7 Nov 2024 09:35:31 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 54C6E1624; Thu, 7 Nov 2024 12:35:30 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 2ACC31650; Thu, 7 Nov 2024 12:35:00 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 9BA011600; Thu, 7 Nov 2024 12:34:57 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id B8DE715FA for ; Thu, 7 Nov 2024 12:34:56 -0500 (EST) Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-692-WsUc5GD1OcyqCjykXPIOdQ-1; Thu, 07 Nov 2024 12:34:55 -0500 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0D0A619560B2 for ; Thu, 7 Nov 2024 17:34:54 +0000 (UTC) Received: from harajuku.usersys.redhat.com (unknown [10.45.224.96]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 362663003B71 for ; Thu, 7 Nov 2024 17:34:52 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1731000896; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Ap3KTrC+qrLggcJ0qOQ8c5f9H3FWgBOaV2j7TzsWbzY=; b=NtbHofdmlsNdsbdpGVUhAqursW/5iK4IHxMA6KlyYyQeofvd+nuszNLqGapE2rXP0Iiz24 BFVeftDUjUy2+MvAktyH4zmjmdL1Vw78905sGAHaB7vsDISIitVC5zZ7AeT2hgoLtIth+k 8A0peZHOe049x0fZ4o4XLwlHpTPUuFQ= X-MC-Unique: WsUc5GD1OcyqCjykXPIOdQ-1 X-Mimecast-MFC-AGG-ID: WsUc5GD1OcyqCjykXPIOdQ From: Andrea Bolognani To: devel@lists.libvirt.org Subject: [PATCH v2] docs: Recommend virtio instead of virtio-(non-)transitional Date: Thu, 7 Nov 2024 18:34:49 +0100 Message-ID: <20241107173449.115588-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: VGq0YSen-5bcGqNn0vneaBqjFNb1UOcsvph-619UaiA_1731000894 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: ZM6TCZUBCM3SYX4IEMY27ILUCIFDFYND X-Message-ID-Hash: ZM6TCZUBCM3SYX4IEMY27ILUCIFDFYND X-MailFrom: abologna@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1731000932541116600 Content-Type: text/plain; charset="utf-8"; x-default="true" 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 Reviewed-by: Martin Kletzander --- 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 @@ -2756,8 +2756,8 @@ paravirtualized driver is specified via the ``disk`` = element. ``model`` Indicates the emulated device model of the disk. Typically this is indicated solely by the ``bus`` property but for ``bus`` "virtio" the - model can be specified further with "virtio-transitional", - "virtio-non-transitional", or "virtio". See `Virtio transitional dev= ices`_ + model can be specified further with "virtio", "virtio-transitional" = or + "virtio-non-transitional". See `virtio device models`_ for more details. :since:`Since 5.2.0` ``rawio`` Indicates whether the disk needs rawio capability. Valid settings are @@ -3680,9 +3680,8 @@ A directory on the host that can be accessed directly= from the guest. info `__ =20 :since:`Since 5.2.0`, the filesystem element has an optional attribute - ``model`` with supported values "virtio-transitional", - "virtio-non-transitional", or "virtio". See `Virtio transitional device= s`_ - for more details. + ``model`` with supported values "virtio", "virtio-transitional" or + "virtio-non-transitional". See `virtio device models`_ for more details. =20 The filesystem element has optional attributes ``fmode`` and ``dmode``. These two attributes control the creation mode for files and directories @@ -3910,11 +3909,20 @@ Note: In general you should leave this option alone= , unless you are very certain you know what you are doing. =20 =20 -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 ``mo= del`` +attribute, which supports the following values: =20 -:since:`Since 5.2.0`, some of QEMU's virtio devices, when used with PCI/PC= Ie -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 ra= nge + of architectures, machine types and libvirt versions. + +:since:`Since 5.2.0`, the following values can additionally be used with m= achine +types based on PCI (either conventional PCI or PCI Express): =20 ``virtio-transitional`` This device can work both with virtio 0.9 and virtio 1.0 guest drivers,= so @@ -3926,12 +3934,6 @@ machine types, accept the following ``model`` values: necessary. libvirt will plug the device into either a PCI Express slot = or a conventional PCI slot based on the machine type, resulting in a more optimized PCI topology. -``virtio`` - This device will work like a ``virtio-non-transitional`` device when pl= ugged - into a PCI Express slot, and like a ``virtio-transitional`` device othe= rwise; - libvirt will pick one or the other based on the machine type. This is t= he - best choice when compatibility with libvirt versions older than 5.2.0 is - necessary, but it's otherwise not recommended to use it. =20 While the information outlined above applies to most virtio devices, there= are a few exceptions: @@ -3992,14 +3994,14 @@ specific features, such as: The ``virtio-serial`` controller has two additional optional attributes ``ports`` and ``vectors``, which control how many devices can be connec= ted through the controller. :since:`Since 5.2.0`, it supports an optional - attribute ``model`` which can be 'virtio', 'virtio-transitional', or - 'virtio-non-transitional'. See `Virtio transitional devices`_ for more = details. + attribute ``model`` which can be 'virtio', 'virtio-transitional' or + 'virtio-non-transitional'. See `virtio device models`_ for more details. ``scsi`` A ``scsi`` controller has an optional attribute ``model``, which is one= of 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078', 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitio= nal', 'ncr53c90' (as builtin implicit controller only), 'am53c974', 'dc390'. - See `Virtio transitional devices`_ for more details. + See `virtio device models`_ for more details. ``usb`` A ``usb`` controller has an optional attribute ``model``, which is one = of "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-u= hci2", @@ -4452,9 +4454,8 @@ or: :since:`since 2.5.0` For SCSI devices, user is responsible to make s= ure the device is not used by host. This ``type`` passes all LUNs presen= ted by a single HBA to the guest. :since:`Since 5.2.0`, the ``model`` attri= bute - can be specified further with "virtio-transitional", - "virtio-non-transitional", or "virtio". `Virtio transitional devices= `_ - for more details. + can be specified further with "virtio", "virtio-transitional" or + "virtio-non-transitional". See `virtio device models`_ for more deta= ils. ``mdev`` For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute specifies the device API which determines how the host's vfio driver= will @@ -6300,8 +6301,8 @@ value 'all' which when enabled grabs all input device= s instead of just one, change the grab key combination. ``input`` type ``evdev`` is currently supported only on linux devices. (KVM only) :since:`Since 5.2.0`, the ``input`` element accepts a -``model`` attribute which has the values 'virtio', 'virtio-transitional' a= nd -'virtio-non-transitional'. See `Virtio transitional devices`_ for more det= ails. +``model`` attribute which has the values 'virtio', 'virtio-transitional' or +'virtio-non-transitional'. See `virtio device models`_ for more details. =20 The subelement ``driver`` can be used to tune the virtio options of the de= vice: `Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) @@ -7982,7 +7983,7 @@ Example: manually added device with static PCI slot 2= requested - 'virtio-non-transitional' :since:`Since 5.2.0` - 'xen' - default with Xen =20 - See `Virtio transitional devices`_ for more details. + See `virtio device models`_ for more details. =20 ``autodeflate`` The optional ``autodeflate`` attribute allows to enable/disable (values @@ -8048,7 +8049,7 @@ Example: usage of the RNG device: - 'virtio-transitional' :since:`Since 5.2.0` - 'virtio-non-transitional' :since:`Since 5.2.0` =20 - See `Virtio transitional devices`_ for more details. + See `virtio device models`_ for more details. =20 ``rate`` The optional ``rate`` element allows limiting the rate at which entropy= can @@ -8673,8 +8674,8 @@ Vsock ~~~~~ =20 A vsock host/guest interface. The ``model`` attribute defaults to ``virtio= ``. -:since:`Since 5.2.0` ``model`` can also be 'virtio-transitional' and -'virtio-non-transitional', see `Virtio transitional devices`_ for more de= tails. +:since:`Since 5.2.0` ``model`` can also be 'virtio-transitional' or +'virtio-non-transitional', see `virtio device models`_ for more details. The optional attribute ``address`` of the ``cid`` element specifies the CID assigned to the guest. If the attribute ``auto`` is set to ``yes``, libvir= t will assign a free CID automatically on domain startup. :since:`Since 4.4.0` --=20 2.47.0