aboutsummaryrefslogtreecommitdiff
path: root/docs
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 /docs
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 'docs')
-rw-r--r--docs/qapi-code-gen.txt11
1 files changed, 11 insertions, 0 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