Re: [PATCH RFC 1/4] docs: add a table showing x86-64 ABI compatibility levels

[David Edmondson <dme@dme.org>]

On Monday, 2021-02-01 at 15:36:03 GMT, Daniel P. Berrangé wrote:

> It is useful to know which CPUs satisfy each x86-64 ABI
> compatibility level, when dealing with guest OS that require
> something newer than the baseline ABI.
>
> These ABI levels are defined in:
>
>   https://gitlab.com/x86-psABIs/x86-64-ABI/
>
> and supported by GCC, CLang, GLibC and more.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  MAINTAINERS                        |   2 +-
>  docs/system/cpu-models-x86-abi.csv | 121 +++++++++++++++++++++++++++++
>  docs/system/cpu-models-x86.rst.inc |  18 +++++
>  3 files changed, 140 insertions(+), 1 deletion(-)
>  create mode 100644 docs/system/cpu-models-x86-abi.csv
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index fbb228ef2b..bb8d60c458 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -344,7 +344,7 @@ F: tests/tcg/i386/
>  F: tests/tcg/x86_64/
>  F: hw/i386/
>  F: disas/i386.c
> -F: docs/system/cpu-models-x86.rst.inc
> +F: docs/system/cpu-models-x86*
>  T: git https://gitlab.com/ehabkost/qemu.git x86-next
>  
>  Xtensa TCG CPUs
> diff --git a/docs/system/cpu-models-x86-abi.csv b/docs/system/cpu-models-x86-abi.csv
> new file mode 100644
> index 0000000000..4565e6a535
> --- /dev/null
> +++ b/docs/system/cpu-models-x86-abi.csv
> @@ -0,0 +1,121 @@
> +Model,baseline,v2,v3,v4
> +486,,,,
> +486-v1,,,,
> +Broadwell,✅,✅,✅,
> +Broadwell-IBRS,✅,✅,✅,
> +Broadwell-noTSX,✅,✅,✅,
> +Broadwell-noTSX-IBRS,✅,✅,✅,

Would it be useful to add an explicit negative mark (✘) in the slots
where the CPU does not satisfy the requirement? It makes reading the
table a little easier (my opinion, of course).

