]>
Commit | Line | Data |
---|---|---|
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 | # Additional members depend on the value of @meta-type. | |
97 | # | |
98 | # Since: 2.5 | |
99 | ## | |
100 | { 'union': 'SchemaInfo', | |
101 | 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType', | |
102 | '*features': [ 'str' ] }, | |
103 | 'discriminator': 'meta-type', | |
104 | 'data': { | |
105 | 'builtin': 'SchemaInfoBuiltin', | |
106 | 'enum': 'SchemaInfoEnum', | |
107 | 'array': 'SchemaInfoArray', | |
108 | 'object': 'SchemaInfoObject', | |
109 | 'alternate': 'SchemaInfoAlternate', | |
110 | 'command': 'SchemaInfoCommand', | |
111 | 'event': 'SchemaInfoEvent' } } | |
112 | ||
113 | ## | |
114 | # @SchemaInfoBuiltin: | |
115 | # | |
116 | # Additional SchemaInfo members for meta-type 'builtin'. | |
117 | # | |
118 | # @json-type: the JSON type used for this type on the wire. | |
119 | # | |
120 | # Since: 2.5 | |
121 | ## | |
122 | { 'struct': 'SchemaInfoBuiltin', | |
123 | 'data': { 'json-type': 'JSONType' } } | |
124 | ||
125 | ## | |
126 | # @JSONType: | |
127 | # | |
128 | # The four primitive and two structured types according to RFC 8259 | |
129 | # section 1, plus 'int' (split off 'number'), plus the obvious top | |
130 | # type 'value'. | |
131 | # | |
132 | # Since: 2.5 | |
133 | ## | |
134 | { 'enum': 'JSONType', | |
135 | 'data': [ 'string', 'number', 'int', 'boolean', 'null', | |
136 | 'object', 'array', 'value' ] } | |
137 | ||
138 | ## | |
139 | # @SchemaInfoEnum: | |
140 | # | |
141 | # Additional SchemaInfo members for meta-type 'enum'. | |
142 | # | |
143 | # @members: the enum type's members, in no particular order (since | |
144 | # 6.2). | |
145 | # | |
146 | # @values: the enumeration type's member names, in no particular | |
147 | # order. Redundant with @members. Just for backward | |
148 | # compatibility. | |
149 | # | |
150 | # Features: | |
151 | # | |
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 | |
198 | # order. | |
199 | # | |
200 | # @tag: the name of the member serving as type tag. An element of | |
201 | # @members with this name must exist. | |
202 | # | |
203 | # @variants: variant members, i.e. additional members that depend on | |
204 | # the type tag's value. Present exactly when @tag is present. | |
205 | # The variants are in no particular order, and may even differ | |
206 | # from the order of the values of the 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. If absent, the | |
227 | # parameter is mandatory. If present, the value must be null. | |
228 | # The parameter is optional, and behavior when it's missing is not | |
229 | # specified here. Future extension: if present and non-null, the | |
230 | # parameter is optional, and defaults to this value. | |
231 | # | |
232 | # @features: names of features associated with the member, in no | |
233 | # particular order. (since 5.0) | |
234 | # | |
235 | # Since: 2.5 | |
236 | ## | |
237 | { 'struct': 'SchemaInfoObjectMember', | |
238 | 'data': { 'name': 'str', 'type': 'str', '*default': 'any', | |
239 | # @default's type must be null or match @type | |
240 | '*features': [ 'str' ] } } | |
241 | ||
242 | ## | |
243 | # @SchemaInfoObjectVariant: | |
244 | # | |
245 | # The variant members for a value of the type tag. | |
246 | # | |
247 | # @case: a value of the type tag. | |
248 | # | |
249 | # @type: the name of the object type that provides the variant members | |
250 | # when the type tag has value @case. | |
251 | # | |
252 | # Since: 2.5 | |
253 | ## | |
254 | { 'struct': 'SchemaInfoObjectVariant', | |
255 | 'data': { 'case': 'str', 'type': 'str' } } | |
256 | ||
257 | ## | |
258 | # @SchemaInfoAlternate: | |
259 | # | |
260 | # Additional SchemaInfo members for meta-type 'alternate'. | |
261 | # | |
262 | # @members: the alternate type's members, in no particular order. The | |
263 | # members' wire encoding is distinct, see | |
264 | # docs/devel/qapi-code-gen.txt section Alternate types. | |
265 | # | |
266 | # On the wire, this can be any of the members. | |
267 | # | |
268 | # Since: 2.5 | |
269 | ## | |
270 | { 'struct': 'SchemaInfoAlternate', | |
271 | 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } | |
272 | ||
273 | ## | |
274 | # @SchemaInfoAlternateMember: | |
275 | # | |
276 | # An alternate member. | |
277 | # | |
278 | # @type: the name of the member's type. | |
279 | # | |
280 | # Since: 2.5 | |
281 | ## | |
282 | { 'struct': 'SchemaInfoAlternateMember', | |
283 | 'data': { 'type': 'str' } } | |
284 | ||
285 | ## | |
286 | # @SchemaInfoCommand: | |
287 | # | |
288 | # Additional SchemaInfo members for meta-type 'command'. | |
289 | # | |
290 | # @arg-type: the name of the object type that provides the command's | |
291 | # parameters. | |
292 | # | |
293 | # @ret-type: the name of the command's result type. | |
294 | # | |
295 | # @allow-oob: whether the command allows out-of-band execution, | |
296 | # defaults to false (Since: 2.12) | |
297 | # | |
298 | # TODO: @success-response (currently irrelevant, because it's QGA, not | |
299 | # QMP) | |
300 | # | |
301 | # Since: 2.5 | |
302 | ## | |
303 | { 'struct': 'SchemaInfoCommand', | |
304 | 'data': { 'arg-type': 'str', 'ret-type': 'str', | |
305 | '*allow-oob': 'bool' } } | |
306 | ||
307 | ## | |
308 | # @SchemaInfoEvent: | |
309 | # | |
310 | # Additional SchemaInfo members for meta-type 'event'. | |
311 | # | |
312 | # @arg-type: the name of the object type that provides the event's | |
313 | # parameters. | |
314 | # | |
315 | # Since: 2.5 | |
316 | ## | |
317 | { 'struct': 'SchemaInfoEvent', | |
318 | 'data': { 'arg-type': 'str' } } |