Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20200117-1' into...
[qemu.git] / qapi / introspect.json
1 # -*- Mode: Python -*-
2 #
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
11 ##
12 # = QMP introspection
13 ##
14
15 ##
16 # @query-qmp-schema:
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 #
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 #
36 # Returns: array of @SchemaInfo, where each element describes an
37 # entity in the ABI: command, event, type, ...
38 #
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).
42 #
43 # Note: the QAPI schema is also used to help define *internal*
44 # interfaces, by defining QAPI types.  These are not part of the QMP
45 # wire ABI, and therefore not returned by this command.
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 ##
54 # @SchemaMetaType:
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
79 ##
80 # @SchemaInfo:
81 #
82 # @name: the entity's name, inherited from @base.
83 #        The SchemaInfo is always referenced by this name.
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
87 #        strings here, although they are still guaranteed unique
88 #        regardless of @meta-type.
89 #
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': { 'name': 'str', 'meta-type': 'SchemaMetaType' },
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 8259
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 #
138 # @values: the enumeration type's values, in no particular order.
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 #
166 # @members: the object type's (non-variant) members, in no particular order.
167 #
168 # @tag: the name of the member serving as type tag.
169 #       An element of @members with this name must exist.
170 #
171 # @variants: variant members, i.e. additional members that
172 #            depend on the type tag's value.  Present exactly when
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.
176 #
177 # @features: names of features associated with the type, in no particular
178 #            order. (since: 4.1)
179 #
180 # Values of this type are JSON object on the wire.
181 #
182 # Since: 2.5
183 ##
184 { 'struct': 'SchemaInfoObject',
185   'data': { 'members': [ 'SchemaInfoObjectMember' ],
186             '*tag': 'str',
187             '*variants': [ 'SchemaInfoObjectVariant' ],
188             '*features': [ 'str' ] } }
189
190 ##
191 # @SchemaInfoObjectMember:
192 #
193 # An object member.
194 #
195 # @name: the member's name, as defined in the QAPI schema.
196 #
197 # @type: the name of the member's type.
198 #
199 # @default: default when used as command parameter.
200 #           If absent, the parameter is mandatory.
201 #           If present, the value must be null.  The parameter is
202 #           optional, and behavior when it's missing is not specified
203 #           here.
204 #           Future extension: if present and non-null, the parameter
205 #           is optional, and defaults to this value.
206 #
207 # Since: 2.5
208 ##
209 { 'struct': 'SchemaInfoObjectMember',
210   'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
211 # @default's type must be null or match @type
212
213 ##
214 # @SchemaInfoObjectVariant:
215 #
216 # The variant members for a value of the type tag.
217 #
218 # @case: a value of the type tag.
219 #
220 # @type: the name of the object type that provides the variant members
221 #        when the type tag has value @case.
222 #
223 # Since: 2.5
224 ##
225 { 'struct': 'SchemaInfoObjectVariant',
226   'data': { 'case': 'str', 'type': 'str' } }
227
228 ##
229 # @SchemaInfoAlternate:
230 #
231 # Additional SchemaInfo members for meta-type 'alternate'.
232 #
233 # @members: the alternate type's members, in no particular order.
234 #           The members' wire encoding is distinct, see
235 #           docs/devel/qapi-code-gen.txt section Alternate types.
236 #
237 # On the wire, this can be any of the members.
238 #
239 # Since: 2.5
240 ##
241 { 'struct': 'SchemaInfoAlternate',
242   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
243
244 ##
245 # @SchemaInfoAlternateMember:
246 #
247 # An alternate member.
248 #
249 # @type: the name of the member's type.
250 #
251 # Since: 2.5
252 ##
253 { 'struct': 'SchemaInfoAlternateMember',
254   'data': { 'type': 'str' } }
255
256 ##
257 # @SchemaInfoCommand:
258 #
259 # Additional SchemaInfo members for meta-type 'command'.
260 #
261 # @arg-type: the name of the object type that provides the command's
262 #            parameters.
263 #
264 # @ret-type: the name of the command's result type.
265 #
266 # @allow-oob: whether the command allows out-of-band execution,
267 #             defaults to false (Since: 2.12)
268 #
269 # @features: names of features associated with the command, in no particular
270 #            order. (since 4.2)
271 #
272 # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
273 #
274 # Since: 2.5
275 ##
276 { 'struct': 'SchemaInfoCommand',
277   'data': { 'arg-type': 'str', 'ret-type': 'str',
278             '*allow-oob': 'bool',
279             '*features': [ 'str' ] } }
280
281 ##
282 # @SchemaInfoEvent:
283 #
284 # Additional SchemaInfo members for meta-type 'event'.
285 #
286 # @arg-type: the name of the object type that provides the event's
287 #            parameters.
288 #
289 # Since: 2.5
290 ##
291 { 'struct': 'SchemaInfoEvent',
292   'data': { 'arg-type': 'str' } }