Re: [Qemu-devel] [PATCH v4 5/7] docs: mention shared state protect for OOB

[Markus Armbruster]

Peter Xu <address@hidden> writes:

> Out-Of-Band handlers need to protect shared state if there is any.
> Mention it in the document.  Meanwhile, touch up some other places too,
> either with better English, or reordering of bullets.
>
> Suggested-by: Markus Armbruster <address@hidden>
> Signed-off-by: Peter Xu <address@hidden>
> ---
>  docs/devel/qapi-code-gen.txt | 17 +++++++++++------
>  1 file changed, 11 insertions(+), 6 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index 1366228b2a..fb486d4050 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -664,22 +664,27 @@ command:
>  
>  - They are executed in order,
>  - They run only in main thread of QEMU,
> -- They have the BQL taken during execution.
> +- They run with the BQL held.
>  
>  When a command is executed with OOB, the following changes occur:
>  
>  - They can be completed before a pending in-band command,
>  - They run in a dedicated monitor thread,
> -- They do not take the BQL during execution.
> +- They run with the BQL not held.
>  
>  OOB command handlers must satisfy the following conditions:
>  
> -- It executes extremely fast,
> -- It does not take any lock, or, it can take very small locks if all
> -  critical regions also follow the rules for OOB command handler code,
> +- It terminates quickly,
>  - 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.
> +  enabled for postcopy live migration,
> +- It takes only "fast" locks, i.e. all critical sections protected by
> +  any lock it takes also satisfy the conditions for OOB command
> +  handler code.
> +
> +The restrictions on locking limit access to shared state.  Such access
> +requires synchronization, but OOB commands can't take the BQL or any
> +other "slow" lock.
>  
>  If in doubt, do not implement OOB execution support.

Reviewed-by: Markus Armbruster <address@hidden>