aboutsummaryrefslogtreecommitdiff
path: root/qapi
diff options
context:
space:
mode:
authorEric Blake <eblake@redhat.com>2015-11-11 10:50:02 -0700
committerMarkus Armbruster <armbru@redhat.com>2015-11-17 08:42:07 +0100
commit39a65e2c243978a480e03cab865462d98873fc3c (patch)
tree774200f0b32e424867c1f28d55e7b55c5cebcbc6 /qapi
parentc257779e2a586043a1480bb7e96fb6bcd0129634 (diff)
qapi: Document introspection stability considerations
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>
Diffstat (limited to 'qapi')
-rw-r--r--qapi/introspect.json9
1 files changed, 9 insertions, 0 deletions
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, ...
#