On Thu, 20 Feb 2020 at 14:20, Kashyap Chamarthy <kcham...@redhat.com> wrote:
>
> This doc was originally written by Daniel P. Berrangé
> <berra...@redhat.com>, introduced via commit[1]: 2544e9e4aa (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: for building the manual page,
> Makefile fixes, clean up references to qemu-cpu-models.texi, etc.
>
> [1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa
>
> Signed-off-by: Kashyap Chamarthy <kcham...@redhat.com>
> ---
> v2: Fix rST conversion, man page creation, Makefile changes, et al
> (thanks, Peter Maydell)
> ---
> MAINTAINERS | 2 +-
> Makefile | 10 +-
> docs/qemu-cpu-models.texi | 677 --------------------------------
> docs/system/conf.py | 3 +
> docs/system/index.rst | 1 +
> docs/system/qemu-cpu-models.rst | 514 ++++++++++++++++++++++++
> qemu-doc.texi | 5 -
> 7 files changed, 524 insertions(+), 688 deletions(-)
> delete mode 100644 docs/qemu-cpu-models.texi
> create mode 100644 docs/system/qemu-cpu-models.rst
> @@ -1056,6 +1055,8 @@ $(call define-manpage-rule,interop,\
>
> $(call define-manpage-rule,system,qemu-block-drivers.7)
>
> +$(call define-manpage-rule,system,qemu-cpu-models.7)
The new manpage should be added to the existing define-manpage-rule
invocation for the system manual: the last argument is a space
separated list of all the manpages in the manual, like this:
$(call define-manpage-rule,system,qemu-block-drivers.7 qemu-cpu-models.7)
> +
> $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
> @mkdir -p "$(MANUAL_BUILDDIR)"
> $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \
> -@c man begin AUTHOR
> -Daniel P. Berrange
> -@c man end
> diff --git a/docs/system/conf.py b/docs/system/conf.py
> index 7ca115f5e0..7cc9da9508 100644
> --- a/docs/system/conf.py
> +++ b/docs/system/conf.py
> @@ -18,5 +18,8 @@ html_theme_options['description'] = u'System Emulation
> User''s Guide'
> man_pages = [
> ('qemu-block-drivers', 'qemu-block-drivers',
> u'QEMU block drivers reference',
> + ['Fabrice Bellard and the QEMU Project developers'], 7),
> + ('qemu-cpu-models', 'qemu-cpu-models',
> + u'QEMU CPU Models',
> ['Fabrice Bellard and the QEMU Project developers'], 7)
> ]
The old manpage/documentation credits Dan as the author,
so that's what we should specify in the conf.py line,
rather than 'Fabrice and the project devs' (which we
use for qemu-block-drivers.7 because that's what the
old texi version of that file specified as the authors).
> +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.
> +
> +* Intel Xeon Processor (Skylake, 2016)
> +
> + * ``Skylake-Server``
> + * ``Skylake-Server-IBRS``
This reverses the old ordering of these lists, which consistently
had the QEMU CPU model names as the 'term' and the explanations
as the 'definition' of a definition-list. Now we have the
'explanation' first and the 'terms' second...
> +* AMD EPYC Processor (2017)
> +
> + * ``EPYC``
> + * ``EPYC-IBPB``
> +
> +* ``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)
...but here we become inconsistent, switching back to
term first and explanation second. I think the
term-first approach of the original texi makes more sense,
as we're trying to document the behaviour of the various
CPU models QEMU supports.
rST is not a fan of having multiple definition list items
sharing a definition, which is probably why you ended up with
the list approach you did, but we can do:
``Skylake-Server``, ``Skylake-Server-IBRS``
Intel Xeon Processor (Skylake, 2016)
``Skylake-Client``, ``Skylake-Client-IBRS``
Intel Core Processor (Skylake, 2015)
Or we can actually document what the difference is between
a "Skylake-Server" and a "Skylake-Server-IBRS", rather than
leaving the user to guess :-), in which case we could write
``Skylake-Server``
Intel Xeon Processor (Skylake, 2016)
``Skylake-Server-IBRS``
Like ``Skylake-Server`` but with extra magic
(or whatever the difference is...)
Regardless of how we format this, we should be consistent
in using the same format throughout the document.
thanks
-- PMM
