QAPI patches

-----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJWSuUoAAoJEDhwtADrkYZTMXIP/ijz05sXbgx06GWvhWBEeAxK
 /LSU2+a6CjVaj8yX+nzbGnK6b3Xu3GVFtjgy2XrSzDvuCyVv6olq1yh3UNZUlyBh
 cQrQe7BAwFUJVDyB8Znwvwadona8fp9WjJoKFRmTgO9quSUJR4ZE5EtxLqqAz0WR
 dfK+t7kG3P25dHHjRSXdGjQOZa/jOHcJboccQoPGDVFx0WkaS21U2kd22rjVPmjM
 B4DpHkIKxM3rpDne5Xg17rHwoBB1PvgdZ3Ib2mj6B2gnLT/mCeXFKxCUeQBeKcVL
 E5D7/co77BQrDbiTQB8SuXw03LfnuA+EGTOmXgClqErh6GrIBo8YrYsbFU4yxV/l
 glaQ7ionkbRGawpSWgQxMuQ73s2Nvyz74w3lo/WmaR/2Vvjuu4KPLLO+Dd2apqPX
 HOv8x0h3IFVYxhOGVdFCIX13NFb1d7jGFSOl/9hzfoZc8zWgZOEMYcAN3nMl24DW
 K2wBA2dzGvmzpiCNiEppL0rysZU33cnEKJtxwGjYpS3OgqcBp2OyxBlrHUtfZ6tF
 KmB/JMNDx8Kh3r+PI1ZqdAWP9yfBAWDvGp8Vol+Nv06T/MSQlIN2PlkTopR+czZE
 sbSQeKSI0S3mlCv45PLY9oB+kOgSIYcRCD5xwGO9tAbxyfW69eew+nPqSnhcLmQt
 lacneNDlYjHKfmAfv0VB
 =Lr9c
 -----END PGP SIGNATURE-----

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>

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

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',

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