qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Anthony Liguori
Subject: Re: [Qemu-devel] [PATCH 14/22] qapi: add query-version QMP command
Date: Wed, 09 Mar 2011 08:11:43 -0600
User-agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.14) Gecko/20110223 Lightning/1.0b2 Thunderbird/3.1.8

On 03/09/2011 07:36 AM, Avi Kivity wrote:
On 03/07/2011 03:22 AM, Anthony Liguori wrote:
This is used internally by QMP. It's also a pretty good example of a typical
command conversion.

+##
+{ 'VersionInfo': {'qemu': {'major': 'int', 'minor': 'int', 'micro': 'int'},
+                  'package': 'str'} }
+
+##
+# @query-version:
+#
+# Returns the current version of QEMU.
+#
+# Returns: A @VersionInfo object describing the current version of QEMU.
+#
+# Since: 0.14.0
+##
+[ 'query-version', {}, {}, 'VersionInfo' ]

(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

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

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.

Regards,

Anthony Liguori




reply via email to

[Prev in Thread] Current Thread [Next in Thread]