[PATCH 1/1] docs : add doc on cpu model and features
From: Hector Cao <hector.cao(a)canonical.com>
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 <hector.cao(a)canonical.com>
---
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:
</guest>
</capabilities>
+
+Host CPU model and features
+~~~~~~~~~~~~~~~~~
+
+As described in the (`Host capabilities`_) section, libvirt exposes to users 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 features on top of it.
+
+Example:
+
+::
+
+ <capabilities>
+
+ <host>
+ <uuid>7b55704c-29f4-11b2-a85c-9dc6ff50623f</uuid>
+ <cpu>
+ <arch>x86_64</arch>
+ <model>Skylake-Client-noTSX-IBRS</model>
+ <vendor>Intel</vendor>
+ ...
+ <feature name='ds'/>
+ <feature name='acpi'/>
+ <feature name='ss'/>
+ <feature name='ht'/>
+ <feature name='tm'/>
+ ...
+
+The ideal case would be that the baseline CPU model definition matches exactly the CPU
present in the system and no additional feature is needed to express the capabilities of
the CPU. For example, if you are running on a Server CPU you bought as ``Icelake`` type,
the returned CPU model name could be ``Icelake-Server``. However, this ideal situation
rarely happens, for two main reasons:
+
+- Manufacturers do not ship one (=1) type of CPU under a given name, there 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. Instead 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 reasons (BIOS and
kernel configuration, disabled for security, ...). One typical 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 distributions keep this safer default behavior these 2 features
appear as disabled.
+
+
+It chooses the named baseline model that shares the greatest number of features (CPUID
bits and MSR features) with the actual CPU present in the machine and then lists the
remaining named features as differences to that known 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, usually 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 model name, but
that is fine - the purpose is not to confirm what generation-branding 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`` variants are added
to cover the missing TSX features mentioned above) and offer users the ability to more
often see the CPU model name they expect, but this can never be fully complete. Therefore
users *should not* expect to have 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
--
2.43.0