Re: [Qemu-devel] [PATCH 3/4] doc: add item for "-M enforce-config-section"

[Peter Xu]

On Mon, Jul 03, 2017 at 02:07:12PM -0300, Eduardo Habkost wrote:
> On Mon, Jul 03, 2017 at 10:44:07AM +0800, Peter Xu wrote:
> > It's never documented, and now we have one more parameter for it (which
> > means this one can be obsolete in the future). Document it properly.
> > 
> > Although now when enforce-config-section is set, it'll override the
> > other "-global" parameter, that is not necessarily a rule. Forbid that
> > usage in the document.
> > 
> > Suggested-by: Eduardo Habkost <address@hidden>
> > Signed-off-by: Peter Xu <address@hidden>
> > ---
> >  qemu-options.hx | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> > 
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index 297bd8a..927c51f 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -85,6 +85,14 @@ Enables or disables NVDIMM support. The default is off.
> >  @item s390-squash-mcss=on|off
> >  Enables or disables squashing subchannels into the default css.
> >  The default is off.
> > address@hidden enforce-config-section=on|off
> > +Decides whether we will send the configuration section when doing
> > +migration. By default, it is turned on. We can set this to off to
> > +explicitly disable it.
> [...]
> 
> Wait, isn't it off by default?
> 
> This seems to imply that "-machine enforce-config-section=on" would have
> no effect at all, as the option would be already on by default.  This is
> not the case.
> 
> I suggest rewriting this as:
> 
>   If set to "on, force migration code to send configuration section even
>   if the machine-type sets the "migration.send-configuration" property
>   to "off".
>   Note: this parameter is obsolete, please use "-global
>   migration.send-configuration=on|off" instead.
>   Behavior is undefined if "enforce-config-section" and "-global
>   migration.send-configuration" are used together.
> 
> (Note: we probably should use proper markup (@option/@var/@samp?)
> instead of quotes above, to format the option names properly in the
> generated documentation.)

Yes, you are right.  How's this one? (markup used this time)

If @option{enforce-config-section} is set to @var{on}, force migration
code to send configuration section even if the machine-type sets the
@option{migration.send-configuration} property to @var{off}.
@option{enforce-config-section} cannot be used together with
@option{-global} @option{migration.send-configuration}. Behavior is
undefined if @option{enforce-config-section} and @option{-global}
@option{migration.send-configuration} are used together.

NOTE: this parameter is obsolete. Please use @option{-global}
@address@hidden|off} instead.

Thanks,

-- 
Peter Xu