hw/arm/virt: use VirtMachineState.gic_version
[qemu.git] / qapi / introspect.json
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 # Furthermore, while we strive to keep the QMP wire format
26 # backwards-compatible across qemu versions, the introspection output
27 # is not guaranteed to have the same stability.  For example, one
28 # version of qemu may list an object member as an optional
29 # non-variant, while another lists the same member only through the
30 # object's variants; or the type of a member may change from a generic
31 # string into a specific enum or from one specific type into an
32 # alternate that includes the original type alongside something else.
33 #
34 # Returns: array of @SchemaInfo, where each element describes an
35 # entity in the ABI: command, event, type, ...
36 #
37 # The order of the various SchemaInfo is unspecified; however, all
38 # names are guaranteed to be unique (no name will be duplicated with
39 # different meta-types).
40 #
41 # Note: the QAPI schema is also used to help define *internal*
42 # interfaces, by defining QAPI types.  These are not part of the QMP
43 # wire ABI, and therefore not returned by this command.
44 #
45 # Since: 2.5
46 ##
47 { 'command': 'query-qmp-schema',
48   'returns': [ 'SchemaInfo' ],
49   'gen': false }                # just to simplify qmp_query_json()
50
51 ##
52 # @SchemaMetaType:
53 #
54 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
55 # describes.
56 #
57 # @builtin: a predefined type such as 'int' or 'bool'.
58 #
59 # @enum: an enumeration type
60 #
61 # @array: an array type
62 #
63 # @object: an object type (struct or union)
64 #
65 # @alternate: an alternate type
66 #
67 # @command: a QMP command
68 #
69 # @event: a QMP event
70 #
71 # Since: 2.5
72 ##
73 { 'enum': 'SchemaMetaType',
74   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
75             'command', 'event' ] }
76
77 ##
78 # @SchemaInfo:
79 #
80 # @name: the entity's name, inherited from @base.
81 #        Commands and events have the name defined in the QAPI schema.
82 #        Unlike command and event names, type names are not part of
83 #        the wire ABI.  Consequently, type names are meaningless
84 #        strings here, although they are still guaranteed unique
85 #        regardless of @meta-type.
86 #
87 # All references to other SchemaInfo are by name.
88 #
89 # @meta-type: the entity's meta type, inherited from @base.
90 #
91 # Additional members depend on the value of @meta-type.
92 #
93 # Since: 2.5
94 ##
95 { 'union': 'SchemaInfo',
96   'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' },
97   'discriminator': 'meta-type',
98   'data': {
99       'builtin': 'SchemaInfoBuiltin',
100       'enum': 'SchemaInfoEnum',
101       'array': 'SchemaInfoArray',
102       'object': 'SchemaInfoObject',
103       'alternate': 'SchemaInfoAlternate',
104       'command': 'SchemaInfoCommand',
105       'event': 'SchemaInfoEvent' } }
106
107 ##
108 # @SchemaInfoBuiltin:
109 #
110 # Additional SchemaInfo members for meta-type 'builtin'.
111 #
112 # @json-type: the JSON type used for this type on the wire.
113 #
114 # Since: 2.5
115 ##
116 { 'struct': 'SchemaInfoBuiltin',
117   'data': { 'json-type': 'JSONType' } }
118
119 ##
120 # @JSONType:
121 #
122 # The four primitive and two structured types according to RFC 7159
123 # section 1, plus 'int' (split off 'number'), plus the obvious top
124 # type 'value'.
125 #
126 # Since: 2.5
127 ##
128 { 'enum': 'JSONType',
129   'data': [ 'string', 'number', 'int', 'boolean', 'null',
130             'object', 'array', 'value' ] }
131
132 ##
133 # @SchemaInfoEnum:
134 #
135 # Additional SchemaInfo members for meta-type 'enum'.
136 #
137 # @values: the enumeration type's values, in no particular order.
138 #
139 # Values of this type are JSON string on the wire.
140 #
141 # Since: 2.5
142 ##
143 { 'struct': 'SchemaInfoEnum',
144   'data': { 'values': ['str'] } }
145
146 ##
147 # @SchemaInfoArray:
148 #
149 # Additional SchemaInfo members for meta-type 'array'.
150 #
151 # @element-type: the array type's element type.
152 #
153 # Values of this type are JSON array on the wire.
154 #
155 # Since: 2.5
156 ##
157 { 'struct': 'SchemaInfoArray',
158   'data': { 'element-type': 'str' } }
159
160 ##
161 # @SchemaInfoObject:
162 #
163 # Additional SchemaInfo members for meta-type 'object'.
164 #
165 # @members: the object type's (non-variant) members, in no particular order.
166 #
167 # @tag: #optional the name of the member serving as type tag.
168 #       An element of @members with this name must exist.
169 #
170 # @variants: #optional variant members, i.e. additional members that
171 #            depend on the type tag's value.  Present exactly when
172 #            @tag is present.  The variants are in no particular order,
173 #            and may even differ from the order of the values of the
174 #            enum type of the @tag.
175 #
176 # Values of this type are JSON object on the wire.
177 #
178 # Since: 2.5
179 ##
180 { 'struct': 'SchemaInfoObject',
181   'data': { 'members': [ 'SchemaInfoObjectMember' ],
182             '*tag': 'str',
183             '*variants': [ 'SchemaInfoObjectVariant' ] } }
184
185 ##
186 # @SchemaInfoObjectMember:
187 #
188 # An object member.
189 #
190 # @name: the member's name, as defined in the QAPI schema.
191 #
192 # @type: the name of the member's type.
193 #
194 # @default: #optional default when used as command parameter.
195 #           If absent, the parameter is mandatory.
196 #           If present, the value must be null.  The parameter is
197 #           optional, and behavior when it's missing is not specified
198 #           here.
199 #           Future extension: if present and non-null, the parameter
200 #           is optional, and defaults to this value.
201 #
202 # Since: 2.5
203 ##
204 { 'struct': 'SchemaInfoObjectMember',
205   'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
206 # @default's type must be null or match @type
207
208 ##
209 # @SchemaInfoObjectVariant:
210 #
211 # The variant members for a value of the type tag.
212 #
213 # @case: a value of the type tag.
214 #
215 # @type: the name of the object type that provides the variant members
216 #        when the type tag has value @case.
217 #
218 # Since: 2.5
219 ##
220 { 'struct': 'SchemaInfoObjectVariant',
221   'data': { 'case': 'str', 'type': 'str' } }
222
223 ##
224 # @SchemaInfoAlternate:
225 #
226 # Additional SchemaInfo members for meta-type 'alternate'.
227 #
228 # @members: the alternate type's members, in no particular order.
229 #           The members' wire encoding is distinct, see
230 #           docs/qapi-code-gen.txt section Alternate types.
231 #
232 # On the wire, this can be any of the members.
233 #
234 # Since: 2.5
235 ##
236 { 'struct': 'SchemaInfoAlternate',
237   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
238
239 ##
240 # @SchemaInfoAlternateMember:
241 #
242 # An alternate member.
243 #
244 # @type: the name of the member's type.
245 #
246 # Since: 2.5
247 ##
248 { 'struct': 'SchemaInfoAlternateMember',
249   'data': { 'type': 'str' } }
250
251 ##
252 # @SchemaInfoCommand:
253 #
254 # Additional SchemaInfo members for meta-type 'command'.
255 #
256 # @arg-type: the name of the object type that provides the command's
257 #            parameters.
258 #
259 # @ret-type: the name of the command's result type.
260 #
261 # TODO @success-response (currently irrelevant, because it's QGA, not QMP)
262 #
263 # Since: 2.5
264 ##
265 { 'struct': 'SchemaInfoCommand',
266   'data': { 'arg-type': 'str', 'ret-type': 'str' } }
267
268 ##
269 # @SchemaInfoEvent:
270 #
271 # Additional SchemaInfo members for meta-type 'event'.
272 #
273 # @arg-type: the name of the object type that provides the event's
274 #            parameters.
275 #
276 # Since: 2.5
277 ##
278 { 'struct': 'SchemaInfoEvent',
279   'data': { 'arg-type': 'str' } }