xref: /qemu/qapi/introspect.json (revision 1d8bda128d2ff1f7e589c90d0ac468b95d260757)
139a18158SMarkus Armbruster# -*- Mode: Python -*-
239a18158SMarkus Armbruster#
339a18158SMarkus Armbruster# QAPI/QMP introspection
439a18158SMarkus Armbruster#
539a18158SMarkus Armbruster# Copyright (C) 2015 Red Hat, Inc.
639a18158SMarkus Armbruster#
739a18158SMarkus Armbruster# Authors:
839a18158SMarkus Armbruster#  Markus Armbruster <armbru@redhat.com>
939a18158SMarkus Armbruster#
1039a18158SMarkus Armbruster# This work is licensed under the terms of the GNU GPL, version 2 or later.
1139a18158SMarkus Armbruster# See the COPYING file in the top-level directory.
1239a18158SMarkus Armbruster
1339a18158SMarkus Armbruster##
145072f7b3SMarc-André Lureau# @query-qmp-schema:
1539a18158SMarkus Armbruster#
1639a18158SMarkus Armbruster# Command query-qmp-schema exposes the QMP wire ABI as an array of
1739a18158SMarkus Armbruster# SchemaInfo.  This lets QMP clients figure out what commands and
1839a18158SMarkus Armbruster# events are available in this QEMU, and their parameters and results.
1939a18158SMarkus Armbruster#
2039a18158SMarkus Armbruster# However, the SchemaInfo can't reflect all the rules and restrictions
2139a18158SMarkus Armbruster# that apply to QMP.  It's interface introspection (figuring out
2239a18158SMarkus Armbruster# what's there), not interface specification.  The specification is in
2339a18158SMarkus Armbruster# the QAPI schema.
2439a18158SMarkus Armbruster#
2539a65e2cSEric Blake# Furthermore, while we strive to keep the QMP wire format
2639a65e2cSEric Blake# backwards-compatible across qemu versions, the introspection output
2739a65e2cSEric Blake# is not guaranteed to have the same stability.  For example, one
2839a65e2cSEric Blake# version of qemu may list an object member as an optional
2939a65e2cSEric Blake# non-variant, while another lists the same member only through the
3039a65e2cSEric Blake# object's variants; or the type of a member may change from a generic
3139a65e2cSEric Blake# string into a specific enum or from one specific type into an
3239a65e2cSEric Blake# alternate that includes the original type alongside something else.
3339a65e2cSEric Blake#
3439a18158SMarkus Armbruster# Returns: array of @SchemaInfo, where each element describes an
3539a18158SMarkus Armbruster# entity in the ABI: command, event, type, ...
3639a18158SMarkus Armbruster#
37f5455044SEric Blake# The order of the various SchemaInfo is unspecified; however, all
38f5455044SEric Blake# names are guaranteed to be unique (no name will be duplicated with
39f5455044SEric Blake# different meta-types).
40f5455044SEric Blake#
4139a18158SMarkus Armbruster# Note: the QAPI schema is also used to help define *internal*
4239a18158SMarkus Armbruster# interfaces, by defining QAPI types.  These are not part of the QMP
4339a18158SMarkus Armbruster# wire ABI, and therefore not returned by this command.
4439a18158SMarkus Armbruster#
4539a18158SMarkus Armbruster# Since: 2.5
4639a18158SMarkus Armbruster##
4739a18158SMarkus Armbruster{ 'command': 'query-qmp-schema',
4839a18158SMarkus Armbruster  'returns': [ 'SchemaInfo' ],
4939a18158SMarkus Armbruster  'gen': false }                # just to simplify qmp_query_json()
5039a18158SMarkus Armbruster
5139a18158SMarkus Armbruster##
525072f7b3SMarc-André Lureau# @SchemaMetaType:
5339a18158SMarkus Armbruster#
5439a18158SMarkus Armbruster# This is a @SchemaInfo's meta type, i.e. the kind of entity it
5539a18158SMarkus Armbruster# describes.
5639a18158SMarkus Armbruster#
5739a18158SMarkus Armbruster# @builtin: a predefined type such as 'int' or 'bool'.
5839a18158SMarkus Armbruster#
5939a18158SMarkus Armbruster# @enum: an enumeration type
6039a18158SMarkus Armbruster#
6139a18158SMarkus Armbruster# @array: an array type
6239a18158SMarkus Armbruster#
6339a18158SMarkus Armbruster# @object: an object type (struct or union)
6439a18158SMarkus Armbruster#
6539a18158SMarkus Armbruster# @alternate: an alternate type
6639a18158SMarkus Armbruster#
6739a18158SMarkus Armbruster# @command: a QMP command
6839a18158SMarkus Armbruster#
6939a18158SMarkus Armbruster# @event: a QMP event
7039a18158SMarkus Armbruster#
7139a18158SMarkus Armbruster# Since: 2.5
7239a18158SMarkus Armbruster##
7339a18158SMarkus Armbruster{ 'enum': 'SchemaMetaType',
7439a18158SMarkus Armbruster  'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
7539a18158SMarkus Armbruster            'command', 'event' ] }
7639a18158SMarkus Armbruster
7739a18158SMarkus Armbruster##
785072f7b3SMarc-André Lureau# @SchemaInfo:
7939a18158SMarkus Armbruster#
8039a18158SMarkus Armbruster# @name: the entity's name, inherited from @base.
815807ff88SMarc-André Lureau#        The SchemaInfo is always referenced by this name.
821a9a507bSMarkus Armbruster#        Commands and events have the name defined in the QAPI schema.
831a9a507bSMarkus Armbruster#        Unlike command and event names, type names are not part of
841a9a507bSMarkus Armbruster#        the wire ABI.  Consequently, type names are meaningless
85f5455044SEric Blake#        strings here, although they are still guaranteed unique
86f5455044SEric Blake#        regardless of @meta-type.
8739a18158SMarkus Armbruster#
8839a18158SMarkus Armbruster# @meta-type: the entity's meta type, inherited from @base.
8939a18158SMarkus Armbruster#
9039a18158SMarkus Armbruster# Additional members depend on the value of @meta-type.
9139a18158SMarkus Armbruster#
9239a18158SMarkus Armbruster# Since: 2.5
9339a18158SMarkus Armbruster##
9439a18158SMarkus Armbruster{ 'union': 'SchemaInfo',
953666a97fSEric Blake  'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' },
9639a18158SMarkus Armbruster  'discriminator': 'meta-type',
9739a18158SMarkus Armbruster  'data': {
9839a18158SMarkus Armbruster      'builtin': 'SchemaInfoBuiltin',
9939a18158SMarkus Armbruster      'enum': 'SchemaInfoEnum',
10039a18158SMarkus Armbruster      'array': 'SchemaInfoArray',
10139a18158SMarkus Armbruster      'object': 'SchemaInfoObject',
10239a18158SMarkus Armbruster      'alternate': 'SchemaInfoAlternate',
10339a18158SMarkus Armbruster      'command': 'SchemaInfoCommand',
10439a18158SMarkus Armbruster      'event': 'SchemaInfoEvent' } }
10539a18158SMarkus Armbruster
10639a18158SMarkus Armbruster##
1075072f7b3SMarc-André Lureau# @SchemaInfoBuiltin:
10839a18158SMarkus Armbruster#
10939a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'builtin'.
11039a18158SMarkus Armbruster#
11139a18158SMarkus Armbruster# @json-type: the JSON type used for this type on the wire.
11239a18158SMarkus Armbruster#
11339a18158SMarkus Armbruster# Since: 2.5
11439a18158SMarkus Armbruster##
11539a18158SMarkus Armbruster{ 'struct': 'SchemaInfoBuiltin',
11639a18158SMarkus Armbruster  'data': { 'json-type': 'JSONType' } }
11739a18158SMarkus Armbruster
11839a18158SMarkus Armbruster##
1195072f7b3SMarc-André Lureau# @JSONType:
12039a18158SMarkus Armbruster#
12139a18158SMarkus Armbruster# The four primitive and two structured types according to RFC 7159
12239a18158SMarkus Armbruster# section 1, plus 'int' (split off 'number'), plus the obvious top
12339a18158SMarkus Armbruster# type 'value'.
12439a18158SMarkus Armbruster#
12539a18158SMarkus Armbruster# Since: 2.5
12639a18158SMarkus Armbruster##
12739a18158SMarkus Armbruster{ 'enum': 'JSONType',
12839a18158SMarkus Armbruster  'data': [ 'string', 'number', 'int', 'boolean', 'null',
12939a18158SMarkus Armbruster            'object', 'array', 'value' ] }
13039a18158SMarkus Armbruster
13139a18158SMarkus Armbruster##
1325072f7b3SMarc-André Lureau# @SchemaInfoEnum:
13339a18158SMarkus Armbruster#
13439a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'enum'.
13539a18158SMarkus Armbruster#
136f5455044SEric Blake# @values: the enumeration type's values, in no particular order.
13739a18158SMarkus Armbruster#
13839a18158SMarkus Armbruster# Values of this type are JSON string on the wire.
13939a18158SMarkus Armbruster#
14039a18158SMarkus Armbruster# Since: 2.5
14139a18158SMarkus Armbruster##
14239a18158SMarkus Armbruster{ 'struct': 'SchemaInfoEnum',
14339a18158SMarkus Armbruster  'data': { 'values': ['str'] } }
14439a18158SMarkus Armbruster
14539a18158SMarkus Armbruster##
1465072f7b3SMarc-André Lureau# @SchemaInfoArray:
14739a18158SMarkus Armbruster#
14839a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'array'.
14939a18158SMarkus Armbruster#
15039a18158SMarkus Armbruster# @element-type: the array type's element type.
15139a18158SMarkus Armbruster#
15239a18158SMarkus Armbruster# Values of this type are JSON array on the wire.
15339a18158SMarkus Armbruster#
15439a18158SMarkus Armbruster# Since: 2.5
15539a18158SMarkus Armbruster##
15639a18158SMarkus Armbruster{ 'struct': 'SchemaInfoArray',
15739a18158SMarkus Armbruster  'data': { 'element-type': 'str' } }
15839a18158SMarkus Armbruster
15939a18158SMarkus Armbruster##
1605072f7b3SMarc-André Lureau# @SchemaInfoObject:
16139a18158SMarkus Armbruster#
16239a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'object'.
16339a18158SMarkus Armbruster#
164f5455044SEric Blake# @members: the object type's (non-variant) members, in no particular order.
16539a18158SMarkus Armbruster#
166*1d8bda12SMarkus Armbruster# @tag: the name of the member serving as type tag.
16739a18158SMarkus Armbruster#       An element of @members with this name must exist.
16839a18158SMarkus Armbruster#
169*1d8bda12SMarkus Armbruster# @variants: variant members, i.e. additional members that
17039a18158SMarkus Armbruster#            depend on the type tag's value.  Present exactly when
171f5455044SEric Blake#            @tag is present.  The variants are in no particular order,
172f5455044SEric Blake#            and may even differ from the order of the values of the
173f5455044SEric Blake#            enum type of the @tag.
17439a18158SMarkus Armbruster#
17539a18158SMarkus Armbruster# Values of this type are JSON object on the wire.
17639a18158SMarkus Armbruster#
17739a18158SMarkus Armbruster# Since: 2.5
17839a18158SMarkus Armbruster##
17939a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObject',
18039a18158SMarkus Armbruster  'data': { 'members': [ 'SchemaInfoObjectMember' ],
18139a18158SMarkus Armbruster            '*tag': 'str',
18239a18158SMarkus Armbruster            '*variants': [ 'SchemaInfoObjectVariant' ] } }
18339a18158SMarkus Armbruster
18439a18158SMarkus Armbruster##
1855072f7b3SMarc-André Lureau# @SchemaInfoObjectMember:
18639a18158SMarkus Armbruster#
18739a18158SMarkus Armbruster# An object member.
18839a18158SMarkus Armbruster#
18939a18158SMarkus Armbruster# @name: the member's name, as defined in the QAPI schema.
19039a18158SMarkus Armbruster#
19139a18158SMarkus Armbruster# @type: the name of the member's type.
19239a18158SMarkus Armbruster#
193*1d8bda12SMarkus Armbruster# @default: default when used as command parameter.
19439a18158SMarkus Armbruster#           If absent, the parameter is mandatory.
19539a18158SMarkus Armbruster#           If present, the value must be null.  The parameter is
19639a18158SMarkus Armbruster#           optional, and behavior when it's missing is not specified
19739a18158SMarkus Armbruster#           here.
19839a18158SMarkus Armbruster#           Future extension: if present and non-null, the parameter
19939a18158SMarkus Armbruster#           is optional, and defaults to this value.
20039a18158SMarkus Armbruster#
20139a18158SMarkus Armbruster# Since: 2.5
20239a18158SMarkus Armbruster##
20339a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObjectMember',
20439a18158SMarkus Armbruster  'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
20539a18158SMarkus Armbruster# @default's type must be null or match @type
20639a18158SMarkus Armbruster
20739a18158SMarkus Armbruster##
2085072f7b3SMarc-André Lureau# @SchemaInfoObjectVariant:
20939a18158SMarkus Armbruster#
21039a18158SMarkus Armbruster# The variant members for a value of the type tag.
21139a18158SMarkus Armbruster#
21239a18158SMarkus Armbruster# @case: a value of the type tag.
21339a18158SMarkus Armbruster#
21439a18158SMarkus Armbruster# @type: the name of the object type that provides the variant members
21539a18158SMarkus Armbruster#        when the type tag has value @case.
21639a18158SMarkus Armbruster#
21739a18158SMarkus Armbruster# Since: 2.5
21839a18158SMarkus Armbruster##
21939a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObjectVariant',
22039a18158SMarkus Armbruster  'data': { 'case': 'str', 'type': 'str' } }
22139a18158SMarkus Armbruster
22239a18158SMarkus Armbruster##
2235072f7b3SMarc-André Lureau# @SchemaInfoAlternate:
22439a18158SMarkus Armbruster#
22539a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'alternate'.
22639a18158SMarkus Armbruster#
227f5455044SEric Blake# @members: the alternate type's members, in no particular order.
22839a18158SMarkus Armbruster#           The members' wire encoding is distinct, see
22939a18158SMarkus Armbruster#           docs/qapi-code-gen.txt section Alternate types.
23039a18158SMarkus Armbruster#
23139a18158SMarkus Armbruster# On the wire, this can be any of the members.
23239a18158SMarkus Armbruster#
23339a18158SMarkus Armbruster# Since: 2.5
23439a18158SMarkus Armbruster##
23539a18158SMarkus Armbruster{ 'struct': 'SchemaInfoAlternate',
23639a18158SMarkus Armbruster  'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
23739a18158SMarkus Armbruster
23839a18158SMarkus Armbruster##
2395072f7b3SMarc-André Lureau# @SchemaInfoAlternateMember:
24039a18158SMarkus Armbruster#
24139a18158SMarkus Armbruster# An alternate member.
24239a18158SMarkus Armbruster#
24339a18158SMarkus Armbruster# @type: the name of the member's type.
24439a18158SMarkus Armbruster#
24539a18158SMarkus Armbruster# Since: 2.5
24639a18158SMarkus Armbruster##
24739a18158SMarkus Armbruster{ 'struct': 'SchemaInfoAlternateMember',
24839a18158SMarkus Armbruster  'data': { 'type': 'str' } }
24939a18158SMarkus Armbruster
25039a18158SMarkus Armbruster##
2515072f7b3SMarc-André Lureau# @SchemaInfoCommand:
25239a18158SMarkus Armbruster#
25339a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'command'.
25439a18158SMarkus Armbruster#
25539a18158SMarkus Armbruster# @arg-type: the name of the object type that provides the command's
25639a18158SMarkus Armbruster#            parameters.
25739a18158SMarkus Armbruster#
25839a18158SMarkus Armbruster# @ret-type: the name of the command's result type.
25939a18158SMarkus Armbruster#
260e22da431SMarc-André Lureau# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
26139a18158SMarkus Armbruster#
26239a18158SMarkus Armbruster# Since: 2.5
26339a18158SMarkus Armbruster##
26439a18158SMarkus Armbruster{ 'struct': 'SchemaInfoCommand',
26539a18158SMarkus Armbruster  'data': { 'arg-type': 'str', 'ret-type': 'str' } }
26639a18158SMarkus Armbruster
26739a18158SMarkus Armbruster##
2685072f7b3SMarc-André Lureau# @SchemaInfoEvent:
26939a18158SMarkus Armbruster#
27039a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'event'.
27139a18158SMarkus Armbruster#
27239a18158SMarkus Armbruster# @arg-type: the name of the object type that provides the event's
27339a18158SMarkus Armbruster#            parameters.
27439a18158SMarkus Armbruster#
27539a18158SMarkus Armbruster# Since: 2.5
27639a18158SMarkus Armbruster##
27739a18158SMarkus Armbruster{ 'struct': 'SchemaInfoEvent',
27839a18158SMarkus Armbruster  'data': { 'arg-type': 'str' } }
279