From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=60358 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PxKVx-00030G-0Q for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:37:26 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PxKVu-0007Uw-QS for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:37:24 -0500 Received: from mx1.redhat.com ([209.132.183.28]:55031) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PxKVu-0007UM-I6 for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:37:22 -0500 Message-ID: <4D77909B.90800@redhat.com> Date: Wed, 09 Mar 2011 16:37:15 +0200 From: Avi Kivity 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> In-Reply-To: <4D778A9F.80700@codemonkey.ws> 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: Anthony Liguori Cc: qemu-devel@nongnu.org, Adam Litke , Anthony Liguori , Markus Armbruster , Luiz Capitulino 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