Re: [PATCH 11/12] docs/system/arm/virt: document missing properties

[Pierrick Bouvier]

On 11/25/24 09:02, Peter Maydell wrote:
> On Fri, 22 Nov 2024 at 22:52, Pierrick Bouvier
> <pierrick.bouvier@linaro.org> wrote:
> > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> > ---
> >   docs/bypass-iommu.txt    |  2 ++
> >   docs/system/arm/virt.rst | 15 +++++++++++++++
> >   2 files changed, 17 insertions(+)
> >
> > diff --git a/docs/bypass-iommu.txt b/docs/bypass-iommu.txt
> > index e6677bddd32..62818e44ed9 100644
> > --- a/docs/bypass-iommu.txt
> > +++ b/docs/bypass-iommu.txt
> > @@ -1,3 +1,5 @@
> > +.. _bypass_iommu:
> > +
>
> This is a .txt file -- adding rST markup to it won't do anything :-)
>
> (It's one of the remaining legacy .txt files that we haven't
> yet converted to .rst and moved to the right place in the
> documentation. The .txt files in the /docs/ directory are
> mostly the awkward ones to convert because they are a mishmash
> of internal info about the implementation and stuff that is user
> facing, that needs to be pulled apart by somebody with some
> familiarity with the feature and moved into the right places,
> or in some cases simply deleted as unnecessary.)

Oops.
I was very unlucky because it's the only place where I did the mistake 
to use an anonymous link >`_, instead of ref link, so I missed it.
Adding too many rst links is bad for your (mental) health :)

I'll update the bypass_iommu link to refer to the file (upstream) instead.

> >   BYPASS IOMMU PROPERTY
> >   =====================
> >
> > diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst
> > index 11ceb898264..d3d21499ff5 100644
> > --- a/docs/system/arm/virt.rst
> > +++ b/docs/system/arm/virt.rst
> > @@ -169,10 +169,17 @@ iommu
> >     ``smmuv3``
> >       Create an SMMUv3
> >
> > +default-bus-bypass-iommu
> > +  Set ``on``/``off`` to enable/disable `bypass_iommu <bypass_iommu>`_ for
> > +  default root bus.
> > +
> >   ras
> >     Set ``on``/``off`` to enable/disable reporting host memory errors to a guest
> >     using ACPI and guest external abort exceptions. The default is off.
> >
> > +acpi
> > +  Set ``on``/``off``/``auto`` to enable/disable ACPI.
> > +
> >   dtb-randomness
> >     Set ``on``/``off`` to pass random seeds via the guest DTB
> >     rng-seed and kaslr-seed nodes (in both "/chosen" and
> > @@ -186,6 +193,14 @@ dtb-randomness
> >   dtb-kaslr-seed
> >     A deprecated synonym for dtb-randomness.
> >
> > +x-oem-id
> > +  Set string (up to 6 bytes) to override the default value of field OEMID in 
> > ACPI
> > +  table header.
> > +
> > +x-oem-table-id
> > +  Set string (up to 8 bytes) to override the default value of field OEM Table 
> > ID
> > +  in ACPI table header.
>
> Do we have a policy about whether we should explicitly note that
> x- options are not ABI-stable when we document them?

I noticed that x-rme was documented, so took it as an implicit yes.

From the commit that introduce them [1], it seems to be more a 
workaround than proper experimental options, which is a bit debatable to 
be honest.

If you prefer to not include x-oem-* options, let me know.

[1] 
https://gitlab.com/qemu-project/qemu/-/commit/90a66f48471975fd46f1caab1574679f0a0ef74b

> thanks
> -- PMM