]>
Commit | Line | Data |
---|---|---|
39a18158 MA |
1 | # -*- Mode: Python -*- |
2 | # | |
39a18158 MA |
3 | # Copyright (C) 2015 Red Hat, Inc. |
4 | # | |
5 | # Authors: | |
6 | # Markus Armbruster <armbru@redhat.com> | |
7 | # | |
8 | # This work is licensed under the terms of the GNU GPL, version 2 or later. | |
9 | # See the COPYING file in the top-level directory. | |
10 | ||
a885cd39 MA |
11 | ## |
12 | # = QMP introspection | |
13 | ## | |
14 | ||
39a18158 | 15 | ## |
5072f7b3 | 16 | # @query-qmp-schema: |
39a18158 MA |
17 | # |
18 | # Command query-qmp-schema exposes the QMP wire ABI as an array of | |
19 | # SchemaInfo. This lets QMP clients figure out what commands and | |
20 | # events are available in this QEMU, and their parameters and results. | |
21 | # | |
22 | # However, the SchemaInfo can't reflect all the rules and restrictions | |
23 | # that apply to QMP. It's interface introspection (figuring out | |
24 | # what's there), not interface specification. The specification is in | |
25 | # the QAPI schema. | |
26 | # | |
39a65e2c EB |
27 | # Furthermore, while we strive to keep the QMP wire format |
28 | # backwards-compatible across qemu versions, the introspection output | |
29 | # is not guaranteed to have the same stability. For example, one | |
30 | # version of qemu may list an object member as an optional | |
31 | # non-variant, while another lists the same member only through the | |
32 | # object's variants; or the type of a member may change from a generic | |
33 | # string into a specific enum or from one specific type into an | |
34 | # alternate that includes the original type alongside something else. | |
35 | # | |
39a18158 | 36 | # Returns: array of @SchemaInfo, where each element describes an |
26ec4e53 | 37 | # entity in the ABI: command, event, type, ... |
39a18158 | 38 | # |
26ec4e53 PM |
39 | # The order of the various SchemaInfo is unspecified; however, all |
40 | # names are guaranteed to be unique (no name will be duplicated with | |
41 | # different meta-types). | |
f5455044 | 42 | # |
39a18158 | 43 | # Note: the QAPI schema is also used to help define *internal* |
26ec4e53 PM |
44 | # interfaces, by defining QAPI types. These are not part of the QMP |
45 | # wire ABI, and therefore not returned by this command. | |
39a18158 MA |
46 | # |
47 | # Since: 2.5 | |
48 | ## | |
49 | { 'command': 'query-qmp-schema', | |
50 | 'returns': [ 'SchemaInfo' ], | |
51 | 'gen': false } # just to simplify qmp_query_json() | |
52 | ||
53 | ## | |
5072f7b3 | 54 | # @SchemaMetaType: |
39a18158 MA |
55 | # |
56 | # This is a @SchemaInfo's meta type, i.e. the kind of entity it | |
57 | # describes. | |
58 | # | |
59 | # @builtin: a predefined type such as 'int' or 'bool'. | |
60 | # | |
61 | # @enum: an enumeration type | |
62 | # | |
63 | # @array: an array type | |
64 | # | |
65 | # @object: an object type (struct or union) | |
66 | # | |
67 | # @alternate: an alternate type | |
68 | # | |
69 | # @command: a QMP command | |
70 | # | |
71 | # @event: a QMP event | |
72 | # | |
73 | # Since: 2.5 | |
74 | ## | |
75 | { 'enum': 'SchemaMetaType', | |
76 | 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate', | |
77 | 'command', 'event' ] } | |
78 | ||
39a18158 | 79 | ## |
5072f7b3 | 80 | # @SchemaInfo: |
39a18158 MA |
81 | # |
82 | # @name: the entity's name, inherited from @base. | |
5807ff88 | 83 | # The SchemaInfo is always referenced by this name. |
1a9a507b MA |
84 | # Commands and events have the name defined in the QAPI schema. |
85 | # Unlike command and event names, type names are not part of | |
86 | # the wire ABI. Consequently, type names are meaningless | |
f5455044 EB |
87 | # strings here, although they are still guaranteed unique |
88 | # regardless of @meta-type. | |
39a18158 | 89 | # |
39a18158 MA |
90 | # @meta-type: the entity's meta type, inherited from @base. |
91 | # | |
013b4efc MA |
92 | # @features: names of features associated with the entity, in no |
93 | # particular order. | |
94 | # (since 4.1 for object types, 4.2 for commands, 5.0 for | |
95 | # the rest) | |
96 | # | |
39a18158 MA |
97 | # Additional members depend on the value of @meta-type. |
98 | # | |
99 | # Since: 2.5 | |
100 | ## | |
101 | { 'union': 'SchemaInfo', | |
013b4efc MA |
102 | 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType', |
103 | '*features': [ 'str' ] }, | |
39a18158 MA |
104 | 'discriminator': 'meta-type', |
105 | 'data': { | |
106 | 'builtin': 'SchemaInfoBuiltin', | |
107 | 'enum': 'SchemaInfoEnum', | |
108 | 'array': 'SchemaInfoArray', | |
109 | 'object': 'SchemaInfoObject', | |
110 | 'alternate': 'SchemaInfoAlternate', | |
111 | 'command': 'SchemaInfoCommand', | |
112 | 'event': 'SchemaInfoEvent' } } | |
113 | ||
114 | ## | |
5072f7b3 | 115 | # @SchemaInfoBuiltin: |
39a18158 MA |
116 | # |
117 | # Additional SchemaInfo members for meta-type 'builtin'. | |
118 | # | |
119 | # @json-type: the JSON type used for this type on the wire. | |
120 | # | |
121 | # Since: 2.5 | |
122 | ## | |
123 | { 'struct': 'SchemaInfoBuiltin', | |
124 | 'data': { 'json-type': 'JSONType' } } | |
125 | ||
126 | ## | |
5072f7b3 | 127 | # @JSONType: |
39a18158 | 128 | # |
37aded92 | 129 | # The four primitive and two structured types according to RFC 8259 |
39a18158 MA |
130 | # section 1, plus 'int' (split off 'number'), plus the obvious top |
131 | # type 'value'. | |
132 | # | |
133 | # Since: 2.5 | |
134 | ## | |
135 | { 'enum': 'JSONType', | |
136 | 'data': [ 'string', 'number', 'int', 'boolean', 'null', | |
137 | 'object', 'array', 'value' ] } | |
138 | ||
139 | ## | |
5072f7b3 | 140 | # @SchemaInfoEnum: |
39a18158 MA |
141 | # |
142 | # Additional SchemaInfo members for meta-type 'enum'. | |
143 | # | |
f5455044 | 144 | # @values: the enumeration type's values, in no particular order. |
39a18158 MA |
145 | # |
146 | # Values of this type are JSON string on the wire. | |
147 | # | |
148 | # Since: 2.5 | |
149 | ## | |
150 | { 'struct': 'SchemaInfoEnum', | |
151 | 'data': { 'values': ['str'] } } | |
152 | ||
153 | ## | |
5072f7b3 | 154 | # @SchemaInfoArray: |
39a18158 MA |
155 | # |
156 | # Additional SchemaInfo members for meta-type 'array'. | |
157 | # | |
158 | # @element-type: the array type's element type. | |
159 | # | |
160 | # Values of this type are JSON array on the wire. | |
161 | # | |
162 | # Since: 2.5 | |
163 | ## | |
164 | { 'struct': 'SchemaInfoArray', | |
165 | 'data': { 'element-type': 'str' } } | |
166 | ||
167 | ## | |
5072f7b3 | 168 | # @SchemaInfoObject: |
39a18158 MA |
169 | # |
170 | # Additional SchemaInfo members for meta-type 'object'. | |
171 | # | |
f5455044 | 172 | # @members: the object type's (non-variant) members, in no particular order. |
39a18158 | 173 | # |
1d8bda12 | 174 | # @tag: the name of the member serving as type tag. |
39a18158 MA |
175 | # An element of @members with this name must exist. |
176 | # | |
1d8bda12 | 177 | # @variants: variant members, i.e. additional members that |
39a18158 | 178 | # depend on the type tag's value. Present exactly when |
f5455044 EB |
179 | # @tag is present. The variants are in no particular order, |
180 | # and may even differ from the order of the values of the | |
181 | # enum type of the @tag. | |
39a18158 MA |
182 | # |
183 | # Values of this type are JSON object on the wire. | |
184 | # | |
185 | # Since: 2.5 | |
186 | ## | |
187 | { 'struct': 'SchemaInfoObject', | |
188 | 'data': { 'members': [ 'SchemaInfoObjectMember' ], | |
189 | '*tag': 'str', | |
013b4efc | 190 | '*variants': [ 'SchemaInfoObjectVariant' ] } } |
39a18158 MA |
191 | |
192 | ## | |
5072f7b3 | 193 | # @SchemaInfoObjectMember: |
39a18158 MA |
194 | # |
195 | # An object member. | |
196 | # | |
197 | # @name: the member's name, as defined in the QAPI schema. | |
198 | # | |
199 | # @type: the name of the member's type. | |
200 | # | |
1d8bda12 | 201 | # @default: default when used as command parameter. |
39a18158 MA |
202 | # If absent, the parameter is mandatory. |
203 | # If present, the value must be null. The parameter is | |
204 | # optional, and behavior when it's missing is not specified | |
205 | # here. | |
206 | # Future extension: if present and non-null, the parameter | |
207 | # is optional, and defaults to this value. | |
208 | # | |
84ab0086 MA |
209 | # @features: names of features associated with the member, in no |
210 | # particular order. (since 5.0) | |
211 | # | |
39a18158 MA |
212 | # Since: 2.5 |
213 | ## | |
214 | { 'struct': 'SchemaInfoObjectMember', | |
84ab0086 | 215 | 'data': { 'name': 'str', 'type': 'str', '*default': 'any', |
39a18158 | 216 | # @default's type must be null or match @type |
84ab0086 | 217 | '*features': [ 'str' ] } } |
39a18158 MA |
218 | |
219 | ## | |
5072f7b3 | 220 | # @SchemaInfoObjectVariant: |
39a18158 MA |
221 | # |
222 | # The variant members for a value of the type tag. | |
223 | # | |
224 | # @case: a value of the type tag. | |
225 | # | |
226 | # @type: the name of the object type that provides the variant members | |
227 | # when the type tag has value @case. | |
228 | # | |
229 | # Since: 2.5 | |
230 | ## | |
231 | { 'struct': 'SchemaInfoObjectVariant', | |
232 | 'data': { 'case': 'str', 'type': 'str' } } | |
233 | ||
234 | ## | |
5072f7b3 | 235 | # @SchemaInfoAlternate: |
39a18158 MA |
236 | # |
237 | # Additional SchemaInfo members for meta-type 'alternate'. | |
238 | # | |
f5455044 | 239 | # @members: the alternate type's members, in no particular order. |
39a18158 | 240 | # The members' wire encoding is distinct, see |
b3125e73 | 241 | # docs/devel/qapi-code-gen.txt section Alternate types. |
39a18158 MA |
242 | # |
243 | # On the wire, this can be any of the members. | |
244 | # | |
245 | # Since: 2.5 | |
246 | ## | |
247 | { 'struct': 'SchemaInfoAlternate', | |
248 | 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } | |
249 | ||
250 | ## | |
5072f7b3 | 251 | # @SchemaInfoAlternateMember: |
39a18158 MA |
252 | # |
253 | # An alternate member. | |
254 | # | |
255 | # @type: the name of the member's type. | |
256 | # | |
257 | # Since: 2.5 | |
258 | ## | |
259 | { 'struct': 'SchemaInfoAlternateMember', | |
260 | 'data': { 'type': 'str' } } | |
261 | ||
262 | ## | |
5072f7b3 | 263 | # @SchemaInfoCommand: |
39a18158 MA |
264 | # |
265 | # Additional SchemaInfo members for meta-type 'command'. | |
266 | # | |
267 | # @arg-type: the name of the object type that provides the command's | |
268 | # parameters. | |
269 | # | |
270 | # @ret-type: the name of the command's result type. | |
271 | # | |
25b1ef31 MA |
272 | # @allow-oob: whether the command allows out-of-band execution, |
273 | # defaults to false (Since: 2.12) | |
876c6751 | 274 | # |
e22da431 | 275 | # TODO: @success-response (currently irrelevant, because it's QGA, not QMP) |
39a18158 MA |
276 | # |
277 | # Since: 2.5 | |
278 | ## | |
279 | { 'struct': 'SchemaInfoCommand', | |
876c6751 | 280 | 'data': { 'arg-type': 'str', 'ret-type': 'str', |
013b4efc | 281 | '*allow-oob': 'bool' } } |
39a18158 MA |
282 | |
283 | ## | |
5072f7b3 | 284 | # @SchemaInfoEvent: |
39a18158 MA |
285 | # |
286 | # Additional SchemaInfo members for meta-type 'event'. | |
287 | # | |
288 | # @arg-type: the name of the object type that provides the event's | |
289 | # parameters. | |
290 | # | |
291 | # Since: 2.5 | |
292 | ## | |
293 | { 'struct': 'SchemaInfoEvent', | |
294 | 'data': { 'arg-type': 'str' } } |