[PATCH v2 1/2] docs: Convert qemu-cpu-models.texi to rST

[Kashyap Chamarthy]

This doc was originally written by Daniel P. Berrangé
<address@hidden>, introduced via commit[1]: 2544e9e4aa (docs: add
guidance on configuring CPU models for x86, 2018-06-27).

This is a 1-1 conversion of Texinfo to rST, besides a couple of minor
non-content tweaks that are too trivial to spell out.  Further
modifications will be done via a separate patch.

(Thanks to Stephen Finucane on IRC for the suggestion to use rST
"definition lists" instead of bullets in some places.)

[1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa

Signed-off-by: Kashyap Chamarthy <address@hidden>
---
 docs/qemu-cpu-models.texi       | 677 --------------------------------
 docs/system/index.rst           |   1 +
 docs/system/qemu-cpu-models.rst | 496 +++++++++++++++++++++++
 3 files changed, 497 insertions(+), 677 deletions(-)
 delete mode 100644 docs/qemu-cpu-models.texi
 create mode 100644 docs/system/qemu-cpu-models.rst

diff --git a/docs/qemu-cpu-models.texi b/docs/qemu-cpu-models.texi
deleted file mode 100644
index f88a1def0d..0000000000
--- a/docs/qemu-cpu-models.texi
+++ /dev/null
@@ -1,677 +0,0 @@
-@c man begin SYNOPSIS
-QEMU / KVM CPU model configuration
-@c man end
-
-@set qemu_system_x86 qemu-system-x86_64
-
-@c man begin DESCRIPTION
-
-@menu
-* recommendations_cpu_models_x86::  Recommendations for KVM CPU model 
configuration on x86 hosts
-* recommendations_cpu_models_MIPS:: Supported CPU model configurations on MIPS 
hosts
-* cpu_model_syntax_apps::           Syntax for configuring CPU models
-@end menu
-
-QEMU / KVM virtualization supports two ways to configure CPU models
-
-@table @option
-
-@item Host passthrough
-
-This passes the host CPU model features, model, stepping, exactly to the
-guest. Note that KVM may filter out some host CPU model features if they
-cannot be supported with virtualization. Live migration is unsafe when
-this mode is used as libvirt / QEMU cannot guarantee a stable CPU is
-exposed to the guest across hosts. This is the recommended CPU to use,
-provided live migration is not required.
-
-@item Named model
-
-QEMU comes with a number of predefined named CPU models, that typically
-refer to specific generations of hardware released by Intel and AMD.
-These allow the guest VMs to have a degree of isolation from the host CPU,
-allowing greater flexibility in live migrating between hosts with differing
-hardware.
-@end table
-
-In both cases, it is possible to optionally add or remove individual CPU
-features, to alter what is presented to the guest by default.
-
-Libvirt supports a third way to configure CPU models known as "Host model".
-This uses the QEMU "Named model" feature, automatically picking a CPU model
-that is similar the host CPU, and then adding extra features to approximate
-the host model as closely as possible. This does not guarantee the CPU family,
-stepping, etc will precisely match the host CPU, as they would with "Host
-passthrough", but gives much of the benefit of passthrough, while making
-live migration safe.
-
-@node recommendations_cpu_models_x86
-@subsection Recommendations for KVM CPU model configuration on x86 hosts
-
-The information that follows provides recommendations for configuring
-CPU models on x86 hosts. The goals are to maximise performance, while
-protecting guest OS against various CPU hardware flaws, and optionally
-enabling live migration between hosts with heterogeneous CPU models.
-
-@menu
-* preferred_cpu_models_intel_x86::       Preferred CPU models for Intel x86 
hosts
-* important_cpu_features_intel_x86::     Important CPU features for Intel x86 
hosts
-* preferred_cpu_models_amd_x86::         Preferred CPU models for AMD x86 hosts
-* important_cpu_features_amd_x86::       Important CPU features for AMD x86 
hosts
-* default_cpu_models_x86::               Default x86 CPU models
-* other_non_recommended_cpu_models_x86:: Other non-recommended x86 CPUs
-@end menu
-
-@node preferred_cpu_models_intel_x86
-@subsubsection Preferred CPU models for Intel x86 hosts
-
-The following CPU models are preferred for use on Intel hosts. Administrators /
-applications are recommended to use the CPU model that matches the generation
-of the host CPUs in use. In a deployment with a mixture of host CPU models
-between machines, if live migration compatibility is required, use the newest
-CPU model that is compatible across all desired hosts.
-
-@table @option
-@item @code{Skylake-Server}
-@item @code{Skylake-Server-IBRS}
-
-Intel Xeon Processor (Skylake, 2016)
-
-
-@item @code{Skylake-Client}
-@item @code{Skylake-Client-IBRS}
-
-Intel Core Processor (Skylake, 2015)
-
-
-@item @code{Broadwell}
-@item @code{Broadwell-IBRS}
-@item @code{Broadwell-noTSX}
-@item @code{Broadwell-noTSX-IBRS}
-
-Intel Core Processor (Broadwell, 2014)
-
-
-@item @code{Haswell}
-@item @code{Haswell-IBRS}
-@item @code{Haswell-noTSX}
-@item @code{Haswell-noTSX-IBRS}
-
-Intel Core Processor (Haswell, 2013)
-
-
-@item @code{IvyBridge}
-@item @code{IvyBridge-IBRS}
-
-Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
-
-
-@item @code{SandyBridge}
-@item @code{SandyBridge-IBRS}
-
-Intel Xeon E312xx (Sandy Bridge, 2011)
-
-
-@item @code{Westmere}
-@item @code{Westmere-IBRS}
-
-Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
-
-
-@item @code{Nehalem}
-@item @code{Nehalem-IBRS}
-
-Intel Core i7 9xx (Nehalem Class Core i7, 2008)
-
-
-@item @code{Penryn}
-
-Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
-
-
-@item @code{Conroe}
-
-Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
-
-@end table
-
-@node important_cpu_features_intel_x86
-@subsubsection Important CPU features for Intel x86 hosts
-
-The following are important CPU features that should be used on Intel x86
-hosts, when available in the host CPU. Some of them require explicit
-configuration to enable, as they are not included by default in some, or all,
-of the named CPU models listed above. In general all of these features are
-included if using "Host passthrough" or "Host model".
-
-
-@table @option
-
-@item @code{pcid}
-
-Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix
-
-Included by default in Haswell, Broadwell & Skylake Intel CPU models.
-
-Should be explicitly turned on for Westmere, SandyBridge, and IvyBridge
-Intel CPU models. Note that some desktop/mobile Westmere CPUs cannot
-support this feature.
-
-
-@item @code{spec-ctrl}
-
-Required to enable the Spectre v2 (CVE-2017-5715) fix.
-
-Included by default in Intel CPU models with -IBRS suffix.
-
-Must be explicitly turned on for Intel CPU models without -IBRS suffix.
-
-Requires the host CPU microcode to support this feature before it
-can be used for guest CPUs.
-
-
-@item @code{stibp}
-
-Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
-operating systems.
-
-Must be explicitly turned on for all Intel CPU models.
-
-Requires the host CPU microcode to support this feature before it
-can be used for guest CPUs.
-
-
-@item @code{ssbd}
-
-Required to enable the CVE-2018-3639 fix
-
-Not included by default in any Intel CPU model.
-
-Must be explicitly turned on for all Intel CPU models.
-
-Requires the host CPU microcode to support this feature before it
-can be used for guest CPUs.
-
-
-@item @code{pdpe1gb}
-
-Recommended to allow guest OS to use 1GB size pages
-
-Not included by default in any Intel CPU model.
-
-Should be explicitly turned on for all Intel CPU models.
-
-Note that not all CPU hardware will support this feature.
-
-@item @code{md-clear}
-
-Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127, CVE-2018-12130,
-CVE-2019-11091) fixes.
-
-Not included by default in any Intel CPU model.
-
-Must be explicitly turned on for all Intel CPU models.
-
-Requires the host CPU microcode to support this feature before it
-can be used for guest CPUs.
-@end table
-
-
-@node preferred_cpu_models_amd_x86
-@subsubsection Preferred CPU models for AMD x86 hosts
-
-The following CPU models are preferred for use on Intel hosts. Administrators /
-applications are recommended to use the CPU model that matches the generation
-of the host CPUs in use. In a deployment with a mixture of host CPU models
-between machines, if live migration compatibility is required, use the newest
-CPU model that is compatible across all desired hosts.
-
-@table @option
-
-@item @code{EPYC}
-@item @code{EPYC-IBPB}
-
-AMD EPYC Processor (2017)
-
-
-@item @code{Opteron_G5}
-
-AMD Opteron 63xx class CPU (2012)
-
-
-@item @code{Opteron_G4}
-
-AMD Opteron 62xx class CPU (2011)
-
-
-@item @code{Opteron_G3}
-
-AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
-
-
-@item @code{Opteron_G2}
-
-AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
-
-
-@item @code{Opteron_G1}
-
-AMD Opteron 240 (Gen 1 Class Opteron, 2004)
-@end table
-
-@node important_cpu_features_amd_x86
-@subsubsection Important CPU features for AMD x86 hosts
-
-The following are important CPU features that should be used on AMD x86
-hosts, when available in the host CPU. Some of them require explicit
-configuration to enable, as they are not included by default in some, or all,
-of the named CPU models listed above. In general all of these features are
-included if using "Host passthrough" or "Host model".
-
-
-@table @option
-
-@item @code{ibpb}
-
-Required to enable the Spectre v2 (CVE-2017-5715) fix.
-
-Included by default in AMD CPU models with -IBPB suffix.
-
-Must be explicitly turned on for AMD CPU models without -IBPB suffix.
-
-Requires the host CPU microcode to support this feature before it
-can be used for guest CPUs.
-
-
-@item @code{stibp}
-
-Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
-operating systems.
-
-Must be explicitly turned on for all AMD CPU models.
-
-Requires the host CPU microcode to support this feature before it
-can be used for guest CPUs.
-
-
-@item @code{virt-ssbd}
-
-Required to enable the CVE-2018-3639 fix
-
-Not included by default in any AMD CPU model.
-
-Must be explicitly turned on for all AMD CPU models.
-
-This should be provided to guests, even if amd-ssbd is also
-provided, for maximum guest compatibility.
-
-Note for some QEMU / libvirt versions, this must be force enabled
-when when using "Host model", because this is a virtual feature
-that doesn't exist in the physical host CPUs.
-
-
-@item @code{amd-ssbd}
-
-Required to enable the CVE-2018-3639 fix
-
-Not included by default in any AMD CPU model.
-
-Must be explicitly turned on for all AMD CPU models.
-
-This provides higher performance than virt-ssbd so should be
-exposed to guests whenever available in the host. virt-ssbd
-should none the less also be exposed for maximum guest
-compatibility as some kernels only know about virt-ssbd.
-
-
-@item @code{amd-no-ssb}
-
-Recommended to indicate the host is not vulnerable CVE-2018-3639
-
-Not included by default in any AMD CPU model.
-
-Future hardware generations of CPU will not be vulnerable to
-CVE-2018-3639, and thus the guest should be told not to enable
-its mitigations, by exposing amd-no-ssb. This is mutually
-exclusive with virt-ssbd and amd-ssbd.
-
-
-@item @code{pdpe1gb}
-
-Recommended to allow guest OS to use 1GB size pages
-
-Not included by default in any AMD CPU model.
-
-Should be explicitly turned on for all AMD CPU models.
-
-Note that not all CPU hardware will support this feature.
-@end table
-
-
-@node default_cpu_models_x86
-@subsubsection Default x86 CPU models
-
-The default QEMU CPU models are designed such that they can run on all hosts.
-If an application does not wish to do perform any host compatibility checks
-before launching guests, the default is guaranteed to work.
-
-The default CPU models will, however, leave the guest OS vulnerable to various
-CPU hardware flaws, so their use is strongly discouraged. Applications should
-follow the earlier guidance to setup a better CPU configuration, with host
-passthrough recommended if live migration is not needed.
-
-@table @option
-@item @code{qemu32}
-@item @code{qemu64}
-
-QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
-
-qemu64 is used for x86_64 guests and qemu32 is used for i686 guests, when no
--cpu argument is given to QEMU, or no <cpu> is provided in libvirt XML.
-@end table
-
-
-@node other_non_recommended_cpu_models_x86
-@subsubsection Other non-recommended x86 CPUs
-
-The following CPUs models are compatible with most AMD and Intel x86 hosts, but
-their usage is discouraged, as they expose a very limited featureset, which
-prevents guests having optimal performance.
-
-@table @option
-
-@item @code{kvm32}
-@item @code{kvm64}
-
-Common KVM processor (32 & 64 bit variants)
-
-Legacy models just for historical compatibility with ancient QEMU versions.
-
-
-@item @code{486}
-@item @code{athlon}
-@item @code{phenom}
-@item @code{coreduo}
-@item @code{core2duo}
-@item @code{n270}
-@item @code{pentium}
-@item @code{pentium2}
-@item @code{pentium3}
-
-Various very old x86 CPU models, mostly predating the introduction of
-hardware assisted virtualization, that should thus not be required for
-running virtual machines.
-@end table
-
-@node recommendations_cpu_models_MIPS
-@subsection Supported CPU model configurations on MIPS hosts
-
-QEMU supports variety of MIPS CPU models:
-
-@menu
-* cpu_models_MIPS32::               Supported CPU models for MIPS32 hosts
-* cpu_models_MIPS64::               Supported CPU models for MIPS64 hosts
-* cpu_models_nanoMIPS::             Supported CPU models for nanoMIPS hosts
-* preferred_cpu_models_MIPS::       Preferred CPU models for MIPS hosts
-@end menu
-
-@node cpu_models_MIPS32
-@subsubsection Supported CPU models for MIPS32 hosts
-
-The following CPU models are supported for use on MIPS32 hosts. Administrators 
/
-applications are recommended to use the CPU model that matches the generation
-of the host CPUs in use. In a deployment with a mixture of host CPU models
-between machines, if live migration compatibility is required, use the newest
-CPU model that is compatible across all desired hosts.
-
-@table @option
-@item @code{mips32r6-generic}
-
-MIPS32 Processor (Release 6, 2015)
-
-
-@item @code{P5600}
-
-MIPS32 Processor (P5600, 2014)
-
-
-@item @code{M14K}
-@item @code{M14Kc}
-
-MIPS32 Processor (M14K, 2009)
-
-
-@item @code{74Kf}
-
-MIPS32 Processor (74K, 2007)
-
-
-@item @code{34Kf}
-
-MIPS32 Processor (34K, 2006)
-
-
-@item @code{24Kc}
-@item @code{24KEc}
-@item @code{24Kf}
-
-MIPS32 Processor (24K, 2003)
-
-
-@item @code{4Kc}
-@item @code{4Km}
-@item @code{4KEcR1}
-@item @code{4KEmR1}
-@item @code{4KEc}
-@item @code{4KEm}
-
-MIPS32 Processor (4K, 1999)
-@end table
-
-@node cpu_models_MIPS64
-@subsubsection Supported CPU models for MIPS64 hosts
-
-The following CPU models are supported for use on MIPS64 hosts. Administrators 
/
-applications are recommended to use the CPU model that matches the generation
-of the host CPUs in use. In a deployment with a mixture of host CPU models
-between machines, if live migration compatibility is required, use the newest
-CPU model that is compatible across all desired hosts.
-
-@table @option
-@item @code{I6400}
-
-MIPS64 Processor (Release 6, 2014)
-
-
-@item @code{Loongson-2F}
-
-MIPS64 Processor (Loongson 2, 2008)
-
-
-@item @code{Loongson-2E}
-
-MIPS64 Processor (Loongson 2, 2006)
-
-
-@item @code{mips64dspr2}
-
-MIPS64 Processor (Release 2, 2006)
-
-
-@item @code{MIPS64R2-generic}
-@item @code{5KEc}
-@item @code{5KEf}
-
-MIPS64 Processor (Release 2, 2002)
-
-
-@item @code{20Kc}
-
-MIPS64 Processor (20K, 2000)
-
-
-@item @code{5Kc}
-@item @code{5Kf}
-
-MIPS64 Processor (5K, 1999)
-
-
-@item @code{VR5432}
-
-MIPS64 Processor (VR, 1998)
-
-
-@item @code{R4000}
-
-MIPS64 Processor (MIPS III, 1991)
-@end table
-
-@node cpu_models_nanoMIPS
-@subsubsection Supported CPU models for nanoMIPS hosts
-
-The following CPU models are supported for use on nanoMIPS hosts. 
Administrators /
-applications are recommended to use the CPU model that matches the generation
-of the host CPUs in use. In a deployment with a mixture of host CPU models
-between machines, if live migration compatibility is required, use the newest
-CPU model that is compatible across all desired hosts.
-
-@table @option
-@item @code{I7200}
-
-MIPS I7200 (nanoMIPS, 2018)
-
-@end table
-
-@node preferred_cpu_models_MIPS
-@subsubsection Preferred CPU models for MIPS hosts
-
-The following CPU models are preferred for use on different MIPS hosts:
-
-@table @option
-@item @code{MIPS III}
-R4000
-
-@item @code{MIPS32R2}
-34Kf
-
-@item @code{MIPS64R6}
-I6400
-
-@item @code{nanoMIPS}
-I7200
-@end table
-
-@node cpu_model_syntax_apps
-@subsection Syntax for configuring CPU models
-
-The example below illustrate the approach to configuring the various
-CPU models / features in QEMU and libvirt
-
-@menu
-* cpu_model_syntax_qemu::    QEMU command line
-* cpu_model_syntax_libvirt:: Libvirt guest XML
-@end menu
-
-@node cpu_model_syntax_qemu
-@subsubsection QEMU command line
-
-@table @option
-
-@item Host passthrough
-
-@example
-   $ @value{qemu_system_x86} -cpu host
-@end example
-
-With feature customization:
-
-@example
-   $ @value{qemu_system_x86} -cpu host,-vmx,...
-@end example
-
-@item Named CPU models
-
-@example
-   $ @value{qemu_system_x86} -cpu Westmere
-@end example
-
-With feature customization:
-
-@example
-   $ @value{qemu_system_x86} -cpu Westmere,+pcid,...
-@end example
-
-@end table
-
-@node cpu_model_syntax_libvirt
-@subsubsection Libvirt guest XML
-
-@table @option
-
-@item Host passthrough
-
-@example
-   <cpu mode='host-passthrough'/>
-@end example
-
-With feature customization:
-
-@example
-   <cpu mode='host-passthrough'>
-       <feature name="vmx" policy="disable"/>
-       ...
-   </cpu>
-@end example
-
-@item Host model
-
-@example
-   <cpu mode='host-model'/>
-@end example
-
-With feature customization:
-
-@example
-   <cpu mode='host-model'>
-       <feature name="vmx" policy="disable"/>
-       ...
-   </cpu>
-@end example
-
-@item Named model
-
-@example
-   <cpu mode='custom'>
-       <model name="Westmere"/>
-   </cpu>
-@end example
-
-With feature customization:
-
-@example
-   <cpu mode='custom'>
-       <model name="Westmere"/>
-       <feature name="pcid" policy="require"/>
-       ...
-   </cpu>
-@end example
-
-@end table
-
-@c man end
-
-@ignore
-
-@setfilename qemu-cpu-models
-@settitle QEMU / KVM CPU model configuration
-
-@c man begin SEEALSO
-The HTML documentation of QEMU for more precise information and Linux
-user mode emulator invocation.
-@c man end
-
-@c man begin AUTHOR
-Daniel P. Berrange
-@c man end
-
-@end ignore
diff --git a/docs/system/index.rst b/docs/system/index.rst
index f66e6ea585..849dcd8cb8 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -15,3 +15,4 @@ Contents:
    :maxdepth: 2
 
    qemu-block-drivers
