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

[Anthony Liguori <anthony@codemonkey.ws>]

On 03/09/2011 08:37 AM, Avi Kivity wrote:
> 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.

Yeah, I dislike it too and I've been leaning towards changing it.

My preference would be:

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

I do prefer the dictionary syntax for arguments over a list because a 
list implies order.  Plus I think the syntax is just awkward and a whole 
lot easier to get wrong (too many/few elements in list).

I don't think I want to make this sort of change just yet.  Also note 
that the schema that will be exposed over the wire is not directly 
related to the schema we use for code generation.

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

I'd rather just not add arguments.

Treating QMP as a C API makes it easier for us to maintain compatibility 
both internally and externally.

Regards,

Anthony Liguori