Re: [Qemu-devel] [PATCH 14/22] qapi: add query-version QMP command

[Avi Kivity <avi@redhat.com>]

On 03/09/2011 04:11 PM, Anthony Liguori wrote:
>> (just picking on a patch that has a bit of schema in it)
>
>
> If you want to see more of the schema in action 
> http://repo.or.cz/w/qemu/aliguori.git/blob/refs/heads/glib:/qmp-schema.json

Thanks.  Something a little worrying is the reliance on capitalization 
and punctuation ( {} vs [] ) do distinguish among the different types of 
declarations.  It's not immediately clear if something is a type, event, 
or command.

We could do

[

{ 'type': 'MyType', fields: [['a', 'str'], ['b', 'int'], ['c', 
'AnotherType']] }
{ 'event': 'MY_EVENT', 'arguments': [ ... ] }
{ 'command': 'my-command', 'arguments': [ ... ], 'return': ... }

]

which leaves us room for additional metainformation.

The concern is more about non-qemu consumers of the schema.

>
>> Something that can be added to the schema are default values for 
>> newly added parameters.  This way we can avoid an explosion of 
>> commands where adding an optional parameter suffices; should be 
>> easier for the user to pick the right command and easier for us to 
>> document and support.
>
> Adding a parameter to a command, even if the schema specifies a 
> default value, is going to break the C library ABI so it's something 
> we should strongly discourage.

We could add compatibility signatures when we extend a command:


{ 'command': 'x', arguments: [['a', 'str']], return: ...,
    'signatures': { 'x': [], 'x2': ['a'] } }

That lets the wire protocol extend x without introducing a new command, 
but for libqmp it adds a new x2() API with the new parameter.

>
> We definitely want to systematically document defaults but the 
> question is whether that belongs in the documentation for the command 
> or the schema itself.  Since a default doesn't affect the wire 
> protocol in any way, shape, or form, I think there a pretty strong 
> argument that it belongs in the documentation and not the schema.

Agree.

>
> gtk-doc typically uses a tag to identify defaults.  I think it's 
> something like #default although that is purely a marking concept (the 
> value isn't parsed out or anything).  Whether we'd want to 
> automatically parse the value following the #default tag and change 
> the internal signature is probably a discussion we can defer.  Since 
> this only really should apply to structures, I suspect it's not a huge 
> win.

-- 
error compiling committee.c: too many arguments to function