Re: [PATCH v2] machine: add missing doc for memory-backend option

[Igor Mammedov <imammedo@redhat.com>]

On Fri, 15 Jan 2021 10:02:04 +0000
Peter Maydell <peter.maydell@linaro.org> wrote:

> On Thu, 14 Jan 2021 at 23:48, Igor Mammedov <imammedo@redhat.com> wrote:
> >
> > Add documentation for '-machine memory-backend' CLI option and
> > how to use it.
> >
> > And document that x-use-canonical-path-for-ramblock-id,
> > is considered to be stable to make sure it won't go away by accident.  
> 
> That's not what the x- prefix is supposed to mean.
> If we have an internal constraint that we mustn't delete
> the option in order to support some other must-be-stable
> interface (eg migration of some machines) we can document
> that in a comment,
that was in v1, and Peter asked for adding assurance to help/doc as well.

> but that doesn't mean that we should
> document to users that direct use of an x-prefix option
> is supported as a stable interface.
A concur, that we don't have to declare it as stable in help/doc,
but we still have to document x-use-canonical-path-for-ramblock-id=off
the so users would know how/when to use it in this particular case.


> Alternatively, if the option is really stable for direct
> use by users then we should commit to making it so by
> removing the x-.

Peter Maydell,

I think Peter Krempa already explained/pointed to discussion why
x-use-canonical-path-for-ramblock-id wasn't renamed.

So as I see options are:
  1) keep x- prefix declare it as stable both in doc and comments (like in this patch)
     add to commit message why we are keeping x-
  2) keep x- prefix declare it as stable in comments only,
     keep doc changes to explaining how/when to use it
     add to commit message why we are keeping x-
  3) rename/drop x- prefix and don't care about QEMU-5.0-5.2
     (libvirt would use old syntax (-mem-path/mem-prealloc) for them
      which also leads to => no virtiofs as it needs shared RAM that
      new syntax with backend provides for main RAM)

Which one is acceptable to you?

> thanks
> -- PMM
>