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

[Peter Maydell]

From: Paolo Bonzini <address@hidden>

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 <address@hidden>
Message-id: address@hidden
Reviewed-by: Peter Maydell <address@hidden>
Signed-off-by: Peter Maydell <address@hidden>
---
 Makefile                                      |  11 +-
 MAINTAINERS                                   |   3 +-
 docs/system/cpu-models-mips.texi              | 157 +++++++++++++
 .../cpu-models-x86.texi}                      | 221 ++----------------
 docs/system/qemu-cpu-models.texi              |  28 +++
 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)
-- 
2.20.1