From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=59158 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PxKfQ-0000ng-33 for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:47:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PxKfO-0001Yc-TH for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:47:11 -0500 Received: from mail-iw0-f173.google.com ([209.85.214.173]:63148) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PxKfO-0001YQ-OW for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:47:10 -0500 Received: by iwl42 with SMTP id 42so683879iwl.4 for ; Wed, 09 Mar 2011 06:47:10 -0800 (PST) Message-ID: <4D7792E8.4020402@codemonkey.ws> Date: Wed, 09 Mar 2011 08:47:04 -0600 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH 14/22] qapi: add query-version QMP command References: <1299460984-15849-1-git-send-email-aliguori@us.ibm.com> <1299460984-15849-15-git-send-email-aliguori@us.ibm.com> <4D778246.8090504@redhat.com> <4D778A9F.80700@codemonkey.ws> <4D77909B.90800@redhat.com> In-Reply-To: <4D77909B.90800@redhat.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Avi Kivity Cc: Anthony Liguori , Luiz Capitulino , qemu-devel@nongnu.org, Markus Armbruster 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