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