diff options
| -rw-r--r-- | MAINTAINERS | 2 | ||||
| -rw-r--r-- | Makefile | 8 | ||||
| -rw-r--r-- | docs/system/conf.py | 6 | ||||
| -rw-r--r-- | docs/system/cpu-models-mips.rst.inc | 105 | ||||
| -rw-r--r-- | docs/system/cpu-models-x86.rst.inc | 365 | ||||
| -rw-r--r-- | docs/system/qemu-cpu-models.rst | 20 | ||||
| -rw-r--r-- | docs/system/qemu-cpu-models.texi | 28 |
7 files changed, 500 insertions, 34 deletions
diff --git a/MAINTAINERS b/MAINTAINERS index 190a77be42..752d45d805 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -216,6 +216,7 @@ F: target/mips/ F: default-configs/*mips* F: disas/*mips* F: docs/system/cpu-models-mips.texi +F: docs/system/cpu-models-mips.rst.inc F: hw/intc/mips_gic.c F: hw/mips/ F: hw/misc/mips_* @@ -321,6 +322,7 @@ F: tests/tcg/x86_64/ F: hw/i386/ F: disas/i386.c F: docs/system/cpu-models-x86.texi +F: docs/system/cpu-models-x86.rst.inc T: git https://github.com/ehabkost/qemu.git x86-next Xtensa TCG CPUs @@ -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/system/qemu-cpu-models.7 +DOCS+=$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 DOCS+=$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1 @@ -780,7 +780,6 @@ 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/system/qemu-cpu-models.7 rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -861,7 +860,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/system/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/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" @@ -1083,7 +1082,7 @@ $(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user) $(call define-manpage-rule,interop,qemu-ga.8) -$(call define-manpage-rule,system,qemu-block-drivers.7) +$(call define-manpage-rule,system,qemu-block-drivers.7 qemu-cpu-models.7) $(call define-manpage-rule,tools,\ qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\ @@ -1112,7 +1111,6 @@ 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: docs/system/qemu-option-trace.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 diff --git a/docs/system/conf.py b/docs/system/conf.py index 7ca115f5e0..23cab3fb36 100644 --- a/docs/system/conf.py +++ b/docs/system/conf.py @@ -13,10 +13,14 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) # This slightly misuses the 'description', but is the best way to get # the manual title to appear in the sidebar. html_theme_options['description'] = u'System Emulation User''s Guide' + # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ('qemu-block-drivers', 'qemu-block-drivers', u'QEMU block drivers reference', - ['Fabrice Bellard and the QEMU Project developers'], 7) + ['Fabrice Bellard and the QEMU Project developers'], 7), + ('qemu-cpu-models', 'qemu-cpu-models', + u'QEMU CPU Models', + ['The QEMU Project developers'], 7) ] diff --git a/docs/system/cpu-models-mips.rst.inc b/docs/system/cpu-models-mips.rst.inc new file mode 100644 index 0000000000..499b5b6fed --- /dev/null +++ b/docs/system/cpu-models-mips.rst.inc @@ -0,0 +1,105 @@ +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) + +``M14K``, ``M14Kc`` + MIPS32 Processor (M14K, 2009) + +``74Kf`` + MIPS32 Processor (74K, 2007) + +``34Kf`` + MIPS32 Processor (34K, 2006) + +``24Kc``, ``24KEc``, ``24Kf`` + MIPS32 Processor (24K, 2003) + +``4Kc``, ``4Km``, ``4KEcR1``, ``4KEmR1``, ``4KEc``, ``4KEm`` + MIPS32 Processor (4K, 1999) + + +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) + +``MIPS64R2-generic``, ``5KEc``, ``5KEf`` + MIPS64 Processor (Release 2, 2002) + +``20Kc`` + MIPS64 Processor (20K, 2000 + +``5Kc``, ``5Kf`` + MIPS64 Processor (5K, 1999) + +``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 + diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc new file mode 100644 index 0000000000..cbad930c70 --- /dev/null +++ b/docs/system/cpu-models-x86.rst.inc @@ -0,0 +1,365 @@ +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. + + +Two ways to configure CPU models with QEMU / KVM +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(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. + + +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. + +``Skylake-Server``, ``Skylake-Server-IBRS`` + Intel Xeon Processor (Skylake, 2016) + +``Skylake-Client``, ``Skylake-Client-IBRS`` + Intel Core Processor (Skylake, 2015) + +``Broadwell``, ``Broadwell-IBRS``, ``Broadwell-noTSX``, ``Broadwell-noTSX-IBRS`` + Intel Core Processor (Broadwell, 2014) + +``Haswell``, ``Haswell-IBRS``, ``Haswell-noTSX``, ``Haswell-noTSX-IBRS`` + Intel Core Processor (Haswell, 2013) + +``IvyBridge``, ``IvyBridge-IBR`` + Intel Xeon E3-12xx v2 (Ivy Bridge, 2012) + +``SandyBridge``, ``SandyBridge-IBRS`` + Intel Xeon E312xx (Sandy Bridge, 2011) + +``Westmere``, ``Westmere-IBRS`` + Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010) + +``Nehalem``, ``Nehalem-IBRS`` + Intel Core i7 9xx (Nehalem Class Core i7, 2008) + +``Penryn`` + Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007) + +``Conroe`` + Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006) + + +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. + +``EPYC``, ``EPYC-IBPB`` + AMD EPYC Processor (2017) + +``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. + +``qemu32``, ``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. + +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. + +``kvm32``, ``kvm64`` + Common KVM processor (32 & 64 bit variants). + + Legacy models just for historical compatibility with ancient QEMU + versions. + +``486``, ``athlon``, ``phenom``, ``coreduo``, ``core2duo``, ``n270``, ``pentium``, ``pentium2``, ``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. + + +Syntax for configuring CPU models +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The examples below illustrate the approach to configuring the various +CPU models / features in QEMU and libvirt. + +QEMU command line +^^^^^^^^^^^^^^^^^ + +Host passthrough: + +.. parsed-literal:: + + |qemu_system| -cpu host + +Host passthrough with feature customization: + +.. parsed-literal:: + + |qemu_system| -cpu host,-vmx,... + +Named CPU models: + +.. parsed-literal:: + + |qemu_system| -cpu Westmere + +Named CPU models with feature customization: + +.. parsed-literal:: + + |qemu_system| -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> diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst new file mode 100644 index 0000000000..53d7538c47 --- /dev/null +++ b/docs/system/qemu-cpu-models.rst @@ -0,0 +1,20 @@ +:orphan: + +QEMU / KVM CPU model configuration +================================== + +Synopsis +'''''''' + +QEMU CPU Modelling Infrastructure manual + +Description +''''''''''' + +.. include:: cpu-models-x86.rst.inc +.. include:: cpu-models-mips.rst.inc + +See also +'''''''' + +The HTML documentation of QEMU for more precise information and Linux user mode emulator invocation. diff --git a/docs/system/qemu-cpu-models.texi b/docs/system/qemu-cpu-models.texi deleted file mode 100644 index f399daf944..0000000000 --- a/docs/system/qemu-cpu-models.texi +++ /dev/null @@ -1,28 +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 - -@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 |