docs/system: Convert qemu-cpu-models.texi to rST

This doc was originally written by Daniel P. Berrangé
<berrange@redhat.com>, introduced via commit[1]: 2544e9e (docs: add
guidance on configuring CPU models for x86, 2018-06-27).

In this patch:

  - 1-1 conversion of Texinfo to rST, besides a couple of minor
    tweaks that are too trivial to mention.   (Thanks to Stephen
    Finucane on IRC for the suggestion to use rST "definition lists"
    instead of bullets in some places.)

    Further modifications will be done via a separate patch.

  - rST and related infra changes: manual page generation, Makefile
    fixes, clean up references to qemu-cpu-models.texi, update year in
    the copyright notice, etc.

[1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa

As part of the conversion, we use a more generic 'author' attribution
for the manpage than we previously had, as agreed with the original
author Dan Berrange.

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200228153619.9906-16-peter.maydell@linaro.org
Message-id: 20200226113034.6741-15-pbonzini@redhat.com
[Move macros to defs.rst.inc, split in x86 and MIPS parts,
 make qemu-cpu-models.rst a standalone document. - Paolo]
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
[PMM: Move defs.rst.inc setup to its own commit;
 fix minor issues with MAINTAINERS file updates;
 drop copyright date change; keep capitalization of
 "QEMU Project developers" consistent with other uses;
 minor Makefile fixups]
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

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

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/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

docs/system/conf.py

@@ -13,10 +13,14 @@
 # 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)
 ]

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
+