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

[Daniel P . Berrangé]

On Tue, Feb 02, 2021 at 09:41:15AM +0000, David Edmondson wrote:
> 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).

I felt it was clearer to only show the positive case. Since the
ABI levels are additive, you can count the ticks at a glance to see
the ABI level achieved. Also this CSV file isn't really meant to
be seen by users directly. It is just data input that gets rendered
into an HTML table that looks like this:

  
https://berrange.gitlab.io/-/qemu/-/jobs/1001700036/artifacts/public/system/target-i386.html#recommendations-for-kvm-cpu-model-configuration-on-x86-hosts

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|