mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qapi: Document introspection stability considerations

Browse Source 
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>
This commit is contained in:
Eric Blake 2015-11-11 10:50:02 -07:00 committed by Markus Armbruster
parent c257779e2a
commit 39a65e2c24
2 changed files with 20 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/qapi-code-gen.txt
View File

@ -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

9
qapi/introspect.json
View File

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