mirror of
https://gitlab.com/qemu-project/qemu
synced 2024-09-06 18:05:37 +00:00
![Markus Armbruster](/assets/img/avatar_default.png)
Documentation generated for SchemaInfo looks like
The members of "SchemaInfoBuiltin" when "meta-type" is ""builtin""
The members of "SchemaInfoEnum" when "meta-type" is ""enum""
The members of "SchemaInfoArray" when "meta-type" is ""array""
The members of "SchemaInfoObject" when "meta-type" is ""object""
The members of "SchemaInfoAlternate" when "meta-type" is ""alternate""
The members of "SchemaInfoCommand" when "meta-type" is ""command""
The members of "SchemaInfoEvent" when "meta-type" is ""event""
Additional members depend on the value of "meta-type".
The last line became redundant when commit 88f63467c5
(qapi2texi:
Generate reference to base type members) added the lines preceding it.
Drop it.
BlockdevOptions has the same issue. Drop
Remaining options are determined by the block driver.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
317 lines
8.4 KiB
Python
317 lines
8.4 KiB
Python
# -*- 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' } }
|