Re: [PATCH-for-6.2] docs: add a word of caution on x-native-hotplug property for pcie-root-ports

[Ani Sinha]

On Sat, Nov 27, 2021 at 1:08 AM Igor Mammedov <imammedo@redhat.com> wrote:
>
> It's hardly 6.2 material

We introduced the x-hotplug etc property with 6.2. I wanted to make
sure that people understand that the x- prefix indicates that this is
experimental stuff. We had enough mess with this already.

>
> On Fri, 26 Nov 2021 11:12:55 +0530 (IST)
> Ani Sinha <ani@anisinha.ca> wrote:
>
> > On Thu, 25 Nov 2021, Michael S. Tsirkin wrote:
> >
> > > On Thu, Nov 25, 2021 at 05:36:29PM +0530, Ani Sinha wrote:
> > > > x-native-hotplug property, when used in order to disable HPC bit on the 
> > > > PCIE
> > > > root ports, can lead to unexpected results from the guest operating 
> > > > system.
> > > > Users are strongly advised not to touch this property in order to 
> > > > manipulte the
> > > > HPC bit. Add a word of caution in the pcie.txt doc file to document 
> > > > this.
> > > >
> > > > Signed-off-by: Ani Sinha <ani@anisinha.ca>
> > >
> > > Do we want to generally document this for all "x-" options?
> >
> > Yes igor suggested it but I sent this one for two reasons:
> > (a) I could not find a place to document this for properties without
> > adding a new file. This sounded too bigger a hammer at the present. If you
> > can suggest an existing place for documenting this for the property names,
> > I will go and add this info there as well.
> >
> > (b) I think we need to document this experimental property here regardless
> > because this doc deals with hotplug and pcie ports and we had too much of
> > a mess with this acpi/pci native switch.
> >
> > When things stabilize a bit, Igor suggested elsewhere that we start a
> > separate doc just for hotplug and various options we have and at
> > that point we can move this info in this new doc.
> >
> > https://www.mail-archive.com/libvir-list@redhat.com/msg221746.html
>
> I'd rather put a blanket statement somewhere, like:
>
> "x-" prefixed properties are experimental, unstable, internal and
> are subject to change/go away without prior notice.
> Such properties are not meant for use by users unless explicitly
> documented otherwise.

I will leave this to someone else to pick it up for the doc side if
they are interested.

>
> > >
> > > > ---
> > > >  docs/pcie.txt | 17 ++++++++++++++++-
> > > >  1 file changed, 16 insertions(+), 1 deletion(-)
> > > >
> > > > diff --git a/docs/pcie.txt b/docs/pcie.txt
> > > > index 89e3502075..e1f99f725f 100644
> > > > --- a/docs/pcie.txt
> > > > +++ b/docs/pcie.txt
> > > > @@ -262,11 +262,26 @@ PCI Express Root Ports (and PCI Express 
> > > > Downstream Ports).
> > > >          Port, which may come handy for hot-plugging another device.
> > > >
> > > >
> > > > -5.3 Hot-plug example:
> > > > +5.2 Hot-plug example:
> > > >  Using HMP: (add -monitor stdio to QEMU command line)
> > > >    device_add <dev>,id=<id>,bus=<PCI Express Root Port Id/PCI Express 
> > > > Downstream Port Id/PCI-PCI Bridge Id/>
> > > >
> > > >
> > > > +5.3 A word of caution using hotplug on PCI Express Root Ports:
> > > > +Starting Qemu version 6.2, PCI Express Root ports have a property
> > > > +"x-native-hotplug" ("native-hotplug" for Qemu version 6.1), that can 
> > > > be used to
> > > > +enable or disable hotplug on that port. For example:
> > > > +
> > > > +-device pcie-root-port,x-native-hotplug=off,... etc.
> > > > +
> > > > +The "x-" prefix indicates that this property is highly experimental 
> > > > and can
> > > > +lead to unexpected results from the guest operating system if users 
> > > > try to use
> > > > +it to alter the native hotplug on the port. It also means that the 
> > > > property
> > > > +name and its behavior is liable to change in the future and is not 
> > > > expected to
> > > > +be stable across Qemu versions. Therefore, end users are advised not 
> > > > to change
> > > > +the value of this option from its default set value or use it in the 
> > > > Qemu
> > > > +command line.
> > > > +
> > > >  6. Device assignment
> > > >  ====================
> > > >  Host devices are mostly PCI Express and should be plugged only into
> > > > --
> > > > 2.25.1
> > >
> > >
> >
>