qapi/introspect.json - qemu - Git at Google

 # -*- Mode: Python -*-
 # vim: filetype=python
 #
 # Copyright (C) 2015 Red Hat, Inc.
 #
 # Authors:
 #  Markus Armbruster <armbru@redhat.com>
 #
 # This work is licensed under the terms of the GNU GPL, version 2 or later.
 # See the COPYING file in the top-level directory.

 ##
 # = 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
 # events are available in this QEMU, and their parameters and results.
 #
 # However, the SchemaInfo can't reflect all the rules and restrictions
 # that apply to QMP.  It's interface introspection (figuring out
 # 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, ...
 #
 #     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.
 #
 # Since: 2.5
 ##
 { 'command': 'query-qmp-schema',
   'returns': [ 'SchemaInfo' ],
   'allow-preconfig': true }

 ##
 # @SchemaMetaType:
 #
 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
 # describes.
 #
 # @builtin: a predefined type such as 'int' or 'bool'.
 #
 # @enum: an enumeration type
 #
 # @array: an array type
 #
 # @object: an object type (struct or union)
 #
 # @alternate: an alternate type
 #
 # @command: a QMP command
 #
 # @event: a QMP event
 #
 # Since: 2.5
 ##
 { 'enum': 'SchemaMetaType',
   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
             'command', 'event' ] }

 ##
 # @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, 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)
 #
 # Since: 2.5
 ##
 { 'union': 'SchemaInfo',
   'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
             '*features': [ 'str' ] },
   'discriminator': 'meta-type',
   'data': {
       'builtin': 'SchemaInfoBuiltin',
       'enum': 'SchemaInfoEnum',
       'array': 'SchemaInfoArray',
       'object': 'SchemaInfoObject',
       'alternate': 'SchemaInfoAlternate',
       'command': 'SchemaInfoCommand',
       'event': 'SchemaInfoEvent' } }

 ##
 # @SchemaInfoBuiltin:
 #
 # Additional SchemaInfo members for meta-type 'builtin'.
 #
 # @json-type: the JSON type used for this type on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoBuiltin',
   'data': { 'json-type': 'JSONType' } }

 ##
 # @JSONType:
 #
 # The four primitive and two structured types according to RFC 8259
 # section 1, plus 'int' (split off 'number'), plus the obvious top
 # type 'value'.
 #
 # Since: 2.5
 ##
 { 'enum': 'JSONType',
   'data': [ 'string', 'number', 'int', 'boolean', 'null',
             'object', 'array', 'value' ] }

 ##
 # @SchemaInfoEnum:
 #
 # Additional SchemaInfo members for meta-type 'enum'.
 #
 # @members: the enum type's members, in no particular order (since
 #     6.2).
 #
 # @values: the enumeration type's member names, in no particular
 #     order.  Redundant with @members.  Just for backward
 #     compatibility.
 #
 # Features:
 #
 # @deprecated: Member @values is deprecated.  Use @members instead.
 #
 # Values of this type are JSON string on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoEnum',
   'data': { 'members': [ 'SchemaInfoEnumMember' ],
             'values': { 'type': [ 'str' ],
                         'features': [ 'deprecated' ] } } }

 ##
 # @SchemaInfoEnumMember:
 #
 # An object member.
 #
 # @name: the member's name, as defined in the QAPI schema.
 #
 # @features: names of features associated with the member, in no
 #     particular order.
 #
 # Since: 6.2
 ##
 { 'struct': 'SchemaInfoEnumMember',
   'data': { 'name': 'str', '*features': [ 'str' ] } }

 ##
 # @SchemaInfoArray:
 #
 # Additional SchemaInfo members for meta-type 'array'.
 #
 # @element-type: the array type's element type.
 #
 # Values of this type are JSON array on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoArray',
   'data': { 'element-type': 'str' } }

 ##
 # @SchemaInfoObject:
 #
 # Additional SchemaInfo members for meta-type 'object'.
 #
 # @members: the object type's (non-variant) members, in no particular
 #     order.
 #
 # @tag: the name of the member serving as type tag.  An element of
 #     @members with this name must exist.
 #
 # @variants: variant members, i.e. additional members that depend on
 #     the type tag's value.  Present exactly when @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.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoObject',
   'data': { 'members': [ 'SchemaInfoObjectMember' ],
             '*tag': 'str',
             '*variants': [ 'SchemaInfoObjectVariant' ] } }

 ##
 # @SchemaInfoObjectMember:
 #
 # An object member.
 #
 # @name: the member's name, as defined in the QAPI schema.
 #
 # @type: the name of the member's type.
 #
 # @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 here.  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',
 # @default's type must be null or match @type
             '*features': [ 'str' ] } }

 ##
 # @SchemaInfoObjectVariant:
 #
 # The variant members for a value of the type tag.
 #
 # @case: a value of the type tag.
 #
 # @type: the name of the object type that provides the variant members
 #     when the type tag has value @case.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoObjectVariant',
   'data': { 'case': 'str', 'type': 'str' } }

 ##
 # @SchemaInfoAlternate:
 #
 # Additional SchemaInfo members for meta-type 'alternate'.
 #
 # @members: the alternate type's members, in no particular order.  The
 #     members' wire encoding is distinct, see
 #     :doc:`/devel/qapi-code-gen` section Alternate types.
 #
 # On the wire, this can be any of the members.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoAlternate',
   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }

 ##
 # @SchemaInfoAlternateMember:
 #
 # An alternate member.
 #
 # @type: the name of the member's type.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoAlternateMember',
   'data': { 'type': 'str' } }

 ##
 # @SchemaInfoCommand:
 #
 # Additional SchemaInfo members for meta-type 'command'.
 #
 # @arg-type: the name of the object type that provides the command's
 #     parameters.
 #
 # @ret-type: the name of the command's result type.
 #
 # @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',
             '*allow-oob': 'bool' } }

 ##
 # @SchemaInfoEvent:
 #
 # Additional SchemaInfo members for meta-type 'event'.
 #
 # @arg-type: the name of the object type that provides the event's
 #     parameters.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoEvent',
   'data': { 'arg-type': 'str' } }
	# -- Mode: Python --
	# vim: filetype=python
	#
	# Copyright (C) 2015 Red Hat, Inc.
	#
	# Authors:
	# Markus Armbruster <armbru@redhat.com>
	#
	# This work is licensed under the terms of the GNU GPL, version 2 or later.
	# See the COPYING file in the top-level directory.

	##
	# = 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
	# events are available in this QEMU, and their parameters and results.
	#
	# However, the SchemaInfo can't reflect all the rules and restrictions
	# that apply to QMP. It's interface introspection (figuring out
	# 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, ...
	#
	# 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.
	#
	# Since: 2.5
	##
	{ 'command': 'query-qmp-schema',
	'returns': [ 'SchemaInfo' ],
	'allow-preconfig': true }

	##
	# @SchemaMetaType:
	#
	# This is a @SchemaInfo's meta type, i.e. the kind of entity it
	# describes.
	#
	# @builtin: a predefined type such as 'int' or 'bool'.
	#
	# @enum: an enumeration type
	#
	# @array: an array type
	#
	# @object: an object type (struct or union)
	#
	# @alternate: an alternate type
	#
	# @command: a QMP command
	#
	# @event: a QMP event
	#
	# Since: 2.5
	##
	{ 'enum': 'SchemaMetaType',
	'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
	'command', 'event' ] }

	##
	# @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, 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)
	#
	# Since: 2.5
	##
	{ 'union': 'SchemaInfo',
	'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
	'*features': [ 'str' ] },
	'discriminator': 'meta-type',
	'data': {
	'builtin': 'SchemaInfoBuiltin',
	'enum': 'SchemaInfoEnum',
	'array': 'SchemaInfoArray',
	'object': 'SchemaInfoObject',
	'alternate': 'SchemaInfoAlternate',
	'command': 'SchemaInfoCommand',
	'event': 'SchemaInfoEvent' } }

	##
	# @SchemaInfoBuiltin:
	#
	# Additional SchemaInfo members for meta-type 'builtin'.
	#
	# @json-type: the JSON type used for this type on the wire.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoBuiltin',
	'data': { 'json-type': 'JSONType' } }

	##
	# @JSONType:
	#
	# The four primitive and two structured types according to RFC 8259
	# section 1, plus 'int' (split off 'number'), plus the obvious top
	# type 'value'.
	#
	# Since: 2.5
	##
	{ 'enum': 'JSONType',
	'data': [ 'string', 'number', 'int', 'boolean', 'null',
	'object', 'array', 'value' ] }

	##
	# @SchemaInfoEnum:
	#
	# Additional SchemaInfo members for meta-type 'enum'.
	#
	# @members: the enum type's members, in no particular order (since
	# 6.2).
	#
	# @values: the enumeration type's member names, in no particular
	# order. Redundant with @members. Just for backward
	# compatibility.
	#
	# Features:
	#
	# @deprecated: Member @values is deprecated. Use @members instead.
	#
	# Values of this type are JSON string on the wire.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoEnum',
	'data': { 'members': [ 'SchemaInfoEnumMember' ],
	'values': { 'type': [ 'str' ],
	'features': [ 'deprecated' ] } } }

	##
	# @SchemaInfoEnumMember:
	#
	# An object member.
	#
	# @name: the member's name, as defined in the QAPI schema.
	#
	# @features: names of features associated with the member, in no
	# particular order.
	#
	# Since: 6.2
	##
	{ 'struct': 'SchemaInfoEnumMember',
	'data': { 'name': 'str', '*features': [ 'str' ] } }

	##
	# @SchemaInfoArray:
	#
	# Additional SchemaInfo members for meta-type 'array'.
	#
	# @element-type: the array type's element type.
	#
	# Values of this type are JSON array on the wire.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoArray',
	'data': { 'element-type': 'str' } }

	##
	# @SchemaInfoObject:
	#
	# Additional SchemaInfo members for meta-type 'object'.
	#
	# @members: the object type's (non-variant) members, in no particular
	# order.
	#
	# @tag: the name of the member serving as type tag. An element of
	# @members with this name must exist.
	#
	# @variants: variant members, i.e. additional members that depend on
	# the type tag's value. Present exactly when @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.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoObject',
	'data': { 'members': [ 'SchemaInfoObjectMember' ],
	'*tag': 'str',
	'*variants': [ 'SchemaInfoObjectVariant' ] } }

	##
	# @SchemaInfoObjectMember:
	#
	# An object member.
	#
	# @name: the member's name, as defined in the QAPI schema.
	#
	# @type: the name of the member's type.
	#
	# @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 here. 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',
	# @default's type must be null or match @type
	'*features': [ 'str' ] } }

	##
	# @SchemaInfoObjectVariant:
	#
	# The variant members for a value of the type tag.
	#
	# @case: a value of the type tag.
	#
	# @type: the name of the object type that provides the variant members
	# when the type tag has value @case.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoObjectVariant',
	'data': { 'case': 'str', 'type': 'str' } }

	##
	# @SchemaInfoAlternate:
	#
	# Additional SchemaInfo members for meta-type 'alternate'.
	#
	# @members: the alternate type's members, in no particular order. The
	# members' wire encoding is distinct, see
	# :doc:`/devel/qapi-code-gen` section Alternate types.
	#
	# On the wire, this can be any of the members.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoAlternate',
	'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }

	##
	# @SchemaInfoAlternateMember:
	#
	# An alternate member.
	#
	# @type: the name of the member's type.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoAlternateMember',
	'data': { 'type': 'str' } }

	##
	# @SchemaInfoCommand:
	#
	# Additional SchemaInfo members for meta-type 'command'.
	#
	# @arg-type: the name of the object type that provides the command's
	# parameters.
	#
	# @ret-type: the name of the command's result type.
	#
	# @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',
	'*allow-oob': 'bool' } }

	##
	# @SchemaInfoEvent:
	#
	# Additional SchemaInfo members for meta-type 'event'.
	#
	# @arg-type: the name of the object type that provides the event's
	# parameters.
	#
	# Since: 2.5
	##
	{ 'struct': 'SchemaInfoEvent',
	'data': { 'arg-type': 'str' } }