blob: 1dbaef56eb2c0a8401d8ea579b9125799d892459 [file] [log] [blame]
Markus Armbruster39a18152015-09-16 13:06:28 +02001# -*- Mode: Python -*-
2#
3# QAPI/QMP introspection
4#
5# Copyright (C) 2015 Red Hat, Inc.
6#
7# Authors:
8# Markus Armbruster <armbru@redhat.com>
9#
10# This work is licensed under the terms of the GNU GPL, version 2 or later.
11# See the COPYING file in the top-level directory.
12
13##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040014# @query-qmp-schema:
Markus Armbruster39a18152015-09-16 13:06:28 +020015#
16# Command query-qmp-schema exposes the QMP wire ABI as an array of
17# SchemaInfo. This lets QMP clients figure out what commands and
18# events are available in this QEMU, and their parameters and results.
19#
20# However, the SchemaInfo can't reflect all the rules and restrictions
21# that apply to QMP. It's interface introspection (figuring out
22# what's there), not interface specification. The specification is in
23# the QAPI schema.
24#
Eric Blake39a65e22015-11-11 10:50:02 -070025# Furthermore, while we strive to keep the QMP wire format
26# backwards-compatible across qemu versions, the introspection output
27# is not guaranteed to have the same stability. For example, one
28# version of qemu may list an object member as an optional
29# non-variant, while another lists the same member only through the
30# object's variants; or the type of a member may change from a generic
31# string into a specific enum or from one specific type into an
32# alternate that includes the original type alongside something else.
33#
Markus Armbruster39a18152015-09-16 13:06:28 +020034# Returns: array of @SchemaInfo, where each element describes an
35# entity in the ABI: command, event, type, ...
36#
Eric Blakef5455042015-11-05 23:35:36 -070037# The order of the various SchemaInfo is unspecified; however, all
38# names are guaranteed to be unique (no name will be duplicated with
39# different meta-types).
40#
Markus Armbruster39a18152015-09-16 13:06:28 +020041# Note: the QAPI schema is also used to help define *internal*
42# interfaces, by defining QAPI types. These are not part of the QMP
43# wire ABI, and therefore not returned by this command.
44#
45# Since: 2.5
46##
47{ 'command': 'query-qmp-schema',
48 'returns': [ 'SchemaInfo' ],
49 'gen': false } # just to simplify qmp_query_json()
50
51##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040052# @SchemaMetaType:
Markus Armbruster39a18152015-09-16 13:06:28 +020053#
54# This is a @SchemaInfo's meta type, i.e. the kind of entity it
55# describes.
56#
57# @builtin: a predefined type such as 'int' or 'bool'.
58#
59# @enum: an enumeration type
60#
61# @array: an array type
62#
63# @object: an object type (struct or union)
64#
65# @alternate: an alternate type
66#
67# @command: a QMP command
68#
69# @event: a QMP event
70#
71# Since: 2.5
72##
73{ 'enum': 'SchemaMetaType',
74 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
75 'command', 'event' ] }
76
77##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040078# @SchemaInfo:
Markus Armbruster39a18152015-09-16 13:06:28 +020079#
80# @name: the entity's name, inherited from @base.
Marc-André Lureau5807ff82017-01-13 15:41:21 +010081# The SchemaInfo is always referenced by this name.
Markus Armbruster1a9a5072015-09-16 13:06:29 +020082# Commands and events have the name defined in the QAPI schema.
83# Unlike command and event names, type names are not part of
84# the wire ABI. Consequently, type names are meaningless
Eric Blakef5455042015-11-05 23:35:36 -070085# strings here, although they are still guaranteed unique
86# regardless of @meta-type.
Markus Armbruster39a18152015-09-16 13:06:28 +020087#
Markus Armbruster39a18152015-09-16 13:06:28 +020088# @meta-type: the entity's meta type, inherited from @base.
89#
90# Additional members depend on the value of @meta-type.
91#
92# Since: 2.5
93##
94{ 'union': 'SchemaInfo',
Eric Blake3666a972016-03-17 16:48:40 -060095 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' },
Markus Armbruster39a18152015-09-16 13:06:28 +020096 'discriminator': 'meta-type',
97 'data': {
98 'builtin': 'SchemaInfoBuiltin',
99 'enum': 'SchemaInfoEnum',
100 'array': 'SchemaInfoArray',
101 'object': 'SchemaInfoObject',
102 'alternate': 'SchemaInfoAlternate',
103 'command': 'SchemaInfoCommand',
104 'event': 'SchemaInfoEvent' } }
105
106##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400107# @SchemaInfoBuiltin:
Markus Armbruster39a18152015-09-16 13:06:28 +0200108#
109# Additional SchemaInfo members for meta-type 'builtin'.
110#
111# @json-type: the JSON type used for this type on the wire.
112#
113# Since: 2.5
114##
115{ 'struct': 'SchemaInfoBuiltin',
116 'data': { 'json-type': 'JSONType' } }
117
118##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400119# @JSONType:
Markus Armbruster39a18152015-09-16 13:06:28 +0200120#
121# The four primitive and two structured types according to RFC 7159
122# section 1, plus 'int' (split off 'number'), plus the obvious top
123# type 'value'.
124#
125# Since: 2.5
126##
127{ 'enum': 'JSONType',
128 'data': [ 'string', 'number', 'int', 'boolean', 'null',
129 'object', 'array', 'value' ] }
130
131##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400132# @SchemaInfoEnum:
Markus Armbruster39a18152015-09-16 13:06:28 +0200133#
134# Additional SchemaInfo members for meta-type 'enum'.
135#
Eric Blakef5455042015-11-05 23:35:36 -0700136# @values: the enumeration type's values, in no particular order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200137#
138# Values of this type are JSON string on the wire.
139#
140# Since: 2.5
141##
142{ 'struct': 'SchemaInfoEnum',
143 'data': { 'values': ['str'] } }
144
145##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400146# @SchemaInfoArray:
Markus Armbruster39a18152015-09-16 13:06:28 +0200147#
148# Additional SchemaInfo members for meta-type 'array'.
149#
150# @element-type: the array type's element type.
151#
152# Values of this type are JSON array on the wire.
153#
154# Since: 2.5
155##
156{ 'struct': 'SchemaInfoArray',
157 'data': { 'element-type': 'str' } }
158
159##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400160# @SchemaInfoObject:
Markus Armbruster39a18152015-09-16 13:06:28 +0200161#
162# Additional SchemaInfo members for meta-type 'object'.
163#
Eric Blakef5455042015-11-05 23:35:36 -0700164# @members: the object type's (non-variant) members, in no particular order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200165#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100166# @tag: the name of the member serving as type tag.
Markus Armbruster39a18152015-09-16 13:06:28 +0200167# An element of @members with this name must exist.
168#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100169# @variants: variant members, i.e. additional members that
Markus Armbruster39a18152015-09-16 13:06:28 +0200170# depend on the type tag's value. Present exactly when
Eric Blakef5455042015-11-05 23:35:36 -0700171# @tag is present. The variants are in no particular order,
172# and may even differ from the order of the values of the
173# enum type of the @tag.
Markus Armbruster39a18152015-09-16 13:06:28 +0200174#
175# Values of this type are JSON object on the wire.
176#
177# Since: 2.5
178##
179{ 'struct': 'SchemaInfoObject',
180 'data': { 'members': [ 'SchemaInfoObjectMember' ],
181 '*tag': 'str',
182 '*variants': [ 'SchemaInfoObjectVariant' ] } }
183
184##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400185# @SchemaInfoObjectMember:
Markus Armbruster39a18152015-09-16 13:06:28 +0200186#
187# An object member.
188#
189# @name: the member's name, as defined in the QAPI schema.
190#
191# @type: the name of the member's type.
192#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100193# @default: default when used as command parameter.
Markus Armbruster39a18152015-09-16 13:06:28 +0200194# If absent, the parameter is mandatory.
195# If present, the value must be null. The parameter is
196# optional, and behavior when it's missing is not specified
197# here.
198# Future extension: if present and non-null, the parameter
199# is optional, and defaults to this value.
200#
201# Since: 2.5
202##
203{ 'struct': 'SchemaInfoObjectMember',
204 'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
205# @default's type must be null or match @type
206
207##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400208# @SchemaInfoObjectVariant:
Markus Armbruster39a18152015-09-16 13:06:28 +0200209#
210# The variant members for a value of the type tag.
211#
212# @case: a value of the type tag.
213#
214# @type: the name of the object type that provides the variant members
215# when the type tag has value @case.
216#
217# Since: 2.5
218##
219{ 'struct': 'SchemaInfoObjectVariant',
220 'data': { 'case': 'str', 'type': 'str' } }
221
222##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400223# @SchemaInfoAlternate:
Markus Armbruster39a18152015-09-16 13:06:28 +0200224#
225# Additional SchemaInfo members for meta-type 'alternate'.
226#
Eric Blakef5455042015-11-05 23:35:36 -0700227# @members: the alternate type's members, in no particular order.
Markus Armbruster39a18152015-09-16 13:06:28 +0200228# The members' wire encoding is distinct, see
229# docs/qapi-code-gen.txt section Alternate types.
230#
231# On the wire, this can be any of the members.
232#
233# Since: 2.5
234##
235{ 'struct': 'SchemaInfoAlternate',
236 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
237
238##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400239# @SchemaInfoAlternateMember:
Markus Armbruster39a18152015-09-16 13:06:28 +0200240#
241# An alternate member.
242#
243# @type: the name of the member's type.
244#
245# Since: 2.5
246##
247{ 'struct': 'SchemaInfoAlternateMember',
248 'data': { 'type': 'str' } }
249
250##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400251# @SchemaInfoCommand:
Markus Armbruster39a18152015-09-16 13:06:28 +0200252#
253# Additional SchemaInfo members for meta-type 'command'.
254#
255# @arg-type: the name of the object type that provides the command's
256# parameters.
257#
258# @ret-type: the name of the command's result type.
259#
Marc-André Lureaue22da432017-01-13 15:41:17 +0100260# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
Markus Armbruster39a18152015-09-16 13:06:28 +0200261#
262# Since: 2.5
263##
264{ 'struct': 'SchemaInfoCommand',
265 'data': { 'arg-type': 'str', 'ret-type': 'str' } }
266
267##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400268# @SchemaInfoEvent:
Markus Armbruster39a18152015-09-16 13:06:28 +0200269#
270# Additional SchemaInfo members for meta-type 'event'.
271#
272# @arg-type: the name of the object type that provides the event's
273# parameters.
274#
275# Since: 2.5
276##
277{ 'struct': 'SchemaInfoEvent',
278 'data': { 'arg-type': 'str' } }