Re: [PATCH v3 04/33] qemu-doc: split CPU models doc between MIPS and x86 parts

["Alex Bennée" <alex.bennee@linaro.org>]

Peter Maydell <peter.maydell@linaro.org> writes:

> From: Paolo Bonzini <pbonzini@redhat.com>
>
> 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.

We really need to flesh that out one day - it's not like ARM hasn't got
it's own tweaks.

>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> Message-id: 20200226113034.6741-5-pbonzini@redhat.com
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  Makefile                                      |  11 +-
>  MAINTAINERS                                   |   3 +-
>  docs/system/cpu-models-mips.texi              | 157 +++++++++++++
>  .../cpu-models-x86.texi}                      | 221 ++----------------
>  docs/system/qemu-cpu-models.texi              |  28 +++

I wonder if there is something that should go to docs/core? AFAICT the
CPU modelling covers two things:

  - system KVM modelling which deals with feature bits and presenting a
    common base for the purposes of migration

  - TCG modelling which covers what CPUs we can emulate which affects
    both linux-user and system emulation

Anyway we can "fix it in post" as they say in the movies ;-)

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

>  qemu-doc.texi                                 |  12 +-
>  6 files changed, 213 insertions(+), 219 deletions(-)
>  create mode 100644 docs/system/cpu-models-mips.texi
>  rename docs/{qemu-cpu-models.texi => system/cpu-models-x86.texi} (71%)
>  create mode 100644 docs/system/qemu-cpu-models.texi
>
> diff --git a/Makefile b/Makefile
> index faa0ffa05b0..f75a7b51938 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/MAINTAINERS b/MAINTAINERS
> index b66c46dcb9f..8c6d8f533ce 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/docs/system/cpu-models-mips.texi b/docs/system/cpu-models-mips.texi
> new file mode 100644
> index 00000000000..6a0370cb693
> --- /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 f88a1def0d0..0cd64b0522e 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 00000000000..f399daf9448
> --- /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 e555dea4ef6..617a701b678 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)


-- 
Alex Bennée