> +Broadwell-v1,✅,✅,✅,
> +Broadwell-v2,✅,✅,✅,
> +Broadwell-v3,✅,✅,✅,
> +Broadwell-v4,✅,✅,✅,
> +Cascadelake-Server,✅,✅,✅,✅
> +Cascadelake-Server-noTSX,✅,✅,✅,✅
> +Cascadelake-Server-v1,✅,✅,✅,✅
> +Cascadelake-Server-v2,✅,✅,✅,✅
> +Cascadelake-Server-v3,✅,✅,✅,✅
> +Cascadelake-Server-v4,✅,✅,✅,✅
> +Conroe,✅,,,
> +Conroe-v1,✅,,,
> +Cooperlake,✅,✅,✅,✅
> +Cooperlake-v1,✅,✅,✅,✅
> +Denverton,✅,✅,,
> +Denverton-v1,✅,✅,,
> +Denverton-v2,✅,✅,,
> +Dhyana,✅,✅,✅,
> +Dhyana-v1,✅,✅,✅,
> +EPYC,✅,✅,✅,
> +EPYC-IBPB,✅,✅,✅,
> +EPYC-Rome,✅,✅,✅,
> +EPYC-Rome-v1,✅,✅,✅,
> +EPYC-v1,✅,✅,✅,
> +EPYC-v2,✅,✅,✅,
> +EPYC-v3,✅,✅,✅,
> +Haswell,✅,✅,✅,
> +Haswell-IBRS,✅,✅,✅,
> +Haswell-noTSX,✅,✅,✅,
> +Haswell-noTSX-IBRS,✅,✅,✅,
> +Haswell-v1,✅,✅,✅,
> +Haswell-v2,✅,✅,✅,
> +Haswell-v3,✅,✅,✅,
> +Haswell-v4,✅,✅,✅,
> +Icelake-Client,✅,✅,✅,
> +Icelake-Client-noTSX,✅,✅,✅,
> +Icelake-Client-v1,✅,✅,✅,
> +Icelake-Client-v2,✅,✅,✅,
> +Icelake-Server,✅,✅,✅,✅
> +Icelake-Server-noTSX,✅,✅,✅,✅
> +Icelake-Server-v1,✅,✅,✅,✅
> +Icelake-Server-v2,✅,✅,✅,✅
> +Icelake-Server-v3,✅,✅,✅,✅
> +Icelake-Server-v4,✅,✅,✅,✅
> +IvyBridge,✅,✅,,
> +IvyBridge-IBRS,✅,✅,,
> +IvyBridge-v1,✅,✅,,
> +IvyBridge-v2,✅,✅,,
> +KnightsMill,✅,✅,✅,
> +KnightsMill-v1,✅,✅,✅,
> +Nehalem,✅,✅,,
> +Nehalem-IBRS,✅,✅,,
> +Nehalem-v1,✅,✅,,
> +Nehalem-v2,✅,✅,,
> +Opteron_G1,✅,,,
> +Opteron_G1-v1,✅,,,
> +Opteron_G2,✅,,,
> +Opteron_G2-v1,✅,,,
> +Opteron_G3,✅,,,
> +Opteron_G3-v1,✅,,,
> +Opteron_G4,✅,✅,,
> +Opteron_G4-v1,✅,✅,,
> +Opteron_G5,✅,✅,,
> +Opteron_G5-v1,✅,✅,,
> +Penryn,✅,,,
> +Penryn-v1,✅,,,
> +SandyBridge,✅,✅,,
> +SandyBridge-IBRS,✅,✅,,
> +SandyBridge-v1,✅,✅,,
> +SandyBridge-v2,✅,✅,,
> +Skylake-Client,✅,✅,✅,
> +Skylake-Client-IBRS,✅,✅,✅,
> +Skylake-Client-noTSX-IBRS,✅,✅,✅,
> +Skylake-Client-v1,✅,✅,✅,
> +Skylake-Client-v2,✅,✅,✅,
> +Skylake-Client-v3,✅,✅,✅,
> +Skylake-Server,✅,✅,✅,✅
> +Skylake-Server-IBRS,✅,✅,✅,✅
> +Skylake-Server-noTSX-IBRS,✅,✅,✅,✅
> +Skylake-Server-v1,✅,✅,✅,✅
> +Skylake-Server-v2,✅,✅,✅,✅
> +Skylake-Server-v3,✅,✅,✅,✅
> +Skylake-Server-v4,✅,✅,✅,✅
> +Snowridge,✅,✅,,
> +Snowridge-v1,✅,✅,,
> +Snowridge-v2,✅,✅,,
> +Westmere,✅,✅,,
> +Westmere-IBRS,✅,✅,,
> +Westmere-v1,✅,✅,,
> +Westmere-v2,✅,✅,,
> +athlon,,,,
> +athlon-v1,,,,
> +core2duo,✅,,,
> +core2duo-v1,✅,,,
> +coreduo,,,,
> +coreduo-v1,,,,
> +kvm32,,,,
> +kvm32-v1,,,,
> +kvm64,✅,,,
> +kvm64-v1,✅,,,
> +n270,,,,
> +n270-v1,,,,
> +pentium,,,,
> +pentium-v1,,,,
> +pentium2,,,,
> +pentium2-v1,,,,
> +pentium3,,,,
> +pentium3-v1,,,,
> +phenom,✅,,,
> +phenom-v1,✅,,,
> +qemu32,,,,
> +qemu32-v1,,,,
> +qemu64,✅,,,
> +qemu64-v1,✅,,,
> diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc
> index 9a2327828e..b964b29c78 100644
> --- a/docs/system/cpu-models-x86.rst.inc
> +++ b/docs/system/cpu-models-x86.rst.inc
> @@ -39,6 +39,24 @@ CPU, as they would with "Host passthrough", but gives much of the
>  benefit of passthrough, while making live migration safe.
>  
>  
> +ABI compatibility levels for CPU models
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The x86_64 architecture has a number of `ABI compatibility levels`_
> +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
> +following table illustrates which ABI compatibility levels can be
> +satisfied by the QEMU CPU models

Missing full stop (or colon?).

> +
> +.. _ABI compatibility levels: https://gitlab.com/x86-psABIs/x86-64-ABI/
> +
> +.. csv-table:: x86-64 ABI compatibility levels
> +   :file: cpu-models-x86-abi.csv
> +   :widths: 40,15,15,15,15
> +   :header-rows: 1
> +
> +
>  Preferred CPU models for Intel x86 hosts
>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  
> -- 
> 2.29.2

dme.
-- 
All of us, we're going out tonight. We're gonna walk all over your cars.