ppc/pnv: Add support for POWER8+ LPC Controller
[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 #        The SchemaInfo is always referenced by this name.
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
85 #        strings here, although they are still guaranteed unique
86 #        regardless of @meta-type.
87 #
88 # @meta-type: the entity's meta type, inherited from @base.
89 #
90 # Additional members depend on the value of @meta-type.
91 #
92 # Since: 2.5
93 ##
94 { 'union': 'SchemaInfo',
95   'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' },
96   'discriminator': 'meta-type',
97   'data': {
98       'builtin': 'SchemaInfoBuiltin',
99       'enum': 'SchemaInfoEnum',
100       'array': 'SchemaInfoArray',
101       'object': 'SchemaInfoObject',
102       'alternate': 'SchemaInfoAlternate',
103       'command': 'SchemaInfoCommand',
104       'event': 'SchemaInfoEvent' } }
105
106 ##
107 # @SchemaInfoBuiltin:
108 #
109 # Additional SchemaInfo members for meta-type 'builtin'.
110 #
111 # @json-type: the JSON type used for this type on the wire.
112 #
113 # Since: 2.5
114 ##
115 { 'struct': 'SchemaInfoBuiltin',
116   'data': { 'json-type': 'JSONType' } }
117
118 ##
119 # @JSONType:
120 #
121 # The four primitive and two structured types according to RFC 7159
122 # section 1, plus 'int' (split off 'number'), plus the obvious top
123 # type 'value'.
124 #
125 # Since: 2.5
126 ##
127 { 'enum': 'JSONType',
128   'data': [ 'string', 'number', 'int', 'boolean', 'null',
129             'object', 'array', 'value' ] }
130
131 ##
132 # @SchemaInfoEnum:
133 #
134 # Additional SchemaInfo members for meta-type 'enum'.
135 #
136 # @values: the enumeration type's values, in no particular order.
137 #
138 # Values of this type are JSON string on the wire.
139 #
140 # Since: 2.5
141 ##
142 { 'struct': 'SchemaInfoEnum',
143   'data': { 'values': ['str'] } }
144
145 ##
146 # @SchemaInfoArray:
147 #
148 # Additional SchemaInfo members for meta-type 'array'.
149 #
150 # @element-type: the array type's element type.
151 #
152 # Values of this type are JSON array on the wire.
153 #
154 # Since: 2.5
155 ##
156 { 'struct': 'SchemaInfoArray',
157   'data': { 'element-type': 'str' } }
158
159 ##
160 # @SchemaInfoObject:
161 #
162 # Additional SchemaInfo members for meta-type 'object'.
163 #
164 # @members: the object type's (non-variant) members, in no particular order.
165 #
166 # @tag: the name of the member serving as type tag.
167 #       An element of @members with this name must exist.
168 #
169 # @variants: variant members, i.e. additional members that
170 #            depend on the type tag's value.  Present exactly when
171 #            @tag is present.  The variants are in no particular order,
172 #            and may even differ from the order of the values of the
173 #            enum type of the @tag.
174 #
175 # Values of this type are JSON object on the wire.
176 #
177 # Since: 2.5
178 ##
179 { 'struct': 'SchemaInfoObject',
180   'data': { 'members': [ 'SchemaInfoObjectMember' ],
181             '*tag': 'str',
182             '*variants': [ 'SchemaInfoObjectVariant' ] } }
183
184 ##
185 # @SchemaInfoObjectMember:
186 #
187 # An object member.
188 #
189 # @name: the member's name, as defined in the QAPI schema.
190 #
191 # @type: the name of the member's type.
192 #
193 # @default: default when used as command parameter.
194 #           If absent, the parameter is mandatory.
195 #           If present, the value must be null.  The parameter is
196 #           optional, and behavior when it's missing is not specified
197 #           here.
198 #           Future extension: if present and non-null, the parameter
199 #           is optional, and defaults to this value.
200 #
201 # Since: 2.5
202 ##
203 { 'struct': 'SchemaInfoObjectMember',
204   'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
205 # @default's type must be null or match @type
206
207 ##
208 # @SchemaInfoObjectVariant:
209 #
210 # The variant members for a value of the type tag.
211 #
212 # @case: a value of the type tag.
213 #
214 # @type: the name of the object type that provides the variant members
215 #        when the type tag has value @case.
216 #
217 # Since: 2.5
218 ##
219 { 'struct': 'SchemaInfoObjectVariant',
220   'data': { 'case': 'str', 'type': 'str' } }
221
222 ##
223 # @SchemaInfoAlternate:
224 #
225 # Additional SchemaInfo members for meta-type 'alternate'.
226 #
227 # @members: the alternate type's members, in no particular order.
228 #           The members' wire encoding is distinct, see
229 #           docs/qapi-code-gen.txt section Alternate types.
230 #
231 # On the wire, this can be any of the members.
232 #
233 # Since: 2.5
234 ##
235 { 'struct': 'SchemaInfoAlternate',
236   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
237
238 ##
239 # @SchemaInfoAlternateMember:
240 #
241 # An alternate member.
242 #
243 # @type: the name of the member's type.
244 #
245 # Since: 2.5
246 ##
247 { 'struct': 'SchemaInfoAlternateMember',
248   'data': { 'type': 'str' } }
249
250 ##
251 # @SchemaInfoCommand:
252 #
253 # Additional SchemaInfo members for meta-type 'command'.
254 #
255 # @arg-type: the name of the object type that provides the command's
256 #            parameters.
257 #
258 # @ret-type: the name of the command's result type.
259 #
260 # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
261 #
262 # Since: 2.5
263 ##
264 { 'struct': 'SchemaInfoCommand',
265   'data': { 'arg-type': 'str', 'ret-type': 'str' } }
266
267 ##
268 # @SchemaInfoEvent:
269 #
270 # Additional SchemaInfo members for meta-type 'event'.
271 #
272 # @arg-type: the name of the object type that provides the event's
273 #            parameters.
274 #
275 # Since: 2.5
276 ##
277 { 'struct': 'SchemaInfoEvent',
278   'data': { 'arg-type': 'str' } }