Peter Xu <pet...@redhat.com> 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 <arm...@redhat.com> > Signed-off-by: Peter Xu <pet...@redhat.com> > --- > 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 <arm...@redhat.com>
