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

[Stefan Hajnoczi]

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

signature.asc
Description: PGP signature