]>
Commit | Line | Data |
---|---|---|
39a18158 | 1 | # -*- Mode: Python -*- |
f7160f32 | 2 | # vim: filetype=python |
39a18158 | 3 | # |
39a18158 MA |
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 | ||
a885cd39 MA |
12 | ## |
13 | # = QMP introspection | |
14 | ## | |
15 | ||
39a18158 | 16 | ## |
5072f7b3 | 17 | # @query-qmp-schema: |
39a18158 MA |
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 | # | |
39a65e2c EB |
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 | # | |
39a18158 | 37 | # Returns: array of @SchemaInfo, where each element describes an |
a937b6aa | 38 | # entity in the ABI: command, event, type, ... |
39a18158 | 39 | # |
a937b6aa MA |
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). | |
f5455044 | 43 | # |
39a18158 | 44 | # Note: the QAPI schema is also used to help define *internal* |
a937b6aa MA |
45 | # interfaces, by defining QAPI types. These are not part of the |
46 | # QMP wire ABI, and therefore not returned by this command. | |
39a18158 MA |
47 | # |
48 | # Since: 2.5 | |
49 | ## | |
50 | { 'command': 'query-qmp-schema', | |
51 | 'returns': [ 'SchemaInfo' ], | |
624fa80c | 52 | 'allow-preconfig': true } |
39a18158 MA |
53 | |
54 | ## | |
5072f7b3 | 55 | # @SchemaMetaType: |
39a18158 MA |
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 | ||
39a18158 | 80 | ## |
5072f7b3 | 81 | # @SchemaInfo: |
39a18158 | 82 | # |
a937b6aa MA |
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. | |
39a18158 | 89 | # |
39a18158 MA |
90 | # @meta-type: the entity's meta type, inherited from @base. |
91 | # | |
013b4efc | 92 | # @features: names of features associated with the entity, in no |
a937b6aa MA |
93 | # particular order. (since 4.1 for object types, 4.2 for |
94 | # commands, 5.0 for the rest) | |
013b4efc | 95 | # |
39a18158 MA |
96 | # Additional members depend on the value of @meta-type. |
97 | # | |
98 | # Since: 2.5 | |
99 | ## | |
100 | { 'union': 'SchemaInfo', | |
013b4efc MA |
101 | 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType', |
102 | '*features': [ 'str' ] }, | |
39a18158 MA |
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 | ## | |
5072f7b3 | 114 | # @SchemaInfoBuiltin: |
39a18158 MA |
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 | ## | |
5072f7b3 | 126 | # @JSONType: |
39a18158 | 127 | # |
37aded92 | 128 | # The four primitive and two structured types according to RFC 8259 |
39a18158 MA |
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 | ## | |
5072f7b3 | 139 | # @SchemaInfoEnum: |
39a18158 MA |
140 | # |
141 | # Additional SchemaInfo members for meta-type 'enum'. | |
142 | # | |
a937b6aa MA |
143 | # @members: the enum type's members, in no particular order (since |
144 | # 6.2). | |
75ecee72 | 145 | # |
a937b6aa MA |
146 | # @values: the enumeration type's member names, in no particular |
147 | # order. Redundant with @members. Just for backward | |
148 | # compatibility. | |
75ecee72 MA |
149 | # |
150 | # Features: | |
a937b6aa | 151 | # |
75ecee72 | 152 | # @deprecated: Member @values is deprecated. Use @members instead. |
39a18158 MA |
153 | # |
154 | # Values of this type are JSON string on the wire. | |
155 | # | |
156 | # Since: 2.5 | |
157 | ## | |
158 | { 'struct': 'SchemaInfoEnum', | |
75ecee72 MA |
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 | # | |
b6c18755 | 170 | # @features: names of features associated with the member, in no |
a937b6aa | 171 | # particular order. |
b6c18755 | 172 | # |
75ecee72 MA |
173 | # Since: 6.2 |
174 | ## | |
175 | { 'struct': 'SchemaInfoEnumMember', | |
b6c18755 | 176 | 'data': { 'name': 'str', '*features': [ 'str' ] } } |
39a18158 MA |
177 | |
178 | ## | |
5072f7b3 | 179 | # @SchemaInfoArray: |
39a18158 MA |
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 | ## | |
5072f7b3 | 193 | # @SchemaInfoObject: |
39a18158 MA |
194 | # |
195 | # Additional SchemaInfo members for meta-type 'object'. | |
196 | # | |
a937b6aa MA |
197 | # @members: the object type's (non-variant) members, in no particular |
198 | # order. | |
39a18158 | 199 | # |
a937b6aa MA |
200 | # @tag: the name of the member serving as type tag. An element of |
201 | # @members with this name must exist. | |
39a18158 | 202 | # |
a937b6aa MA |
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. | |
39a18158 MA |
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', | |
013b4efc | 215 | '*variants': [ 'SchemaInfoObjectVariant' ] } } |
39a18158 MA |
216 | |
217 | ## | |
5072f7b3 | 218 | # @SchemaInfoObjectMember: |
39a18158 MA |
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 | # | |
a937b6aa MA |
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. | |
39a18158 | 231 | # |
84ab0086 | 232 | # @features: names of features associated with the member, in no |
a937b6aa | 233 | # particular order. (since 5.0) |
84ab0086 | 234 | # |
39a18158 MA |
235 | # Since: 2.5 |
236 | ## | |
237 | { 'struct': 'SchemaInfoObjectMember', | |
84ab0086 | 238 | 'data': { 'name': 'str', 'type': 'str', '*default': 'any', |
39a18158 | 239 | # @default's type must be null or match @type |
84ab0086 | 240 | '*features': [ 'str' ] } } |
39a18158 MA |
241 | |
242 | ## | |
5072f7b3 | 243 | # @SchemaInfoObjectVariant: |
39a18158 MA |
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 | |
a937b6aa | 250 | # when the type tag has value @case. |
39a18158 MA |
251 | # |
252 | # Since: 2.5 | |
253 | ## | |
254 | { 'struct': 'SchemaInfoObjectVariant', | |
255 | 'data': { 'case': 'str', 'type': 'str' } } | |
256 | ||
257 | ## | |
5072f7b3 | 258 | # @SchemaInfoAlternate: |
39a18158 MA |
259 | # |
260 | # Additional SchemaInfo members for meta-type 'alternate'. | |
261 | # | |
a937b6aa MA |
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. | |
39a18158 MA |
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 | ## | |
5072f7b3 | 274 | # @SchemaInfoAlternateMember: |
39a18158 MA |
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 | ## | |
5072f7b3 | 286 | # @SchemaInfoCommand: |
39a18158 MA |
287 | # |
288 | # Additional SchemaInfo members for meta-type 'command'. | |
289 | # | |
290 | # @arg-type: the name of the object type that provides the command's | |
a937b6aa | 291 | # parameters. |
39a18158 MA |
292 | # |
293 | # @ret-type: the name of the command's result type. | |
294 | # | |
25b1ef31 | 295 | # @allow-oob: whether the command allows out-of-band execution, |
a937b6aa | 296 | # defaults to false (Since: 2.12) |
876c6751 | 297 | # |
a937b6aa MA |
298 | # TODO: @success-response (currently irrelevant, because it's QGA, not |
299 | # QMP) | |
39a18158 MA |
300 | # |
301 | # Since: 2.5 | |
302 | ## | |
303 | { 'struct': 'SchemaInfoCommand', | |
876c6751 | 304 | 'data': { 'arg-type': 'str', 'ret-type': 'str', |
013b4efc | 305 | '*allow-oob': 'bool' } } |
39a18158 MA |
306 | |
307 | ## | |
5072f7b3 | 308 | # @SchemaInfoEvent: |
39a18158 MA |
309 | # |
310 | # Additional SchemaInfo members for meta-type 'event'. | |
311 | # | |
312 | # @arg-type: the name of the object type that provides the event's | |
a937b6aa | 313 | # parameters. |
39a18158 MA |
314 | # |
315 | # Since: 2.5 | |
316 | ## | |
317 | { 'struct': 'SchemaInfoEvent', | |
318 | 'data': { 'arg-type': 'str' } } |