Merge remote-tracking branch 'remotes/huth-gitlab/tags/pull-request-2020-08-05' into...
[qemu.git] / qapi / introspect.json
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 with
42 #          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 QMP
46 #       wire ABI, and therefore not returned by this command.
47 #
48 # Since: 2.5
49 ##
50 { 'command': 'query-qmp-schema',
51   'returns': [ 'SchemaInfo' ],
52   'gen': false }                # just to simplify qmp_query_json()
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.
84 #        The SchemaInfo is always referenced by this name.
85 #        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
88 #        strings here, although they are still guaranteed unique
89 #        regardless of @meta-type.
90 #
91 # @meta-type: the entity's meta type, inherited from @base.
92 #
93 # @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 #
98 # Additional members depend on the value of @meta-type.
99 #
100 # Since: 2.5
101 ##
102 { 'union': 'SchemaInfo',
103   'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
104             '*features': [ 'str' ] },
105   '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 ##
116 # @SchemaInfoBuiltin:
117 #
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 ##
128 # @JSONType:
129 #
130 # The four primitive and two structured types according to RFC 8259
131 # 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 ##
141 # @SchemaInfoEnum:
142 #
143 # Additional SchemaInfo members for meta-type 'enum'.
144 #
145 # @values: the enumeration type's values, in no particular order.
146 #
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 ##
155 # @SchemaInfoArray:
156 #
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 ##
169 # @SchemaInfoObject:
170 #
171 # Additional SchemaInfo members for meta-type 'object'.
172 #
173 # @members: the object type's (non-variant) members, in no particular order.
174 #
175 # @tag: the name of the member serving as type tag.
176 #       An element of @members with this name must exist.
177 #
178 # @variants: variant members, i.e. additional members that
179 #            depend on the type tag's value.  Present exactly when
180 #            @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.
183 #
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',
191             '*variants': [ 'SchemaInfoObjectVariant' ] } }
192
193 ##
194 # @SchemaInfoObjectMember:
195 #
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 #
202 # @default: default when used as command parameter.
203 #           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 #
210 # @features: names of features associated with the member, in no
211 #            particular order.  (since 5.0)
212 #
213 # Since: 2.5
214 ##
215 { 'struct': 'SchemaInfoObjectMember',
216   'data': { 'name': 'str', 'type': 'str', '*default': 'any',
217 # @default's type must be null or match @type
218             '*features': [ 'str' ] } }
219
220 ##
221 # @SchemaInfoObjectVariant:
222 #
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 ##
236 # @SchemaInfoAlternate:
237 #
238 # Additional SchemaInfo members for meta-type 'alternate'.
239 #
240 # @members: the alternate type's members, in no particular order.
241 #           The members' wire encoding is distinct, see
242 #           docs/devel/qapi-code-gen.txt section Alternate types.
243 #
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 ##
252 # @SchemaInfoAlternateMember:
253 #
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 ##
264 # @SchemaInfoCommand:
265 #
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 #
273 # @allow-oob: whether the command allows out-of-band execution,
274 #             defaults to false (Since: 2.12)
275 #
276 # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
277 #
278 # Since: 2.5
279 ##
280 { 'struct': 'SchemaInfoCommand',
281   'data': { 'arg-type': 'str', 'ret-type': 'str',
282             '*allow-oob': 'bool' } }
283
284 ##
285 # @SchemaInfoEvent:
286 #
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' } }