[Qemu-devel] [PULL for-2.5 0/2] QAPI patches

[Qemu-devel] [PULL for-2.5 0/2] QAPI patches

[Markus Armbruster]

The following changes since commit c257779e2a586043a1480bb7e96fb6bcd0129634:

  Merge remote-tracking branch 'remotes/otubo/tags/pull-seccomp-20151116' into staging (2015-11-16 12:09:47 +0000)

are available in the git repository at:

  git://repo.or.cz/qemu/armbru.git tags/pull-qapi-2015-11-17

for you to fetch changes up to 513e7cdbaeec56c77e4cf26f151d7ee79f3a6be9:

  input: Document why x-input-send-event is still experimental (2015-11-17 08:42:07 +0100)

----------------------------------------------------------------
QAPI patches

----------------------------------------------------------------
Eric Blake (2):
      qapi: Document introspection stability considerations
      input: Document why x-input-send-event is still experimental

 docs/qapi-code-gen.txt | 11 +++++++++++
 qapi-schema.json       | 13 +++++++++++--
 qapi/introspect.json   |  9 +++++++++
 3 files changed, 31 insertions(+), 2 deletions(-)

Eric Blake (2):
  qapi: Document introspection stability considerations
  input: Document why x-input-send-event is still experimental

 docs/qapi-code-gen.txt | 11 +++++++++++
 qapi-schema.json       | 13 +++++++++++--
 qapi/introspect.json   |  9 +++++++++
 3 files changed, 31 insertions(+), 2 deletions(-)

-- 
2.4.3

[Qemu-devel] [PULL for-2.5 1/2] qapi: Document introspection stability considerations

[Markus Armbruster]

From: Eric Blake <eblake@redhat.com>

We are not ready (and might never be ready) to declare
introspection stable between releases. Clients written to
control multiple versions of qemu, and desiring to know
whether a particular member is supported for a given
command, must be prepared to locate that member in spite
of qapi changes that may affect the member's location or
type within the overall object, even though such changes
did not break QMP wire back-compatibility.

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <1447264202-19554-1-git-send-email-eblake@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/qapi-code-gen.txt | 11 +++++++++++
 qapi/introspect.json   |  9 +++++++++
 2 files changed, 20 insertions(+)

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index f9fa6f3..ceb9a78 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -514,6 +514,17 @@ exactly the server (QEMU) supports.
 For this purpose, QMP provides introspection via command
 query-qmp-schema.  QGA currently doesn't support introspection.
 
+While Client JSON Protocol wire compatibility should be maintained
+between qemu versions, we cannot make the same guarantees for
+introspection stability.  For example, one version of qemu may provide
+a non-variant optional member of a struct, and a later version rework
+the member to instead be non-optional and associated with a variant.
+Likewise, one version of qemu may list a member with open-ended type
+'str', and a later version could convert it to a finite set of strings
+via an enum type; or a member may be converted from a specific type to
+an alternate that represents a choice between the original type and
+something else.
+
 query-qmp-schema returns a JSON array of SchemaInfo objects.  These
 objects together describe the wire ABI, as defined in the QAPI schema.
 There is no specified order to the SchemaInfo objects returned; a
diff --git a/qapi/introspect.json b/qapi/introspect.json
index e7c4c3e..9e9369e 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -22,6 +22,15 @@
 # what's there), not interface specification.  The specification is in
 # the QAPI schema.
 #
+# Furthermore, while we strive to keep the QMP wire format
+# backwards-compatible across qemu versions, the introspection output
+# is not guaranteed to have the same stability.  For example, one
+# version of qemu may list an object member as an optional
+# non-variant, while another lists the same member only through the
+# object's variants; or the type of a member may change from a generic
+# string into a specific enum or from one specific type into an
+# alternate that includes the original type alongside something else.
+#
 # Returns: array of @SchemaInfo, where each element describes an
 # entity in the ABI: command, event, type, ...
 #
-- 
2.4.3

[Qemu-devel] [PULL for-2.5 2/2] input: Document why x-input-send-event is still experimental

[Markus Armbruster]

From: Eric Blake <eblake@redhat.com>

The x-input-send-event command was introduced in 2.2 with mention
that it is experimental, but now that several releases have elapsed
without any changes, it would be nice to document why that was done
and should still remain experimental in 2.5.

Meanwhile, our documentation states that we prefer 'lower-case',
rather than 'CamelCase', for qapi enum values.  The InputButton and
InputAxis enums violate this convention.  However, because they are
currently used primarily for generating code that is used internally;
and their only exposure through QMP is via the experimental
'x-input-send-event' command, we are free to change their spelling.
Of course, it would be nicer to delay such a change until the same
time we promote the command to non-experimental.  Adding
documentation will help us remember to do that rename.

We have plans to tighten the qapi generator to flag instances of
inconsistent use of naming conventions; if that lands first, it
will just need to whitelist these exceptions until the time we
settle on the final interface.

Fix a typo in the docs for InputAxis while at it.

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <1447354243-31825-1-git-send-email-eblake@redhat.com>
Reviewed-by: Gerd Hoffmann <kraxel@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi-schema.json | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/qapi-schema.json b/qapi-schema.json
index b65905f..8b1a423 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3579,16 +3579,22 @@
 # Button of a pointer input device (mouse, tablet).
 #
 # Since: 2.0
+#
+# Note that the spelling of these values may change when the
+# x-input-send-event is promoted out of experimental status.
 ##
 { 'enum'  : 'InputButton',
   'data'  : [ 'Left', 'Middle', 'Right', 'WheelUp', 'WheelDown' ] }
 
 ##
-# @InputButton
+# @InputAxis
 #
 # Position axis of a pointer input device (mouse, tablet).
 #
 # Since: 2.0
+#
+# Note that the spelling of these values may change when the
+# x-input-send-event is promoted out of experimental status.
 ##
 { 'enum'  : 'InputAxis',
   'data'  : [ 'X', 'Y' ] }
@@ -3679,7 +3685,10 @@
 #
 # Since: 2.2
 #
-# Note: this command is experimental, and not a stable API.
+# Note: this command is experimental, and not a stable API.  Things that
+# might change before it becomes stable include the spelling of enum
+# values for InputButton and InputAxis, and the notion of how to designate
+# which console will receive the event.
 #
 ##
 { 'command': 'x-input-send-event',
-- 
2.4.3

Re: [Qemu-devel] [PULL for-2.5 0/2] QAPI patches

[Peter Maydell]

On 17 November 2015 at 08:46, Markus Armbruster <armbru@redhat.com> wrote:
> The following changes since commit c257779e2a586043a1480bb7e96fb6bcd0129634:
>
>   Merge remote-tracking branch 'remotes/otubo/tags/pull-seccomp-20151116' into staging (2015-11-16 12:09:47 +0000)
>
> are available in the git repository at:
>
>   git://repo.or.cz/qemu/armbru.git tags/pull-qapi-2015-11-17
>
> for you to fetch changes up to 513e7cdbaeec56c77e4cf26f151d7ee79f3a6be9:
>
>   input: Document why x-input-send-event is still experimental (2015-11-17 08:42:07 +0100)
>
> ----------------------------------------------------------------
> QAPI patches
>
> ----------------------------------------------------------------
> Eric Blake (2):
>       qapi: Document introspection stability considerations
>       input: Document why x-input-send-event is still experimental
>

Applied, thanks.

-- PMM