diff options
| -rw-r--r-- | docs/qapi-code-gen.txt | 11 | ||||
| -rw-r--r-- | qapi-schema.json | 13 | ||||
| -rw-r--r-- | qapi/introspect.json | 9 |
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, ... # |