+   qemu-cpu-models
diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst
new file mode 100644
index 0000000000..2332fba1f9
--- /dev/null
+++ b/docs/system/qemu-cpu-models.rst
@@ -0,0 +1,496 @@
+QEMU / KVM CPU model configuration
+==================================
+
+QEMU / KVM virtualization supports two ways to configure CPU models:
+
+(1) **Host passthrough**
+
+    This passes the host CPU model features, model, stepping, exactly to
+    the guest. Note that KVM may filter out some host CPU model features
+    if they cannot be supported with virtualization. Live migration is
+    unsafe when this mode is used as libvirt / QEMU cannot guarantee a
+    stable CPU is exposed to the guest across hosts. This is the
+    recommended CPU to use, provided live migration is not required.
+
+(2) **Named model**
+
+    QEMU comes with a number of predefined named CPU models, that
+    typically refer to specific generations of hardware released by
+    Intel and AMD.  These allow the guest VMs to have a degree of
+    isolation from the host CPU, allowing greater flexibility in live
+    migrating between hosts with differing hardware.  @end table
+
+In both cases, it is possible to optionally add or remove individual CPU
+features, to alter what is presented to the guest by default.
+
+Libvirt supports a third way to configure CPU models known as "Host
+model".  This uses the QEMU "Named model" feature, automatically picking
+a CPU model that is similar the host CPU, and then adding extra features
+to approximate the host model as closely as possible. This does not
+guarantee the CPU family, stepping, etc will precisely match the host
+CPU, as they would with "Host passthrough", but gives much of the
+benefit of passthrough, while making live migration safe.
+
+
+Recommendations for KVM CPU model configuration on x86 hosts
+------------------------------------------------------------
+
+The information that follows provides recommendations for configuring
+CPU models on x86 hosts. The goals are to maximise performance, while
+protecting guest OS against various CPU hardware flaws, and optionally
+enabling live migration between hosts with heterogeneous CPU models.
+
+
+Preferred CPU models for Intel x86 hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following CPU models are preferred for use on Intel hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+* Intel Xeon Processor (Skylake, 2016)
+
+  * ``Skylake-Server``
+  * ``Skylake-Server-IBRS``
+
+* Intel Core Processor (Skylake, 2015)
+
+  * ``Skylake-Client``
+  * ``Skylake-Client-IBRS``
+
+* Intel Core Processor (Broadwell, 2014)
+
+  * ``Broadwell``
+  * ``Broadwell-IBRS``
+  * ``Broadwell-noTSX``
+  * ``Broadwell-noTSX-IBRS``
+
+* Intel Core Processor (Haswell, 2013)
+
+  * ``Haswell``
+  * ``Haswell-IBRS``
+  * ``Haswell-noTSX``
+  * ``Haswell-noTSX-IBRS``
+
+* Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
+
+  * ``IvyBridge``
+  * ``IvyBridge-IBR``
+
+* Intel Xeon E312xx (Sandy Bridge, 2011)
+
+  * ``SandyBridge``
+  * ``SandyBridge-IBRS``
+
+* Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
+
+  * ``Westmere``
+  * ``Westmere-IBRS``
+
+* Intel Core i7 9xx (Nehalem Class Core i7, 2008)
+
+  * ``Nehalem``
+  * ``Nehalem-IBRS``
+
+* Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
+
+  * ``Penryn``
+
+* Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
+
+  * ``Conroe``
+
+
+Important CPU features for Intel x86 hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following are important CPU features that should be used on Intel
+x86 hosts, when available in the host CPU. Some of them require explicit
+configuration to enable, as they are not included by default in some, or
+all, of the named CPU models listed above. In general all of these
+features are included if using "Host passthrough" or "Host model".
+
+``pcid``
+  Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix.
+
+  Included by default in Haswell, Broadwell & Skylake Intel CPU models.
+
+  Should be explicitly turned on for Westmere, SandyBridge, and
+  IvyBridge Intel CPU models. Note that some desktop/mobile Westmere
+  CPUs cannot support this feature.
+
+``spec-ctrl``
+  Required to enable the Spectre v2 (CVE-2017-5715) fix.
+
+  Included by default in Intel CPU models with -IBRS suffix.
+
+  Must be explicitly turned on for Intel CPU models without -IBRS
+  suffix.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``stibp``
+  Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
+  operating systems.
+
+  Must be explicitly turned on for all Intel CPU models.
+
+  Requires the host CPU microcode to support this feature before it can
+  be used for guest CPUs.
+
+``ssbd``
+  Required to enable the CVE-2018-3639 fix.
+
+  Not included by default in any Intel CPU model.
+
+  Must be explicitly turned on for all Intel CPU models.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``pdpe1gb``
+  Recommended to allow guest OS to use 1GB size pages.
+
+  Not included by default in any Intel CPU model.
+
+  Should be explicitly turned on for all Intel CPU models.
+
+  Note that not all CPU hardware will support this feature.
+
+``md-clear``
+  Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127,
+  CVE-2018-12130, CVE-2019-11091) fixes.
+
+  Not included by default in any Intel CPU model.
+
+  Must be explicitly turned on for all Intel CPU models.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+
+Preferred CPU models for AMD x86 hosts
+--------------------------------------
+
+The following CPU models are preferred for use on Intel hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+* AMD EPYC Processor (2017)
+
+  * ``EPYC``
+  * ``EPYC-IBPB``
+
+* ``Opteron_G5`` -- AMD Opteron 63xx class CPU (2012)
+
+* ``Opteron_G4`` -- AMD Opteron 62xx class CPU (2011)
+
+* ``Opteron_G3`` -- AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
+
+* ``Opteron_G2`` -- AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
+
+* ``Opteron_G1`` -- AMD Opteron 240 (Gen 1 Class Opteron, 2004)
+
+
+Important CPU features for AMD x86 hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following are important CPU features that should be used on AMD x86
+hosts, when available in the host CPU. Some of them require explicit
+configuration to enable, as they are not included by default in some, or
+all, of the named CPU models listed above. In general all of these
+features are included if using "Host passthrough" or "Host model".
+
+``ibpb``
+  Required to enable the Spectre v2 (CVE-2017-5715) fix.
+
+  Included by default in AMD CPU models with -IBPB suffix.
+
+  Must be explicitly turned on for AMD CPU models without -IBPB suffix.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``stibp``
+  Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
+  operating systems.
+
+  Must be explicitly turned on for all AMD CPU models.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``virt-ssbd``
+  Required to enable the CVE-2018-3639 fix
+
+  Not included by default in any AMD CPU model.
+
+  Must be explicitly turned on for all AMD CPU models.
+
+  This should be provided to guests, even if amd-ssbd is also provided,
+  for maximum guest compatibility.
+
+  Note for some QEMU / libvirt versions, this must be force enabled when
+  when using "Host model", because this is a virtual feature that
+  doesn't exist in the physical host CPUs.
+
+``amd-ssbd``
+  Required to enable the CVE-2018-3639 fix
+
+  Not included by default in any AMD CPU model.
+
+  Must be explicitly turned on for all AMD CPU models.
+
+  This provides higher performance than ``virt-ssbd`` so should be
+  exposed to guests whenever available in the host. ``virt-ssbd`` should
+  none the less also be exposed for maximum guest compatibility as some
+  kernels only know about ``virt-ssbd``.
+
+``amd-no-ssb``
+  Recommended to indicate the host is not vulnerable CVE-2018-3639
+
+  Not included by default in any AMD CPU model.
+
+  Future hardware generations of CPU will not be vulnerable to
+  CVE-2018-3639, and thus the guest should be told not to enable
+  its mitigations, by exposing amd-no-ssb. This is mutually
+  exclusive with virt-ssbd and amd-ssbd.
+
+``pdpe1gb``
+  Recommended to allow guest OS to use 1GB size pages
+
+  Not included by default in any AMD CPU model.
+
+  Should be explicitly turned on for all AMD CPU models.
+
+  Note that not all CPU hardware will support this feature.
+
+
+Default x86 CPU models
+----------------------
+
+The default QEMU CPU models are designed such that they can run on all
+hosts.  If an application does not wish to do perform any host
+compatibility checks before launching guests, the default is guaranteed
+to work.
+
+The default CPU models will, however, leave the guest OS vulnerable to
+various CPU hardware flaws, so their use is strongly discouraged.
+Applications should follow the earlier guidance to setup a better CPU
+configuration, with host passthrough recommended if live migration is
+not needed.
+
+* QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
+
+  * ``qemu32``
+  * ``qemu64``
+
+  ``qemu64`` is used for x86_64 guests and ``qemu32`` is used for i686
+  guests, when no ``-cpu`` argument is given to QEMU, or no ``<cpu>`` is
+  provided in libvirt XML.
+
+Other non-recommended x86 CPUs
+------------------------------
+
+The following CPUs models are compatible with most AMD and Intel x86
+hosts, but their usage is discouraged, as they expose a very limited
+featureset, which prevents guests having optimal performance.
+
+* Common KVM processor (32 & 64 bit variants):
+
+  * ``kvm32``
+  * ``kvm64``
+
+  Legacy models just for historical compatibility with ancient QEMU
+  versions.
+
+* Various very old x86 CPU models, mostly predating the introduction of
+  hardware assisted virtualization, that should thus not be required for
+  running virtual machines.
+
+  * ``486``
+  * ``athlon``
+  * ``phenom``
+  * ``coreduo``
+  * ``core2duo``
+  * ``n270``
+  * ``pentium``
+  * ``pentium2``
+  * ``pentium3``
+
+
+Supported CPU model configurations on MIPS hosts
+------------------------------------------------
+
+QEMU supports variety of MIPS CPU models:
+
+Supported CPU models for MIPS32 hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following CPU models are supported for use on MIPS32 hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+* ``mips32r6-generic`` -- MIPS32 Processor (Release 6, 2015)
+
+* ``P5600`` -- MIPS32 Processor (P5600, 2014)
+
+* MIPS32 Processor (M14K, 2009)
+
+  * ``M14K``
+  * ``M14Kc``
+
+* ``74Kf`` -- MIPS32 Processor (74K, 2007)
+
+* ``34Kf`` -- MIPS32 Processor (34K, 2006)
+
+* MIPS32 Processor (24K, 2003)
+
+  * ``24Kc``
+  * ``24KEc``
+  * ``24Kf``
+
+* MIPS32 Processor (4K, 1999)
+
+  * ``4Kc``
+  * ``4Km``
+  * ``4KEcR1``
+  * ``4KEmR1``
+  * ``4KEc``
+  * ``4KEm``
+
+
+Supported CPU models for MIPS64 hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following CPU models are supported for use on MIPS64 hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+* ``I6400`` -- MIPS64 Processor (Release 6, 2014)
+
+* ``Loongson-2F`` -- MIPS64 Processor (Loongson 2, 2008)
+
+* ``Loongson-2E`` -- MIPS64 Processor (Loongson 2, 2006)
+
+* ``mips64dspr2`` -- MIPS64 Processor (Release 2, 2006)
+
+* MIPS64 Processor (Release 2, 2002)
+
+  * ``MIPS64R2-generic``
+  * ``5KEc``
+  * ``5KEf``
+
+* ``20Kc`` -- MIPS64 Processor (20K, 2000
+
+* MIPS64 Processor (5K, 1999)
+
+  * ``5Kc``
+  * ``5Kf``
+
+* ``VR5432`` -- MIPS64 Processor (VR, 1998)
+
+* ``R4000`` -- MIPS64 Processor (MIPS III, 1991)
+
+
+Supported CPU models for nanoMIPS hosts
+---------------------------------------
+
+The following CPU models are supported for use on nanoMIPS hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+* ``I7200`` -- MIPS I7200 (nanoMIPS, 2018)
+
+Preferred CPU models for MIPS hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following CPU models are preferred for use on different MIPS hosts:
+
+* ``MIPS III`` -- R4000
+
+* ``MIPS32R2`` -- 34Kf
+
+* ``MIPS64R6`` -- I6400
+
+* ``nanoMIPS`` -- I7200
+
+Syntax for configuring CPU models
+---------------------------------
+
+The example below illustrate the approach to configuring the various
+CPU models / features in QEMU and libvirt
+
+QEMU command line
+~~~~~~~~~~~~~~~~~
+
+Host passthrough::
+
+    $ qemu_system_x86 -cpu host
+
+Host passthrough with feature customization::
+
+    $ qemu_system_x86 -cpu host,-vmx,...
+
+Named CPU models::
+
+    $ qemu_system_x86 -cpu Westmere
+
+Named CPU models with feature customization::
+
+    $ qemu_system_x86 -cpu Westmere,+pcid,...
+
+Libvirt guest XML
+~~~~~~~~~~~~~~~~~
+
+Host passthrough::
+
+    <cpu mode='host-passthrough'/>
+
+Host passthrough with feature customization::
+
+    <cpu mode='host-passthrough'>
+        <feature name="vmx" policy="disable"/>
+        ...
+    </cpu>
+
+Host model::
+
+    <cpu mode='host-model'/>
+
+Host model with feature customization::
+
+    <cpu mode='host-model'>
+        <feature name="vmx" policy="disable"/>
+        ...
+    </cpu>
+
+Named model::
+
+    <cpu mode='custom'>
+        <model name="Westmere"/>
+    </cpu>
+
+Named model with feature customization::
+
+    <cpu mode='custom'>
+        <model name="Westmere"/>
+        <feature name="pcid" policy="require"/>
+        ...
+    </cpu>
-- 
2.21.0