Re: [Qemu-devel] [RFC v6 25/27] docs: update QMP documents for OOB commands

[Peter Xu]

On Tue, Jan 09, 2018 at 02:52:25PM +0000, Stefan Hajnoczi wrote:
> On Tue, Dec 19, 2017 at 04:45:55PM +0800, Peter Xu wrote:
> > +To add OOB execution support for a command, we need to make sure the
> > +command handler satisfies at least the following:
> 
> It would help to rephrase this in the imperative mood (telling the
> reader what to do rather than describing what would need to be done):
> 
> "OOB command handlers must satisfy the following conditions:"
> 
> That way it's shorter and easier to read, and it communicates that these
> conditions are absolutely necessary.
> 
> > +
> > +- It executes extremely fast,
> > +- It does not take any lock (or, it can take very small locks, but in
> > +  very predictable ways),
> 
> "it can take very small locks, but in very predictable ways" does not
> explain what is allowed and what isn't.
> 
> I suggest: "it can take very small locks if all critical regions also
> follow the rules for OOB command handler code".
> 
> > +- It does not invoke system calls that may block,
> > +- It does not access guest RAM that may block when userfaultfd is
> > +  enabled for postcopy live migration.
> > +
> > +If someone is unsure about whether a command handler can be run in OOB
> > +way, then it possibly means that it does not suite for OOB execution.
> 
> "If in doubt, do not implement OOB execution support."

All fixed.  Thanks,

-- 
Peter Xu