[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [RFC v5 24/26] docs: update QMP documents for OOB comma
From: |
Peter Xu |
Subject: |
Re: [Qemu-devel] [RFC v5 24/26] docs: update QMP documents for OOB commands |
Date: |
Tue, 19 Dec 2017 11:18:17 +0800 |
User-agent: |
Mutt/1.9.1 (2017-09-22) |
On Mon, Dec 18, 2017 at 02:09:36PM +0000, Stefan Hajnoczi wrote:
> On Mon, Dec 18, 2017 at 05:44:19PM +0800, Peter Xu wrote:
> > On Thu, Dec 14, 2017 at 02:30:19PM +0000, Stefan Hajnoczi wrote:
> > > On Tue, Dec 05, 2017 at 01:51:58PM +0800, Peter Xu wrote:
> > > > diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> > > > index f04c63fe82..8597fdb087 100644
> > > > --- a/docs/devel/qapi-code-gen.txt
> > > > +++ b/docs/devel/qapi-code-gen.txt
> > > > @@ -556,7 +556,8 @@ following example objects:
> > > >
> > > > Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
> > > > '*returns': TYPE-NAME, '*boxed': true,
> > > > - '*gen': false, '*success-response': false }
> > > > + '*gen': false, '*success-response': false,
> > > > + '*allow-oob': false }
> > > >
> > > > Commands are defined by using a dictionary containing several members,
> > > > where three members are most common. The 'command' member is a
> > > > @@ -636,6 +637,44 @@ possible, the command expression should include
> > > > the optional key
> > > > 'success-response' with boolean value false. So far, only QGA makes
> > > > use of this member.
> > > >
> > > > +Most of the QMP commands are handled sequentially in such a order:
> > > > +Firstly, the JSON Parser parses the command request into some internal
> > > > +message, delivers the message to QMP dispatchers. Secondly, the QMP
> > > > +dispatchers will handle the commands one by one in time order, respond
> > > > +when necessary.
> > >
> > > The important points to cover about normal commands:
> > > 1. They execute in order
> > > 2. They run the main loop
> > > 3. They run under the BQL
> > >
> > > The other stuff about parsing requests into internal messages,
> > > dispatchers, etc is not relevant. It's better not to include it in
> > > documentation because it can change and could also confuse readers
> > > (since they don't need this info).
> >
> > Ah yes. I'm thinking whether I should just remove most of the changes
> > to this file (qapi-code-gen.txt) since most of them are really not
> > related to code gen at all... Maybe somewhere in qmp-spec.txt as
> > well?
>
> qmp-spec.txt is the wire protocol that QMP clients and servers follow.
> QEMU details like the BQL do not belong in qmp-spec.txt.
>
> qapi-code-gen.txt is not a bad place to document the QEMU details that
> are relevant to people writing QMP commands with allow-oob: true. What
> I was getting at is that this document should focus on things that QMP
> command authors need to know, not on monitor implementation details.
Fair enough. I'll try to avoid talking about QMP internals in either
of the documents.
Let me cook a better one. Thanks,
--
Peter Xu
- Re: [Qemu-devel] [RFC v5 21/26] qmp: isolate responses into io thread, (continued)
[Qemu-devel] [RFC v5 22/26] monitor: enable IO thread for (qmp & !mux) typed, Peter Xu, 2017/12/05
[Qemu-devel] [RFC v5 23/26] qmp: add command "x-oob-test", Peter Xu, 2017/12/05
[Qemu-devel] [RFC v5 24/26] docs: update QMP documents for OOB commands, Peter Xu, 2017/12/05
[Qemu-devel] [RFC v5 25/26] tests: qmp-test: verify command batching, Peter Xu, 2017/12/05
[Qemu-devel] [RFC v5 26/26] tests: qmp-test: add oob test, Peter Xu, 2017/12/05
Re: [Qemu-devel] [RFC v5 00/26] QMP: out-of-band (OOB) execution support, Stefan Hajnoczi, 2017/12/14
Re: [Qemu-devel] [RFC v5 00/26] QMP: out-of-band (OOB) execution support, Fam Zheng, 2017/12/15