]> git.proxmox.com Git - mirror_qemu.git/blob - qapi/introspect.json
qapi: Generalize command policy checking
[mirror_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 '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.
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 # @members: the enum type's members, in no particular order
146 # (since 6.2).
147 #
148 # @values: the enumeration type's member names, in no particular order.
149 # Redundant with @members. Just for backward compatibility.
150 #
151 # Features:
152 # @deprecated: Member @values is deprecated. Use @members instead.
153 #
154 # Values of this type are JSON string on the wire.
155 #
156 # Since: 2.5
157 ##
158 { 'struct': 'SchemaInfoEnum',
159 'data': { 'members': [ 'SchemaInfoEnumMember' ],
160 'values': { 'type': [ 'str' ],
161 'features': [ 'deprecated' ] } } }
162
163 ##
164 # @SchemaInfoEnumMember:
165 #
166 # An object member.
167 #
168 # @name: the member's name, as defined in the QAPI schema.
169 #
170 # @features: names of features associated with the member, in no
171 # particular order.
172 #
173 # Since: 6.2
174 ##
175 { 'struct': 'SchemaInfoEnumMember',
176 'data': { 'name': 'str', '*features': [ 'str' ] } }
177
178 ##
179 # @SchemaInfoArray:
180 #
181 # Additional SchemaInfo members for meta-type 'array'.
182 #
183 # @element-type: the array type's element type.
184 #
185 # Values of this type are JSON array on the wire.
186 #
187 # Since: 2.5
188 ##
189 { 'struct': 'SchemaInfoArray',
190 'data': { 'element-type': 'str' } }
191
192 ##
193 # @SchemaInfoObject:
194 #
195 # Additional SchemaInfo members for meta-type 'object'.
196 #
197 # @members: the object type's (non-variant) members, in no particular order.
198 #
199 # @tag: the name of the member serving as type tag.
200 # An element of @members with this name must exist.
201 #
202 # @variants: variant members, i.e. additional members that
203 # depend on the type tag's value. Present exactly when
204 # @tag is present. The variants are in no particular order,
205 # and may even differ from the order of the values of the
206 # enum type of the @tag.
207 #
208 # Values of this type are JSON object on the wire.
209 #
210 # Since: 2.5
211 ##
212 { 'struct': 'SchemaInfoObject',
213 'data': { 'members': [ 'SchemaInfoObjectMember' ],
214 '*tag': 'str',
215 '*variants': [ 'SchemaInfoObjectVariant' ] } }
216
217 ##
218 # @SchemaInfoObjectMember:
219 #
220 # An object member.
221 #
222 # @name: the member's name, as defined in the QAPI schema.
223 #
224 # @type: the name of the member's type.
225 #
226 # @default: default when used as command parameter.
227 # If absent, the parameter is mandatory.
228 # If present, the value must be null. The parameter is
229 # optional, and behavior when it's missing is not specified
230 # here.
231 # Future extension: if present and non-null, the parameter
232 # is optional, and defaults to this value.
233 #
234 # @features: names of features associated with the member, in no
235 # particular order. (since 5.0)
236 #
237 # Since: 2.5
238 ##
239 { 'struct': 'SchemaInfoObjectMember',
240 'data': { 'name': 'str', 'type': 'str', '*default': 'any',
241 # @default's type must be null or match @type
242 '*features': [ 'str' ] } }
243
244 ##
245 # @SchemaInfoObjectVariant:
246 #
247 # The variant members for a value of the type tag.
248 #
249 # @case: a value of the type tag.
250 #
251 # @type: the name of the object type that provides the variant members
252 # when the type tag has value @case.
253 #
254 # Since: 2.5
255 ##
256 { 'struct': 'SchemaInfoObjectVariant',
257 'data': { 'case': 'str', 'type': 'str' } }
258
259 ##
260 # @SchemaInfoAlternate:
261 #
262 # Additional SchemaInfo members for meta-type 'alternate'.
263 #
264 # @members: the alternate type's members, in no particular order.
265 # The members' wire encoding is distinct, see
266 # docs/devel/qapi-code-gen.txt section Alternate types.
267 #
268 # On the wire, this can be any of the members.
269 #
270 # Since: 2.5
271 ##
272 { 'struct': 'SchemaInfoAlternate',
273 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
274
275 ##
276 # @SchemaInfoAlternateMember:
277 #
278 # An alternate member.
279 #
280 # @type: the name of the member's type.
281 #
282 # Since: 2.5
283 ##
284 { 'struct': 'SchemaInfoAlternateMember',
285 'data': { 'type': 'str' } }
286
287 ##
288 # @SchemaInfoCommand:
289 #
290 # Additional SchemaInfo members for meta-type 'command'.
291 #
292 # @arg-type: the name of the object type that provides the command's
293 # parameters.
294 #
295 # @ret-type: the name of the command's result type.
296 #
297 # @allow-oob: whether the command allows out-of-band execution,
298 # defaults to false (Since: 2.12)
299 #
300 # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
301 #
302 # Since: 2.5
303 ##
304 { 'struct': 'SchemaInfoCommand',
305 'data': { 'arg-type': 'str', 'ret-type': 'str',
306 '*allow-oob': 'bool' } }
307
308 ##
309 # @SchemaInfoEvent:
310 #
311 # Additional SchemaInfo members for meta-type 'event'.
312 #
313 # @arg-type: the name of the object type that provides the event's
314 # parameters.
315 #
316 # Since: 2.5
317 ##
318 { 'struct': 'SchemaInfoEvent',
319 'data': { 'arg-type': 'str' } }