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/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/qemu-cpu-models.texi b/docs/system/cpu-models-x86.texi similarity index 71% rename from docs/qemu-cpu-models.texi rename to docs/system/cpu-models-x86.texi index f88a1def0d..0cd64b0522 100644 --- a/docs/qemu-cpu-models.texi +++ b/docs/system/cpu-models-x86.texi @@ -1,16 +1,5 @@ -@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 +@node cpu_models_x86 +@section Recommendations for KVM CPU model configuration on x86 hosts QEMU / KVM virtualization supports two ways to configure CPU models @@ -45,9 +34,6 @@ 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 @@ -60,10 +46,11 @@ enabling live migration between hosts with heterogeneous CPU models. * 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 -@subsubsection Preferred CPU models for Intel x86 hosts +@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 @@ -136,7 +123,7 @@ 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 +@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 @@ -218,7 +205,7 @@ can be used for guest CPUs. @node preferred_cpu_models_amd_x86 -@subsubsection Preferred CPU models for AMD x86 hosts +@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 @@ -260,7 +247,7 @@ AMD Opteron 240 (Gen 1 Class Opteron, 2004) @end table @node important_cpu_features_amd_x86 -@subsubsection Important CPU features for AMD x86 hosts +@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 @@ -349,7 +336,7 @@ Note that not all CPU hardware will support this feature. @node default_cpu_models_x86 -@subsubsection Default x86 CPU models +@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 @@ -372,7 +359,7 @@ qemu64 is used for x86_64 guests and qemu32 is used for i686 guests, when no @node other_non_recommended_cpu_models_x86 -@subsubsection Other non-recommended x86 CPUs +@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 @@ -403,177 +390,13 @@ 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 +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 +QEMU command line: @table @option @@ -603,8 +426,8 @@ With feature customization: @end table -@node cpu_model_syntax_libvirt -@subsubsection Libvirt guest XML + +Libvirt guest XML: @table @option @@ -657,21 +480,3 @@ With feature customization: @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/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)