# -*- Mode: Python -*-
-#
-# QAPI/QMP introspection
+# vim: filetype=python
#
# Copyright (C) 2015 Red Hat, Inc.
#
# See the COPYING file in the top-level directory.
##
-# @query-qmp-schema
+# = QMP introspection
+##
+
+##
+# @query-qmp-schema:
#
# Command query-qmp-schema exposes the QMP wire ABI as an array of
# SchemaInfo. This lets QMP clients figure out what commands and
# 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, ...
+# entity in the ABI: command, event, type, ...
+#
+# The order of the various SchemaInfo is unspecified; however, all
+# names are guaranteed to be unique (no name will be duplicated with
+# different meta-types).
#
# Note: the QAPI schema is also used to help define *internal*
-# interfaces, by defining QAPI types. These are not part of the QMP
-# wire ABI, and therefore not returned by this command.
+# interfaces, by defining QAPI types. These are not part of the QMP
+# wire ABI, and therefore not returned by this command.
#
# Since: 2.5
##
'gen': false } # just to simplify qmp_query_json()
##
-# @SchemaMetaType
+# @SchemaMetaType:
#
# This is a @SchemaInfo's meta type, i.e. the kind of entity it
# describes.
'command', 'event' ] }
##
-# @SchemaInfoBase
-#
-# Members common to any @SchemaInfo.
-#
-# Since: 2.5
-##
-{ 'struct': 'SchemaInfoBase',
- 'data': { 'name': 'str', 'meta-type': 'SchemaMetaType' } }
-
-##
-# @SchemaInfo
+# @SchemaInfo:
#
# @name: the entity's name, inherited from @base.
+# The SchemaInfo is always referenced by this name.
# Commands and events have the name defined in the QAPI schema.
# Unlike command and event names, type names are not part of
# the wire ABI. Consequently, type names are meaningless
-# strings here.
-#
-# All references to other SchemaInfo are by name.
+# strings here, although they are still guaranteed unique
+# regardless of @meta-type.
#
# @meta-type: the entity's meta type, inherited from @base.
#
+# @features: names of features associated with the entity, in no
+# particular order.
+# (since 4.1 for object types, 4.2 for commands, 5.0 for
+# the rest)
+#
# Additional members depend on the value of @meta-type.
#
# Since: 2.5
##
{ 'union': 'SchemaInfo',
- 'base': 'SchemaInfoBase',
+ 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
+ '*features': [ 'str' ] },
'discriminator': 'meta-type',
'data': {
'builtin': 'SchemaInfoBuiltin',
'event': 'SchemaInfoEvent' } }
##
-# @SchemaInfoBuiltin
+# @SchemaInfoBuiltin:
#
# Additional SchemaInfo members for meta-type 'builtin'.
#
'data': { 'json-type': 'JSONType' } }
##
-# @JSONType
+# @JSONType:
#
-# The four primitive and two structured types according to RFC 7159
+# The four primitive and two structured types according to RFC 8259
# section 1, plus 'int' (split off 'number'), plus the obvious top
# type 'value'.
#
'object', 'array', 'value' ] }
##
-# @SchemaInfoEnum
+# @SchemaInfoEnum:
#
# Additional SchemaInfo members for meta-type 'enum'.
#
-# @values: the enumeration type's values.
+# @values: the enumeration type's values, in no particular order.
#
# Values of this type are JSON string on the wire.
#
'data': { 'values': ['str'] } }
##
-# @SchemaInfoArray
+# @SchemaInfoArray:
#
# Additional SchemaInfo members for meta-type 'array'.
#
'data': { 'element-type': 'str' } }
##
-# @SchemaInfoObject
+# @SchemaInfoObject:
#
# Additional SchemaInfo members for meta-type 'object'.
#
-# @members: the object type's (non-variant) members.
+# @members: the object type's (non-variant) members, in no particular order.
#
-# @tag: #optional the name of the member serving as type tag.
+# @tag: the name of the member serving as type tag.
# An element of @members with this name must exist.
#
-# @variants: #optional variant members, i.e. additional members that
+# @variants: variant members, i.e. additional members that
# depend on the type tag's value. Present exactly when
-# @tag is present.
+# @tag is present. The variants are in no particular order,
+# and may even differ from the order of the values of the
+# enum type of the @tag.
#
# Values of this type are JSON object on the wire.
#
'*variants': [ 'SchemaInfoObjectVariant' ] } }
##
-# @SchemaInfoObjectMember
+# @SchemaInfoObjectMember:
#
# An object member.
#
#
# @type: the name of the member's type.
#
-# @default: #optional default when used as command parameter.
+# @default: default when used as command parameter.
# If absent, the parameter is mandatory.
# If present, the value must be null. The parameter is
# optional, and behavior when it's missing is not specified
# Future extension: if present and non-null, the parameter
# is optional, and defaults to this value.
#
+# @features: names of features associated with the member, in no
+# particular order. (since 5.0)
+#
# Since: 2.5
##
{ 'struct': 'SchemaInfoObjectMember',
- 'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
+ 'data': { 'name': 'str', 'type': 'str', '*default': 'any',
# @default's type must be null or match @type
+ '*features': [ 'str' ] } }
##
-# @SchemaInfoObjectVariant
+# @SchemaInfoObjectVariant:
#
# The variant members for a value of the type tag.
#
'data': { 'case': 'str', 'type': 'str' } }
##
-# @SchemaInfoAlternate
+# @SchemaInfoAlternate:
#
# Additional SchemaInfo members for meta-type 'alternate'.
#
-# @members: the alternate type's members.
+# @members: the alternate type's members, in no particular order.
# The members' wire encoding is distinct, see
-# docs/qapi-code-gen.txt section Alternate types.
+# docs/devel/qapi-code-gen.txt section Alternate types.
#
# On the wire, this can be any of the members.
#
'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
##
-# @SchemaInfoAlternateMember
+# @SchemaInfoAlternateMember:
#
# An alternate member.
#
'data': { 'type': 'str' } }
##
-# @SchemaInfoCommand
+# @SchemaInfoCommand:
#
# Additional SchemaInfo members for meta-type 'command'.
#
#
# @ret-type: the name of the command's result type.
#
-# TODO @success-response (currently irrelevant, because it's QGA, not QMP)
+# @allow-oob: whether the command allows out-of-band execution,
+# defaults to false (Since: 2.12)
+#
+# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoCommand',
- 'data': { 'arg-type': 'str', 'ret-type': 'str' } }
+ 'data': { 'arg-type': 'str', 'ret-type': 'str',
+ '*allow-oob': 'bool' } }
##
-# @SchemaInfoEvent
+# @SchemaInfoEvent:
#
# Additional SchemaInfo members for meta-type 'event'.
#
projects / mirror_qemu.git / blobdiff