Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2015-11-17' into staging

QAPI patches

# gpg: Signature made Tue 17 Nov 2015 08:28:24 GMT using RSA key ID EB918653
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>"
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>"

* remotes/armbru/tags/pull-qapi-2015-11-17:
  input: Document why x-input-send-event is still experimental
  qapi: Document introspection stability considerations

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

3 files changed, 31 insertions, 2 deletions

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index f9fa6f3d96..ceb9a782d0 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-schema.json b/qapi-schema.json
index b65905f4d6..8b1a423fa7 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',
diff --git a/qapi/introspect.json b/qapi/introspect.json
index e7c4c3e998..9e9369e160 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, ...
 #