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

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

[Ani Sinha]

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>
---
 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

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

[Michael S. Tsirkin]

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?

> ---
>  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

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

[Ani Sinha]

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


>
> > ---
> >  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
>
>

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

[Igor Mammedov]

It's hardly 6.2 material

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.

> >  
> > > ---
> > >  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  
> >
> >  
> 

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
> > >
> > >
> >
>