Re: [PATCH] cpu-models-x86.rst: Tidy up a couple of things

[Kashyap Chamarthy]

On Fri, Oct 15, 2021 at 05:22:59PM +0200, Kashyap Chamarthy wrote:
> - Remove stray texinfo syntax (remnants of texinfo to rST conversion)
> - Clarify the bit about long-term stable CPU models
> 
> TODO: In a future patch, include potential examples as discussed
>       here[1].
> 
> [1] https://lists.nongnu.org/archive/html/qemu-devel/2021-10/msg03411.html
>     -- On versioned CPU models, aliases, and machine types

Ping?

I'd also appreciate if anyone can also answer the two questions I raised
in the above thread[1].

> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
> Eduardo/DanPB: I'm not 100% sure if my wording got it right; please give
> it a close reading to make sure I'm not making things worse.
> ---
>  docs/system/cpu-models-x86.rst.inc | 25 +++++++++++++++++--------
>  1 file changed, 17 insertions(+), 8 deletions(-)
> 
> diff --git a/docs/system/cpu-models-x86.rst.inc 
> b/docs/system/cpu-models-x86.rst.inc
> index 6e8be7d79b..e133753920 100644
> --- a/docs/system/cpu-models-x86.rst.inc
> +++ b/docs/system/cpu-models-x86.rst.inc
> @@ -25,7 +25,7 @@ Two ways to configure CPU models with QEMU / KVM
>      typically refer to specific generations of hardware released by
>      Intel and AMD.  These allow the guest VMs to have a degree of
>      isolation from the host CPU, allowing greater flexibility in live
> -    migrating between hosts with differing hardware.  @end table
> +    migrating between hosts with differing hardware.
>  
>  In both cases, it is possible to optionally add or remove individual CPU
>  features, to alter what is presented to the guest by default.
> @@ -47,11 +47,20 @@ defined. Traditionally most operating systems and 
> toolchains would
>  only target the original baseline ABI. It is expected that in
>  future OS and toolchains are likely to target newer ABIs. The
>  table that follows illustrates which ABI compatibility levels
> -can be satisfied by the QEMU CPU models. Note that the table only
> -lists the long term stable CPU model versions (eg Haswell-v4).
> -In addition to whats listed, there are also many CPU model
> -aliases which resolve to a different CPU model version,
> -depending on the machine type is in use.
> +can be satisfied by the QEMU CPU models. Note that the table only lists
> +the long term stable CPU model versions (e.g. Haswell-v4, Haswell-v3).
> +CPU models without a version tag will alias to a CPU model with a
> +version tag, and the alias varies depending on the machine type.  In
> +addition to what is listed, there are also many CPU model aliases which
> +resolve to a different CPU model version, depending on the machine type
> +in use.
> +
> +The versioned CPU models (e.g. ``Cascadelake-Server-v4``,
> +``Broadwell-v4``) are long-term stable.  Further, when using a versioned
> +machine type (e.g. ``pc-q35-6.0``), instead of its generic alias
> +(``q35``), the CPU models that are associated with it are also long-term
> +stable.  This is because the CPUID features in the CPU models that are
> +part of a versioned machine type do not change.
>  
>  .. _ABI compatibility levels: https://gitlab.com/x86-psABIs/x86-64-ABI/
>  
> @@ -185,8 +194,8 @@ features are included if using "Host passthrough" or 
> "Host model".
>    guest.  Instead, the host kernel uses it to populate the MDS
>    vulnerability file in ``sysfs``.
>  
> -  So it should only be enabled for VMs if the host reports @code{Not
> -  affected} in the ``/sys/devices/system/cpu/vulnerabilities/mds`` file.
> +  So it should only be enabled for VMs if the host reports ``Not
> +  affected`` in the ``/sys/devices/system/cpu/vulnerabilities/mds`` file.
>  
>  ``taa-no``
>    Recommended to inform that the guest that the host is ``not``
> -- 
> 2.31.1
> 

-- 
/kashyap