blob: b041b02ba8c5036f90d94f08f4b7ac193b048a60 [file] [log] [blame]
Markus Armbruster39a18152015-09-16 13:06:28 +02001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Markus Armbruster39a18152015-09-16 13:06:28 +02003#
Markus Armbruster39a18152015-09-16 13:06:28 +02004# Copyright (C) 2015 Red Hat, Inc.
5#
6# Authors:
7# Markus Armbruster <armbru@redhat.com>
8#
9# This work is licensed under the terms of the GNU GPL, version 2 or later.
10# See the COPYING file in the top-level directory.
11
12##
Markus Armbrustera885cd32017-08-24 21:13:54 +020013# = QMP introspection
14##
15
16##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040017# @query-qmp-schema:
Markus Armbruster39a18152015-09-16 13:06:28 +020018#
19# Command query-qmp-schema exposes the QMP wire ABI as an array of
20# SchemaInfo. This lets QMP clients figure out what commands and
21# events are available in this QEMU, and their parameters and results.
22#
23# However, the SchemaInfo can't reflect all the rules and restrictions
24# that apply to QMP. It's interface introspection (figuring out
25# what's there), not interface specification. The specification is in
26# the QAPI schema.
27#
Eric Blake39a65e22015-11-11 10:50:02 -070028# Furthermore, while we strive to keep the QMP wire format
29# backwards-compatible across qemu versions, the introspection output
30# is not guaranteed to have the same stability. For example, one
31# version of qemu may list an object member as an optional
32# non-variant, while another lists the same member only through the
33# object's variants; or the type of a member may change from a generic
34# string into a specific enum or from one specific type into an
35# alternate that includes the original type alongside something else.
36#
Markus Armbruster39a18152015-09-16 13:06:28 +020037# Returns: array of @SchemaInfo, where each element describes an
Markus Armbrustera937b6a2023-04-28 12:54:29 +020038# entity in the ABI: command, event, type, ...
Markus Armbruster39a18152015-09-16 13:06:28 +020039#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020040# The order of the various SchemaInfo is unspecified; however, all
41# names are guaranteed to be unique (no name will be duplicated
42# with different meta-types).
Eric Blakef5455042015-11-05 23:35:36 -070043#
Markus Armbruster39a18152015-09-16 13:06:28 +020044# Note: the QAPI schema is also used to help define *internal*
Markus Armbrustera937b6a2023-04-28 12:54:29 +020045# interfaces, by defining QAPI types. These are not part of the
46# QMP wire ABI, and therefore not returned by this command.
Markus Armbruster39a18152015-09-16 13:06:28 +020047#
48# Since: 2.5
49##
50{ 'command': 'query-qmp-schema',
51 'returns': [ 'SchemaInfo' ],
Markus Armbruster624fa802021-03-18 16:55:14 +010052 'allow-preconfig': true }
Markus Armbruster39a18152015-09-16 13:06:28 +020053
54##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040055# @SchemaMetaType:
Markus Armbruster39a18152015-09-16 13:06:28 +020056#
57# This is a @SchemaInfo's meta type, i.e. the kind of entity it
58# describes.
59#
60# @builtin: a predefined type such as 'int' or 'bool'.
61#
62# @enum: an enumeration type
63#
64# @array: an array type
65#
66# @object: an object type (struct or union)
67#
68# @alternate: an alternate type
69#
70# @command: a QMP command
71#
72# @event: a QMP event
73#
74# Since: 2.5
75##
76{ 'enum': 'SchemaMetaType',
77 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
78 'command', 'event' ] }
79
80##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040081# @SchemaInfo:
Markus Armbruster39a18152015-09-16 13:06:28 +020082#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020083# @name: the entity's name, inherited from @base. The SchemaInfo is
84# always referenced by this name. Commands and events have the
85# name defined in the QAPI schema. Unlike command and event
86# names, type names are not part of the wire ABI. Consequently,
87# type names are meaningless strings here, although they are still
88# guaranteed unique regardless of @meta-type.
Markus Armbruster39a18152015-09-16 13:06:28 +020089#
Markus Armbruster39a18152015-09-16 13:06:28 +020090# @meta-type: the entity's meta type, inherited from @base.
91#
Markus Armbruster013b4ef2020-03-17 12:54:37 +010092# @features: names of features associated with the entity, in no
Markus Armbrustera937b6a2023-04-28 12:54:29 +020093# particular order. (since 4.1 for object types, 4.2 for
94# commands, 5.0 for the rest)
Markus Armbruster013b4ef2020-03-17 12:54:37 +010095#
Markus Armbruster39a18152015-09-16 13:06:28 +020096# Since: 2.5
97##
98{ 'union': 'SchemaInfo',
Markus Armbruster013b4ef2020-03-17 12:54:37 +010099 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
100 '*features': [ 'str' ] },
Markus Armbruster39a18152015-09-16 13:06:28 +0200101 'discriminator': 'meta-type',
102 'data': {
103 'builtin': 'SchemaInfoBuiltin',
104 'enum': 'SchemaInfoEnum',
105 'array': 'SchemaInfoArray',
106 'object': 'SchemaInfoObject',
107 'alternate': 'SchemaInfoAlternate',
108 'command': 'SchemaInfoCommand',
109 'event': 'SchemaInfoEvent' } }
110
111##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400112# @SchemaInfoBuiltin:
Markus Armbruster39a18152015-09-16 13:06:28 +0200113#
114# Additional SchemaInfo members for meta-type 'builtin'.
115#
116# @json-type: the JSON type used for this type on the wire.
117#
118# Since: 2.5
119##
120{ 'struct': 'SchemaInfoBuiltin',
121 'data': { 'json-type': 'JSONType' } }
122
123##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400124# @JSONType:
Markus Armbruster39a18152015-09-16 13:06:28 +0200125#
Markus Armbruster37aded92018-08-23 18:40:25 +0200126# The four primitive and two structured types according to RFC 8259
Markus Armbruster39a18152015-09-16 13:06:28 +0200127# section 1, plus 'int' (split off 'number'), plus the obvious top
128# type 'value'.
129#
130# Since: 2.5
131##
132{ 'enum': 'JSONType',
133 'data': [ 'string', 'number', 'int', 'boolean', 'null',
134 'object', 'array', 'value' ] }
135
136##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400137# @SchemaInfoEnum:
Markus Armbruster39a18152015-09-16 13:06:28 +0200138#
139# Additional SchemaInfo members for meta-type 'enum'.
140#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200141# @members: the enum type's members, in no particular order (since
142# 6.2).
Markus Armbruster75ecee72021-10-25 06:24:01 +0200143#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200144# @values: the enumeration type's member names, in no particular
145# order. Redundant with @members. Just for backward
146# compatibility.
Markus Armbruster75ecee72021-10-25 06:24:01 +0200147#
148# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200149#
Markus Armbruster75ecee72021-10-25 06:24:01 +0200150# @deprecated: Member @values is deprecated. Use @members instead.
Markus Armbruster39a18152015-09-16 13:06:28 +0200151#
152# Values of this type are JSON string on the wire.
153#
154# Since: 2.5
155##
156{ 'struct': 'SchemaInfoEnum',
Markus Armbruster75ecee72021-10-25 06:24:01 +0200157 'data': { 'members': [ 'SchemaInfoEnumMember' ],
158 'values': { 'type': [ 'str' ],
159 'features': [ 'deprecated' ] } } }
160
161##
162# @SchemaInfoEnumMember:
163#
164# An object member.
165#
166# @name: the member's name, as defined in the QAPI schema.
167#
Markus Armbrusterb6c18752021-10-25 06:24:02 +0200168# @features: names of features associated with the member, in no
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200169# particular order.
Markus Armbrusterb6c18752021-10-25 06:24:02 +0200170#
Markus Armbruster75ecee72021-10-25 06:24:01 +0200171# Since: 6.2
172##
173{ 'struct': 'SchemaInfoEnumMember',
Markus Armbrusterb6c18752021-10-25 06:24:02 +0200174 'data': { 'name': 'str', '*features': [ 'str' ] } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200175
176##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400177# @SchemaInfoArray:
Markus Armbruster39a18152015-09-16 13:06:28 +0200178#
179# Additional SchemaInfo members for meta-type 'array'.
180#
181# @element-type: the array type's element type.
182#
183# Values of this type are JSON array on the wire.
184#
185# Since: 2.5
186##
187{ 'struct': 'SchemaInfoArray',
188 'data': { 'element-type': 'str' } }
189
190##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400191# @SchemaInfoObject:
Markus Armbruster39a18152015-09-16 13:06:28 +0200192#
193# Additional SchemaInfo members for meta-type 'object'.
194#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200195# @members: the object type's (non-variant) members, in no particular
196# order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200197#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200198# @tag: the name of the member serving as type tag. An element of
199# @members with this name must exist.
Markus Armbruster39a18152015-09-16 13:06:28 +0200200#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200201# @variants: variant members, i.e. additional members that depend on
202# the type tag's value. Present exactly when @tag is present.
203# The variants are in no particular order, and may even differ
204# from the order of the values of the enum type of the @tag.
Markus Armbruster39a18152015-09-16 13:06:28 +0200205#
206# Values of this type are JSON object on the wire.
207#
208# Since: 2.5
209##
210{ 'struct': 'SchemaInfoObject',
211 'data': { 'members': [ 'SchemaInfoObjectMember' ],
212 '*tag': 'str',
Markus Armbruster013b4ef2020-03-17 12:54:37 +0100213 '*variants': [ 'SchemaInfoObjectVariant' ] } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200214
215##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400216# @SchemaInfoObjectMember:
Markus Armbruster39a18152015-09-16 13:06:28 +0200217#
218# An object member.
219#
220# @name: the member's name, as defined in the QAPI schema.
221#
222# @type: the name of the member's type.
223#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200224# @default: default when used as command parameter. If absent, the
225# parameter is mandatory. If present, the value must be null.
226# The parameter is optional, and behavior when it's missing is not
227# specified here. Future extension: if present and non-null, the
228# parameter is optional, and defaults to this value.
Markus Armbruster39a18152015-09-16 13:06:28 +0200229#
Markus Armbruster84ab0082020-03-17 12:54:45 +0100230# @features: names of features associated with the member, in no
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200231# particular order. (since 5.0)
Markus Armbruster84ab0082020-03-17 12:54:45 +0100232#
Markus Armbruster39a18152015-09-16 13:06:28 +0200233# Since: 2.5
234##
235{ 'struct': 'SchemaInfoObjectMember',
Markus Armbruster84ab0082020-03-17 12:54:45 +0100236 'data': { 'name': 'str', 'type': 'str', '*default': 'any',
Markus Armbruster39a18152015-09-16 13:06:28 +0200237# @default's type must be null or match @type
Markus Armbruster84ab0082020-03-17 12:54:45 +0100238 '*features': [ 'str' ] } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200239
240##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400241# @SchemaInfoObjectVariant:
Markus Armbruster39a18152015-09-16 13:06:28 +0200242#
243# The variant members for a value of the type tag.
244#
245# @case: a value of the type tag.
246#
247# @type: the name of the object type that provides the variant members
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200248# when the type tag has value @case.
Markus Armbruster39a18152015-09-16 13:06:28 +0200249#
250# Since: 2.5
251##
252{ 'struct': 'SchemaInfoObjectVariant',
253 'data': { 'case': 'str', 'type': 'str' } }
254
255##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400256# @SchemaInfoAlternate:
Markus Armbruster39a18152015-09-16 13:06:28 +0200257#
258# Additional SchemaInfo members for meta-type 'alternate'.
259#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200260# @members: the alternate type's members, in no particular order. The
Markus Armbruster7cbdabb2024-01-20 10:53:24 +0100261# members' wire encoding is distinct, see
262# :doc:`/devel/qapi-code-gen` section Alternate types.
Markus Armbruster39a18152015-09-16 13:06:28 +0200263#
264# On the wire, this can be any of the members.
265#
266# Since: 2.5
267##
268{ 'struct': 'SchemaInfoAlternate',
269 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
270
271##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400272# @SchemaInfoAlternateMember:
Markus Armbruster39a18152015-09-16 13:06:28 +0200273#
274# An alternate member.
275#
276# @type: the name of the member's type.
277#
278# Since: 2.5
279##
280{ 'struct': 'SchemaInfoAlternateMember',
281 'data': { 'type': 'str' } }
282
283##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400284# @SchemaInfoCommand:
Markus Armbruster39a18152015-09-16 13:06:28 +0200285#
286# Additional SchemaInfo members for meta-type 'command'.
287#
288# @arg-type: the name of the object type that provides the command's
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200289# parameters.
Markus Armbruster39a18152015-09-16 13:06:28 +0200290#
291# @ret-type: the name of the command's result type.
292#
Markus Armbruster25b1ef32018-07-18 11:05:57 +0200293# @allow-oob: whether the command allows out-of-band execution,
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200294# defaults to false (Since: 2.12)
Peter Xu876c6752018-03-09 17:00:00 +0800295#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200296# TODO: @success-response (currently irrelevant, because it's QGA, not
297# QMP)
Markus Armbruster39a18152015-09-16 13:06:28 +0200298#
299# Since: 2.5
300##
301{ 'struct': 'SchemaInfoCommand',
Peter Xu876c6752018-03-09 17:00:00 +0800302 'data': { 'arg-type': 'str', 'ret-type': 'str',
Markus Armbruster013b4ef2020-03-17 12:54:37 +0100303 '*allow-oob': 'bool' } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200304
305##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400306# @SchemaInfoEvent:
Markus Armbruster39a18152015-09-16 13:06:28 +0200307#
308# Additional SchemaInfo members for meta-type 'event'.
309#
310# @arg-type: the name of the object type that provides the event's
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200311# parameters.
Markus Armbruster39a18152015-09-16 13:06:28 +0200312#
313# Since: 2.5
314##
315{ 'struct': 'SchemaInfoEvent',
316 'data': { 'arg-type': 'str' } }