From nobody Fri Dec 19 18:48:11 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=canonical.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1751556354937592.1204781044538; Thu, 3 Jul 2025 08:25:54 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id BC9DF12E4; Thu, 3 Jul 2025 11:25:53 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id DCA38125A; Thu, 3 Jul 2025 11:25:07 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 6E2591258; Thu, 3 Jul 2025 11:25:01 -0400 (EDT) Received: from smtp-relay-canonical-1.canonical.com (smtp-relay-canonical-1.canonical.com [185.125.188.121]) (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 BBAB4DEE for ; Thu, 3 Jul 2025 11:25:00 -0400 (EDT) Received: from pchector.. (unknown [27.67.179.22]) (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 smtp-relay-canonical-1.canonical.com (Postfix) with ESMTPSA id 38E48405C9 for ; Thu, 3 Jul 2025 15:24:58 +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=-3.1 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, 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=canonical.com; s=20210705; t=1751556300; bh=piUMySbCw+yHeA4AN1wZkdaeWfU3iCPjdq4L/GgyG2s=; h=From:To:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=rFIMpesCpSnHYq4PdivKaFt8cqs2pSQurcepuOOOQwkRlYqckVjpu/Wd8yA3QD+U2 pqt0xUrS9dZB25e69FPfdLVZT7aQu/bRzA/2OMZwo6sj5R0BjE4H/QnlrFHULdRa/h BvehfKS8vKqEP30lyvb4e/VxBwPLetgvhcse+KRMle23mHzb/6gdhaLWJ83YRucI+0 hXujNbDa4Xgi6L2fZJvDY/D/LO9EcGjxmtT9TJguvjmCPEsyJ4sjtd7xrCzK1eCI3G XxSsvFq0emHQjeWavuJ4PSN+I/2UJvS/LcDRLiSqlROjOTXF1p5Khe4udwB76yTFPv SAotauOqD4o0A== From: Hector CAO To: devel@lists.libvirt.org Subject: [PATCH 1/1] docs : add doc on cpu model and features Date: Thu, 3 Jul 2025 17:24:54 +0200 Message-Id: <20250703152454.23205-2-hector.cao@canonical.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250703152454.23205-1-hector.cao@canonical.com> References: <20250703152454.23205-1-hector.cao@canonical.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Message-ID-Hash: UI53CE7CFRVHZUY5A5HHSR6HFHXFGRSA X-Message-ID-Hash: UI53CE7CFRVHZUY5A5HHSR6HFHXFGRSA X-MailFrom: hector.cao@canonical.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 (Computed bodyhash is different from the expected one) X-ZM-MESSAGEID: 1751556357063116600 Content-Type: text/plain; charset="utf-8" From: Hector Cao Add documentation on the way libvirt displays the Host CPU model and capabilities (features). There is an implicit expection from users to get the CPU model name matching the CPU model they are running on, however, this does not happen most of the time. As a consequence, having a documentation is useful both for users to align their expectation and for us to point to a place where the situation is clearly explained. Signed-off-by: Hector Cao --- docs/formatcaps.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst index 7e525487e7..bb2284471c 100644 --- a/docs/formatcaps.rst +++ b/docs/formatcaps.rst @@ -371,3 +371,46 @@ capabilities enabled in the chip and BIOS you will see: =20 + +Host CPU model and features +~~~~~~~~~~~~~~~~~ + +As described in the (`Host capabilities`_) section, libvirt exposes to use= rs the list of Host CPU features. Libvirt has a special way to expose this = list: Instead of providing the full - and thereby often very long - set of = features, libvirt specifies a CPU model name as baseline and additional fea= tures on top of it. + +Example: + +:: + + + + + 7b55704c-29f4-11b2-a85c-9dc6ff50623f + + x86_64 + Skylake-Client-noTSX-IBRS + Intel + ... + + + + + + ... + +The ideal case would be that the baseline CPU model definition matches exa= ctly the CPU present in the system and no additional feature is needed to e= xpress the capabilities of the CPU. For example, if you are running on a Se= rver CPU you bought as ``Icelake`` type, the returned CPU model name could = be ``Icelake-Server``. However, this ideal situation rarely happens, for tw= o main reasons: + +- Manufacturers do not ship one (=3D1) type of CPU under a given name, the= re are various different SKUs with different features under the same name. = Yet it is not practical to have a database listing all of those variants. I= nstead Libvirt only has a list of a baseline CPU model names - roughly one = per generation - in ``/usr/share/libvirt/cpu_map/``. + +- Some features might be in the hardware, but unavailable for various reas= ons (BIOS and kernel configuration, disabled for security, ...). One typica= l example where this situation happens is related to the TSX mitigation [1]= . As a mitigation to the TAA side channel attack, the Linux kernel disables= by default TSX and its 2 features, ``rtm`` and ``hle``. Since many Linux d= istributions keep this safer default behavior these 2 features appear as di= sabled. + + +It chooses the named baseline model that shares the greatest number of fea= tures (CPUID bits and MSR features) with the actual CPU present in the mach= ine and then lists the remaining named features as differences to that know= n name. +As a consequence, the list of detected features is rarely a perfect match = to a baseline model name. +Sometimes that just means that you'll get the right name, but still a long= list of features enabled or disabled on top of it. +At other times it might even lead to a different named baseline model, usu= ally an older CPU generation, being closer to the features libvirt finds in= the CPU present in the system. +In that cases it is closer to express the capabilities via an older name e= .g. ``Broadwell`` plus some features than calling it ``Icelake`` with many = more features disabled. +Due to all that Libvirt might sometimes display the an unexpected CPU mode= l name, but that is fine - the purpose is not to confirm what generation-br= anding the chip was sold by, but instead the shortest set of named baseline= model +/- features to express its capabilities. + +Some effort has been done to address these situations (like ``-noTSX`` var= iants are added to cover the missing TSX features mentioned above) and offe= r users the ability to more often see the CPU model name they expect, but t= his can never be fully complete. Therefore users *should not* expect to hav= e the reported CPU model name to have any implications other than that of a= named baseline to build the complete available feature set of the Host CPU. + +[1] https://docs.kernel.org/arch/x86/tsx_async_abort.html --=20 2.43.0