From: Paolo Bonzini Date: Fri, 28 Feb 2020 15:35:50 +0000 (+0000) Subject: qemu-doc: split CPU models doc between MIPS and x86 parts X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=5600d275d52aa822393edd8b52b397dfff8a499c;p=qemu.git qemu-doc: split CPU models doc between MIPS and x86 parts The MIPS CPU models end up in the middle of the PC documentation. Move them to a separate file so that they can be placed in the right section. The man page still includes both x86 and MIPS content. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell Reviewed-by: Alex Bennée Tested-by: Alex Bennée Signed-off-by: Peter Maydell Message-id: 20200228153619.9906-5-peter.maydell@linaro.org Message-id: 20200226113034.6741-5-pbonzini@redhat.com Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- diff --git a/MAINTAINERS b/MAINTAINERS index c258391cad..615615c32f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -215,6 +215,7 @@ S: Maintained 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_* @@ -319,7 +320,7 @@ F: tests/tcg/i386/ 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 diff --git a/Makefile b/Makefile index faa0ffa05b..f75a7b5193 100644 --- a/Makefile +++ b/Makefile @@ -354,7 +354,7 @@ endif 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 @@ -780,7 +780,7 @@ distclean: clean 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) @@ -861,7 +861,7 @@ ifdef CONFIG_POSIX $(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" @@ -1111,7 +1111,7 @@ docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi 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 @@ -1123,7 +1123,8 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ 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 \ 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 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 - -@end example - -With feature customization: - -@example - - - ... - -@end example - -@item Host model - -@example - -@end example - -With feature customization: - -@example - - - ... - -@end example - -@item Named model - -@example - - - -@end example - -With feature customization: - -@example - - - - ... - -@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/cpu-models-mips.texi b/docs/system/cpu-models-mips.texi new file mode 100644 index 0000000000..6a0370cb69 --- /dev/null +++ b/docs/system/cpu-models-mips.texi @@ -0,0 +1,157 @@ +@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 diff --git a/docs/system/cpu-models-x86.texi b/docs/system/cpu-models-x86.texi new file mode 100644 index 0000000000..0cd64b0522 --- /dev/null +++ b/docs/system/cpu-models-x86.texi @@ -0,0 +1,482 @@ +@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 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 + +@end example + +With feature customization: + +@example + + + ... + +@end example + +@item Host model + +@example + +@end example + +With feature customization: + +@example + + + ... + +@end example + +@item Named model + +@example + + + +@end example + +With feature customization: + +@example + + + + ... + +@end example + +@end table diff --git a/docs/system/qemu-cpu-models.texi b/docs/system/qemu-cpu-models.texi new file mode 100644 index 0000000000..f399daf944 --- /dev/null +++ b/docs/system/qemu-cpu-models.texi @@ -0,0 +1,28 @@ +@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 diff --git a/qemu-doc.texi b/qemu-doc.texi index e555dea4ef..617a701b67 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -139,7 +139,7 @@ accelerator is required to use more than one host CPU for emulation. * 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 @@ -614,10 +614,7 @@ The monitor understands integers expressions for every integer 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 @@ -1864,6 +1861,7 @@ Set the emulated machine type. The default is sun4u. @cindex system emulation (MIPS) @menu +* recommendations_cpu_models_MIPS:: Supported CPU model configurations on MIPS hosts * nanoMIPS System emulator :: @end menu @@ -1980,6 +1978,10 @@ PC style serial port 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)