From nobody Tue Jan 21 04:20:59 2025 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 173643334383824.05324511469405; Thu, 9 Jan 2025 06:35:43 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id DE05F14E1; Thu, 9 Jan 2025 09:35:42 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id F31D6143F; Thu, 9 Jan 2025 09:35:17 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 4A2FC1402; Thu, 9 Jan 2025 09:35:15 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.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 AB01613E3 for ; Thu, 9 Jan 2025 09:35:14 -0500 (EST) Received: from mx-prod-mc-02.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-459-6sNZnp8xOymg05yH5NjJNg-1; Thu, 09 Jan 2025 09:35:12 -0500 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E42EA1955DD1 for ; Thu, 9 Jan 2025 14:35:11 +0000 (UTC) Received: from orkuz (unknown [10.43.3.115]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 6DB4C19560AD for ; Thu, 9 Jan 2025 14:35:11 +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_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=1736433314; 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=XK81AMXQ27QarcMvX6YZE/L5lxUdlGITOTfdFYtWN28=; b=RdqhXNVG0ASE1O8RXc4H3YDkP2Uq8HLfeyGMprDtdawPR27FFmZoDjsdt/t5Nr35nNzWYe i5sVEDt0/Nw7AHJ0WF13nRsX5LYaaB26Q0rvLRy3dmsDIVSrpbSZDC1KmaQGFz2BicMzzu /pGSlxh2vFAyMQYssMh+C/UxXdpI7/M= X-MC-Unique: 6sNZnp8xOymg05yH5NjJNg-1 X-Mimecast-MFC-AGG-ID: 6sNZnp8xOymg05yH5NjJNg From: Jiri Denemark To: devel@lists.libvirt.org Subject: [PATCH] docs: Clarify documentation of host-model CPU mode Date: Thu, 9 Jan 2025 15:35:09 +0100 Message-ID: <9ff8dac9d422da2979077fb7fafd6f3f20a7c071.1736433309.git.jdenemar@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.40 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: Gj41OL7Th-QzYGqOedCzJaM0zPeD9XgXncccVEHt4K8_1736433312 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: KSKTIKB4J7IIWSVBJ5OXB5OPDJ7BPAYO X-Message-ID-Hash: KSKTIKB4J7IIWSVBJ5OXB5OPDJ7BPAYO X-MailFrom: jdenemar@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: 1736433345849116600 Content-Type: text/plain; charset="utf-8" The host-model CPU mode was described as similar to copying the host CPU definition from capabilities, which has not been the case for ages. The host-model definition from domain capabilities is used instead. Only the first sentence changed, but it required reformatting essentially the whole paragraph so I used this as an opportunity to reformat it a little bit more and split the long paragraph into several smaller ones for better readability. Signed-off-by: Jiri Denemark Reviewed-by: J=C3=A1n Tomko --- docs/formatdomain.rst | 68 ++++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 02c5361905..00acf7aa91 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1482,38 +1482,46 @@ In case no restrictions need to be put on CPU model= and its features, a simpler presented to the guest. This is the default when no ``mode`` attribu= te is specified. This mode makes it so that a persistent guest will see th= e same hardware no matter what host the guest is booted on. + ``host-model`` - The ``host-model`` mode is essentially a shortcut to copying host CPU - definition from capabilities XML into domain XML. Since the CPU defi= nition - is copied just before starting a domain, exactly the same XML can be= used - on different hosts while still providing the best guest CPU each host - supports. The ``match`` attribute can't be used in this mode. Specif= ying - CPU model is not supported either, but ``model``'s ``fallback`` attr= ibute - may still be used. Using the ``feature`` element, specific flags may= be - enabled or disabled specifically in addition to the host model. This= may - be used to fine tune features that can be emulated. :since:`(Since 1= .1.1)` - . Libvirt does not model every aspect of each CPU so the guest CPU w= ill - not match the host CPU exactly. On the other hand, the ABI provided = to the + The ``host-model`` mode is essentially a shortcut to copying host-mo= del + CPU definition from `domain capabilities XML + `__ into domain XML. Since = the + CPU definition is copied just before starting a domain, exactly the = same + XML can be used on different hosts while still providing the best gu= est + CPU each host supports. The ``match`` attribute can't be used in this + mode. Specifying CPU model is not supported either, but ``model``'s + ``fallback`` attribute may still be used. Using the ``feature`` elem= ent, + specific flags may be enabled or disabled specifically in addition t= o the + host model. This may be used to fine tune features that can be emula= ted. + :since:`(Since 1.1.1)` + + Libvirt does not model every aspect of each CPU so the guest CPU wil= l not + match the host CPU exactly. On the other hand, the ABI provided to t= he guest is reproducible. During migration, complete CPU model definiti= on is - transferred to the destination host so the migrated guest will see e= xactly - the same CPU model for the running instance of the guest, even if the - destination host contains more capable CPUs or newer kernel; but shu= tting - down and restarting the guest may present different hardware to the = guest - according to the capabilities of the new host. Prior to libvirt 3.2.= 0 and - QEMU 2.9.0 detection of the host CPU model via QEMU is not supported= . Thus - the CPU configuration created using ``host-model`` may not work as - expected. :since:`Since 3.2.0 and QEMU 2.9.0` this mode works the wa= y it - was designed and it is indicated by the ``fallback`` attribute set to - ``forbid`` in the host-model CPU definition advertised in `domain - capabilities XML `__. When - ``fallback`` attribute is set to ``allow`` in the domain capabilities - XML, it is recommended to use ``custom`` mode with just the CPU model - from the host capabilities XML. :since:`Since 1.2.11` PowerISA allows - processors to run VMs in binary compatibility mode supporting an old= er - version of ISA. Libvirt on PowerPC architecture uses the ``host-mod= el`` - to signify a guest mode CPU running in binary compatibility mode. - Example: When a user needs a power7 VM to run in compatibility mode = on a - Power8 host, this can be described in XML as follows : + transferred to the destination host so the migrated guest will see + exactly the same CPU model for the running instance of the guest, ev= en if + the destination host contains more capable CPUs or newer kernel; but + shutting down and restarting the guest may present different hardwar= e to + the guest according to the capabilities of the new host. + + Prior to libvirt 3.2.0 and QEMU 2.9.0 detection of the host CPU mode= l via + QEMU is not supported. Thus the CPU configuration created using + ``host-model`` may not work as expected. :since:`Since 3.2.0 and QEMU + 2.9.0` this mode works the way it was designed and it is indicated b= y the + ``fallback`` attribute set to ``forbid`` in the host-model CPU defin= ition + advertised in `domain capabilities XML + `__. When ``fallback`` attr= ibute + is set to ``allow`` in the domain capabilities XML, it is recommende= d to + use ``custom`` mode with just the CPU model from the host capabiliti= es + XML. + + :since:`Since 1.2.11` PowerISA allows processors to run VMs in binary + compatibility mode supporting an older version of ISA. Libvirt on + PowerPC architecture uses the ``host-model`` to signify a guest mode= CPU + running in binary compatibility mode. Example: When a user needs a p= ower7 + VM to run in compatibility mode on a Power8 host, this can be descri= bed + in XML as follows: =20 :: =20 --=20 2.47.1