blob: 944bb87a20df019bf9cc2976c6b6be96fa49e7b2 [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
Peter Maydell26ec4e52020-02-13 17:56:26 +000038# entity in the ABI: command, event, type, ...
Markus Armbruster39a18152015-09-16 13:06:28 +020039#
Peter Maydell26ec4e52020-02-13 17:56:26 +000040# The order of the various SchemaInfo is unspecified; however, all
41# names are guaranteed to be unique (no name will be duplicated with
42# 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*
Peter Maydell26ec4e52020-02-13 17:56:26 +000045# interfaces, by defining QAPI types. These are not part of the QMP
46# 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' ],
52 'gen': false } # just to simplify qmp_query_json()
53
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#
83# @name: the entity's name, inherited from @base.
Marc-André Lureau5807ff82017-01-13 15:41:21 +010084# The SchemaInfo is always referenced by this name.
Markus Armbruster1a9a5072015-09-16 13:06:29 +020085# Commands and events have the name defined in the QAPI schema.
86# Unlike command and event names, type names are not part of
87# the wire ABI. Consequently, type names are meaningless
Eric Blakef5455042015-11-05 23:35:36 -070088# strings here, although they are still guaranteed unique
89# regardless of @meta-type.
Markus Armbruster39a18152015-09-16 13:06:28 +020090#
Markus Armbruster39a18152015-09-16 13:06:28 +020091# @meta-type: the entity's meta type, inherited from @base.
92#
Markus Armbruster013b4ef2020-03-17 12:54:37 +010093# @features: names of features associated with the entity, in no
94# particular order.
95# (since 4.1 for object types, 4.2 for commands, 5.0 for
96# the rest)
97#
Markus Armbruster39a18152015-09-16 13:06:28 +020098# Additional members depend on the value of @meta-type.
99#
100# Since: 2.5
101##
102{ 'union': 'SchemaInfo',
Markus Armbruster013b4ef2020-03-17 12:54:37 +0100103 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
104 '*features': [ 'str' ] },
Markus Armbruster39a18152015-09-16 13:06:28 +0200105 'discriminator': 'meta-type',
106 'data': {
107 'builtin': 'SchemaInfoBuiltin',
108 'enum': 'SchemaInfoEnum',
109 'array': 'SchemaInfoArray',
110 'object': 'SchemaInfoObject',
111 'alternate': 'SchemaInfoAlternate',
112 'command': 'SchemaInfoCommand',
113 'event': 'SchemaInfoEvent' } }
114
115##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400116# @SchemaInfoBuiltin:
Markus Armbruster39a18152015-09-16 13:06:28 +0200117#
118# Additional SchemaInfo members for meta-type 'builtin'.
119#
120# @json-type: the JSON type used for this type on the wire.
121#
122# Since: 2.5
123##
124{ 'struct': 'SchemaInfoBuiltin',
125 'data': { 'json-type': 'JSONType' } }
126
127##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400128# @JSONType:
Markus Armbruster39a18152015-09-16 13:06:28 +0200129#
Markus Armbruster37aded92018-08-23 18:40:25 +0200130# The four primitive and two structured types according to RFC 8259
Markus Armbruster39a18152015-09-16 13:06:28 +0200131# section 1, plus 'int' (split off 'number'), plus the obvious top
132# type 'value'.
133#
134# Since: 2.5
135##
136{ 'enum': 'JSONType',
137 'data': [ 'string', 'number', 'int', 'boolean', 'null',
138 'object', 'array', 'value' ] }
139
140##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400141# @SchemaInfoEnum:
Markus Armbruster39a18152015-09-16 13:06:28 +0200142#
143# Additional SchemaInfo members for meta-type 'enum'.
144#
Eric Blakef5455042015-11-05 23:35:36 -0700145# @values: the enumeration type's values, in no particular order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200146#
147# Values of this type are JSON string on the wire.
148#
149# Since: 2.5
150##
151{ 'struct': 'SchemaInfoEnum',
152 'data': { 'values': ['str'] } }
153
154##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400155# @SchemaInfoArray:
Markus Armbruster39a18152015-09-16 13:06:28 +0200156#
157# Additional SchemaInfo members for meta-type 'array'.
158#
159# @element-type: the array type's element type.
160#
161# Values of this type are JSON array on the wire.
162#
163# Since: 2.5
164##
165{ 'struct': 'SchemaInfoArray',
166 'data': { 'element-type': 'str' } }
167
168##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400169# @SchemaInfoObject:
Markus Armbruster39a18152015-09-16 13:06:28 +0200170#
171# Additional SchemaInfo members for meta-type 'object'.
172#
Eric Blakef5455042015-11-05 23:35:36 -0700173# @members: the object type's (non-variant) members, in no particular order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200174#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100175# @tag: the name of the member serving as type tag.
Markus Armbruster39a18152015-09-16 13:06:28 +0200176# An element of @members with this name must exist.
177#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100178# @variants: variant members, i.e. additional members that
Markus Armbruster39a18152015-09-16 13:06:28 +0200179# depend on the type tag's value. Present exactly when
Eric Blakef5455042015-11-05 23:35:36 -0700180# @tag is present. The variants are in no particular order,
181# and may even differ from the order of the values of the
182# enum type of the @tag.
Markus Armbruster39a18152015-09-16 13:06:28 +0200183#
184# Values of this type are JSON object on the wire.
185#
186# Since: 2.5
187##
188{ 'struct': 'SchemaInfoObject',
189 'data': { 'members': [ 'SchemaInfoObjectMember' ],
190 '*tag': 'str',
Markus Armbruster013b4ef2020-03-17 12:54:37 +0100191 '*variants': [ 'SchemaInfoObjectVariant' ] } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200192
193##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400194# @SchemaInfoObjectMember:
Markus Armbruster39a18152015-09-16 13:06:28 +0200195#
196# An object member.
197#
198# @name: the member's name, as defined in the QAPI schema.
199#
200# @type: the name of the member's type.
201#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100202# @default: default when used as command parameter.
Markus Armbruster39a18152015-09-16 13:06:28 +0200203# If absent, the parameter is mandatory.
204# If present, the value must be null. The parameter is
205# optional, and behavior when it's missing is not specified
206# here.
207# Future extension: if present and non-null, the parameter
208# is optional, and defaults to this value.
209#
Markus Armbruster84ab0082020-03-17 12:54:45 +0100210# @features: names of features associated with the member, in no
211# particular order. (since 5.0)
212#
Markus Armbruster39a18152015-09-16 13:06:28 +0200213# Since: 2.5
214##
215{ 'struct': 'SchemaInfoObjectMember',
Markus Armbruster84ab0082020-03-17 12:54:45 +0100216 'data': { 'name': 'str', 'type': 'str', '*default': 'any',
Markus Armbruster39a18152015-09-16 13:06:28 +0200217# @default's type must be null or match @type
Markus Armbruster84ab0082020-03-17 12:54:45 +0100218 '*features': [ 'str' ] } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200219
220##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400221# @SchemaInfoObjectVariant:
Markus Armbruster39a18152015-09-16 13:06:28 +0200222#
223# The variant members for a value of the type tag.
224#
225# @case: a value of the type tag.
226#
227# @type: the name of the object type that provides the variant members
228# when the type tag has value @case.
229#
230# Since: 2.5
231##
232{ 'struct': 'SchemaInfoObjectVariant',
233 'data': { 'case': 'str', 'type': 'str' } }
234
235##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400236# @SchemaInfoAlternate:
Markus Armbruster39a18152015-09-16 13:06:28 +0200237#
238# Additional SchemaInfo members for meta-type 'alternate'.
239#
Eric Blakef5455042015-11-05 23:35:36 -0700240# @members: the alternate type's members, in no particular order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200241# The members' wire encoding is distinct, see
Philippe Mathieu-Daudéb3125e72017-07-28 19:46:03 -0300242# docs/devel/qapi-code-gen.txt section Alternate types.
Markus Armbruster39a18152015-09-16 13:06:28 +0200243#
244# On the wire, this can be any of the members.
245#
246# Since: 2.5
247##
248{ 'struct': 'SchemaInfoAlternate',
249 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
250
251##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400252# @SchemaInfoAlternateMember:
Markus Armbruster39a18152015-09-16 13:06:28 +0200253#
254# An alternate member.
255#
256# @type: the name of the member's type.
257#
258# Since: 2.5
259##
260{ 'struct': 'SchemaInfoAlternateMember',
261 'data': { 'type': 'str' } }
262
263##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400264# @SchemaInfoCommand:
Markus Armbruster39a18152015-09-16 13:06:28 +0200265#
266# Additional SchemaInfo members for meta-type 'command'.
267#
268# @arg-type: the name of the object type that provides the command's
269# parameters.
270#
271# @ret-type: the name of the command's result type.
272#
Markus Armbruster25b1ef32018-07-18 11:05:57 +0200273# @allow-oob: whether the command allows out-of-band execution,
274# defaults to false (Since: 2.12)
Peter Xu876c6752018-03-09 17:00:00 +0800275#
Marc-André Lureaue22da432017-01-13 15:41:17 +0100276# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
Markus Armbruster39a18152015-09-16 13:06:28 +0200277#
278# Since: 2.5
279##
280{ 'struct': 'SchemaInfoCommand',
Peter Xu876c6752018-03-09 17:00:00 +0800281 'data': { 'arg-type': 'str', 'ret-type': 'str',
Markus Armbruster013b4ef2020-03-17 12:54:37 +0100282 '*allow-oob': 'bool' } }
Markus Armbruster39a18152015-09-16 13:06:28 +0200283
284##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400285# @SchemaInfoEvent:
Markus Armbruster39a18152015-09-16 13:06:28 +0200286#
287# Additional SchemaInfo members for meta-type 'event'.
288#
289# @arg-type: the name of the object type that provides the event's
290# parameters.
291#
292# Since: 2.5
293##
294{ 'struct': 'SchemaInfoEvent',
295 'data': { 'arg-type': 'str' } }