]>
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 |
26ec4e53 | 38 | # entity in the ABI: command, event, type, ... |
39a18158 | 39 | # |
26ec4e53 PM |
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). | |
f5455044 | 43 | # |
39a18158 | 44 | # Note: the QAPI schema is also used to help define *internal* |
26ec4e53 PM |
45 | # interfaces, by defining QAPI types. These are not part of the QMP |
46 | # 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 MA |
82 | # |
83 | # @name: the entity's name, inherited from @base. | |
5807ff88 | 84 | # The SchemaInfo is always referenced by this name. |
1a9a507b MA |
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 | |
f5455044 EB |
88 | # strings here, although they are still guaranteed unique |
89 | # regardless of @meta-type. | |
39a18158 | 90 | # |
39a18158 MA |
91 | # @meta-type: the entity's meta type, inherited from @base. |
92 | # | |
013b4efc MA |
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 | # | |
39a18158 MA |
98 | # Additional members depend on the value of @meta-type. |
99 | # | |
100 | # Since: 2.5 | |
101 | ## | |
102 | { 'union': 'SchemaInfo', | |
013b4efc MA |
103 | 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType', |
104 | '*features': [ 'str' ] }, | |
39a18158 MA |
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 | ## | |
5072f7b3 | 116 | # @SchemaInfoBuiltin: |
39a18158 MA |
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 | ## | |
5072f7b3 | 128 | # @JSONType: |
39a18158 | 129 | # |
37aded92 | 130 | # The four primitive and two structured types according to RFC 8259 |
39a18158 MA |
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 | ## | |
5072f7b3 | 141 | # @SchemaInfoEnum: |
39a18158 MA |
142 | # |
143 | # Additional SchemaInfo members for meta-type 'enum'. | |
144 | # | |
75ecee72 MA |
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. | |
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 MA |
170 | # @features: names of features associated with the member, in no |
171 | # particular order. | |
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 | # | |
f5455044 | 197 | # @members: the object type's (non-variant) members, in no particular order. |
39a18158 | 198 | # |
1d8bda12 | 199 | # @tag: the name of the member serving as type tag. |
39a18158 MA |
200 | # An element of @members with this name must exist. |
201 | # | |
1d8bda12 | 202 | # @variants: variant members, i.e. additional members that |
39a18158 | 203 | # depend on the type tag's value. Present exactly when |
f5455044 EB |
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. | |
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 | # | |
1d8bda12 | 226 | # @default: default when used as command parameter. |
39a18158 MA |
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 | # | |
84ab0086 MA |
234 | # @features: names of features associated with the member, in no |
235 | # particular order. (since 5.0) | |
236 | # | |
39a18158 MA |
237 | # Since: 2.5 |
238 | ## | |
239 | { 'struct': 'SchemaInfoObjectMember', | |
84ab0086 | 240 | 'data': { 'name': 'str', 'type': 'str', '*default': 'any', |
39a18158 | 241 | # @default's type must be null or match @type |
84ab0086 | 242 | '*features': [ 'str' ] } } |
39a18158 MA |
243 | |
244 | ## | |
5072f7b3 | 245 | # @SchemaInfoObjectVariant: |
39a18158 MA |
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 | ## | |
5072f7b3 | 260 | # @SchemaInfoAlternate: |
39a18158 MA |
261 | # |
262 | # Additional SchemaInfo members for meta-type 'alternate'. | |
263 | # | |
f5455044 | 264 | # @members: the alternate type's members, in no particular order. |
39a18158 | 265 | # The members' wire encoding is distinct, see |
b3125e73 | 266 | # docs/devel/qapi-code-gen.txt section Alternate types. |
39a18158 MA |
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 | ## | |
5072f7b3 | 276 | # @SchemaInfoAlternateMember: |
39a18158 MA |
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 | ## | |
5072f7b3 | 288 | # @SchemaInfoCommand: |
39a18158 MA |
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 | # | |
25b1ef31 MA |
297 | # @allow-oob: whether the command allows out-of-band execution, |
298 | # defaults to false (Since: 2.12) | |
876c6751 | 299 | # |
e22da431 | 300 | # TODO: @success-response (currently irrelevant, because it's QGA, not QMP) |
39a18158 MA |
301 | # |
302 | # Since: 2.5 | |
303 | ## | |
304 | { 'struct': 'SchemaInfoCommand', | |
876c6751 | 305 | 'data': { 'arg-type': 'str', 'ret-type': 'str', |
013b4efc | 306 | '*allow-oob': 'bool' } } |
39a18158 MA |
307 | |
308 | ## | |
5072f7b3 | 309 | # @SchemaInfoEvent: |
39a18158 MA |
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' } } |