F: target/mips/
F: default-configs/*mips*
F: disas/*mips*
+F: docs/system/cpu-models-mips.texi
F: hw/intc/mips_gic.c
F: hw/mips/
F: hw/misc/mips_*
F: tests/tcg/x86_64/
F: hw/i386/
F: disas/i386.c
-F: docs/qemu-cpu-models.texi
+F: docs/system/cpu-models-x86.texi
T: git https://github.com/ehabkost/qemu.git x86-next
Xtensa TCG CPUs
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
-DOCS+=docs/qemu-cpu-models.7
+DOCS+=docs/system/qemu-cpu-models.7
DOCS+=$(MANUAL_BUILDDIR)/index.html
ifdef CONFIG_VIRTFS
DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
- rm -f docs/qemu-cpu-models.7
+ rm -f docs/system/qemu-cpu-models.7
rm -rf .doctrees
$(call clean-manual,devel)
$(call clean-manual,interop)
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
- $(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
+ $(INSTALL_DATA) docs/system/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
ifeq ($(CONFIG_TOOLS),y)
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
qemu.1: qemu-option-trace.texi
-docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
+docs/system/qemu-cpu-models.7: docs/system/qemu-cpu-models.texi docs/system/cpu-models-x86.texi docs/system/cpu-models-mips.texi
html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
qemu-tech.texi qemu-option-trace.texi \
qemu-deprecated.texi qemu-monitor.texi \
qemu-monitor-info.texi \
- docs/qemu-cpu-models.texi docs/security.texi
+ docs/system/cpu-models-x86.texi docs/system/cpu-models-mips.texi \
+ docs/security.texi
docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
+++ /dev/null
-@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
--- /dev/null
+@node recommendations_cpu_models_MIPS
+@section 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
+@subsection 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
+@subsection 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
+@subsection 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
+@subsection 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
--- /dev/null
+@node cpu_models_x86
+@section Recommendations for KVM CPU model configuration on x86 hosts
+
+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.
+
+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
+* cpu_model_syntax_apps:: Syntax for configuring CPU models
+@end menu
+
+@node preferred_cpu_models_intel_x86
+@subsection 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
+@subsection 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
+@subsection 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
+@subsection 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
+@subsection 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
+@subsection 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 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.
+
+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
+
+
+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
--- /dev/null
+@c man begin SYNOPSIS
+QEMU / KVM CPU model configuration
+@c man end
+
+@set qemu_system_x86 qemu-system-x86_64
+
+@c man begin DESCRIPTION
+
+@include cpu-models-x86.texi
+@include cpu-models-mips.texi
+
+@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
* pcsys_keys:: Keys in the graphical frontends
* mux_keys:: Keys in the character backend multiplexer
* pcsys_monitor:: QEMU Monitor
-* cpu_models:: CPU models
+* cpu_models_x86:: Supported CPU model configurations on x86 hosts
* disk_images:: Disk Images
* pcsys_network:: Network emulation
* pcsys_other_devs:: Other Devices
argument. You can use register names to get the value of specifics
CPU registers by prefixing them with @emph{$}.
-@node cpu_models
-@section CPU models
-
-@include docs/qemu-cpu-models.texi
+@include docs/system/cpu-models-x86.texi
@node disk_images
@section Disk Images
@cindex system emulation (MIPS)
@menu
+* recommendations_cpu_models_MIPS:: Supported CPU model configurations on MIPS hosts
* nanoMIPS System emulator ::
@end menu
MIPSnet network emulation
@end itemize
+@lowersections
+@include docs/system/cpu-models-mips.texi
+@raisesections
+
@node nanoMIPS System emulator
@subsection nanoMIPS System emulator
@cindex system emulation (nanoMIPS)
projects / qemu.git / commitdiff