xref: /openbmc/qemu/qapi/introspect.json (revision 01bed0ff)
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4# 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##
13# = QMP introspection
14##
15
16##
17# @query-qmp-schema:
18#
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#
28# 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#
37# Returns: array of @SchemaInfo, where each element describes an
38#     entity in the ABI: command, event, type, ...
39#
40#     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).
43#
44# .. note:: The QAPI schema is also used to help define *internal*
45#    interfaces, by defining QAPI types.  These are not part of the
46#    QMP wire ABI, and therefore not returned by this command.
47#
48# Since: 2.5
49##
50{ 'command': 'query-qmp-schema',
51  'returns': [ 'SchemaInfo' ],
52  'allow-preconfig': true }
53
54##
55# @SchemaMetaType:
56#
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##
81# @SchemaInfo:
82#
83# @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.
89#
90# @meta-type: the entity's meta type, inherited from @base.
91#
92# @features: names of features associated with the entity, in no
93#     particular order.  (since 4.1 for object types, 4.2 for
94#     commands, 5.0 for the rest)
95#
96# Since: 2.5
97##
98{ 'union': 'SchemaInfo',
99  'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
100            '*features': [ 'str' ] },
101  '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##
112# @SchemaInfoBuiltin:
113#
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##
124# @JSONType:
125#
126# The four primitive and two structured types according to RFC 8259
127# 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##
137# @SchemaInfoEnum:
138#
139# Additional SchemaInfo members for meta-type 'enum'.
140#
141# @members: the enum type's members, in no particular order (since
142#     6.2).
143#
144# @values: the enumeration type's member names, in no particular
145#     order.  Redundant with @members.  Just for backward
146#     compatibility.
147#
148# Features:
149#
150# @deprecated: Member @values is deprecated.  Use @members instead.
151#
152# Values of this type are JSON string on the wire.
153#
154# Since: 2.5
155##
156{ 'struct': 'SchemaInfoEnum',
157  '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#
168# @features: names of features associated with the member, in no
169#     particular order.
170#
171# Since: 6.2
172##
173{ 'struct': 'SchemaInfoEnumMember',
174  'data': { 'name': 'str', '*features': [ 'str' ] } }
175
176##
177# @SchemaInfoArray:
178#
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##
191# @SchemaInfoObject:
192#
193# Additional SchemaInfo members for meta-type 'object'.
194#
195# @members: the object type's (non-variant) members, in no particular
196#     order.
197#
198# @tag: the name of the member serving as type tag.  An element of
199#     @members with this name must exist.
200#
201# @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.
205#
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',
213            '*variants': [ 'SchemaInfoObjectVariant' ] } }
214
215##
216# @SchemaInfoObjectMember:
217#
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#
224# @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.
229#
230# @features: names of features associated with the member, in no
231#     particular order.  (since 5.0)
232#
233# Since: 2.5
234##
235{ 'struct': 'SchemaInfoObjectMember',
236  'data': { 'name': 'str', 'type': 'str', '*default': 'any',
237# @default's type must be null or match @type
238            '*features': [ 'str' ] } }
239
240##
241# @SchemaInfoObjectVariant:
242#
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
248#     when the type tag has value @case.
249#
250# Since: 2.5
251##
252{ 'struct': 'SchemaInfoObjectVariant',
253  'data': { 'case': 'str', 'type': 'str' } }
254
255##
256# @SchemaInfoAlternate:
257#
258# Additional SchemaInfo members for meta-type 'alternate'.
259#
260# @members: the alternate type's members, in no particular order.  The
261#     members' wire encoding is distinct, see
262#     :doc:`/devel/qapi-code-gen` section Alternate types.
263#
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##
272# @SchemaInfoAlternateMember:
273#
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##
284# @SchemaInfoCommand:
285#
286# Additional SchemaInfo members for meta-type 'command'.
287#
288# @arg-type: the name of the object type that provides the command's
289#     parameters.
290#
291# @ret-type: the name of the command's result type.
292#
293# @allow-oob: whether the command allows out-of-band execution,
294#     defaults to false (Since: 2.12)
295#
296# TODO: @success-response (currently irrelevant, because it's QGA, not
297#     QMP)
298#
299# Since: 2.5
300##
301{ 'struct': 'SchemaInfoCommand',
302  'data': { 'arg-type': 'str', 'ret-type': 'str',
303            '*allow-oob': 'bool' } }
304
305##
306# @SchemaInfoEvent:
307#
308# Additional SchemaInfo members for meta-type 'event'.
309#
310# @arg-type: the name of the object type that provides the event's
311#     parameters.
312#
313# Since: 2.5
314##
315{ 'struct': 'SchemaInfoEvent',
316  'data': { 'arg-type': 'str' } }
317