Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging
[qemu/kevin.git] / qapi / introspect.json
blob3fd81fb5400a6e561f36fc71137358f0d2940122
1 # -*- Mode: Python -*-
3 # QAPI/QMP introspection
5 # Copyright (C) 2015 Red Hat, Inc.
7 # Authors:
8 #  Markus Armbruster <armbru@redhat.com>
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.
14 # @query-qmp-schema
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.
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.
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.
34 # Returns: array of @SchemaInfo, where each element describes an
35 # entity in the ABI: command, event, type, ...
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).
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.
45 # Since: 2.5
47 { 'command': 'query-qmp-schema',
48   'returns': [ 'SchemaInfo' ],
49   'gen': false }                # just to simplify qmp_query_json()
52 # @SchemaMetaType
54 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
55 # describes.
57 # @builtin: a predefined type such as 'int' or 'bool'.
59 # @enum: an enumeration type
61 # @array: an array type
63 # @object: an object type (struct or union)
65 # @alternate: an alternate type
67 # @command: a QMP command
69 # @event: a QMP event
71 # Since: 2.5
73 { 'enum': 'SchemaMetaType',
74   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
75             'command', 'event' ] }
78 # @SchemaInfo
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.
87 # All references to other SchemaInfo are by name.
89 # @meta-type: the entity's meta type, inherited from @base.
91 # Additional members depend on the value of @meta-type.
93 # Since: 2.5
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' } }
108 # @SchemaInfoBuiltin
110 # Additional SchemaInfo members for meta-type 'builtin'.
112 # @json-type: the JSON type used for this type on the wire.
114 # Since: 2.5
116 { 'struct': 'SchemaInfoBuiltin',
117   'data': { 'json-type': 'JSONType' } }
120 # @JSONType
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'.
126 # Since: 2.5
128 { 'enum': 'JSONType',
129   'data': [ 'string', 'number', 'int', 'boolean', 'null',
130             'object', 'array', 'value' ] }
133 # @SchemaInfoEnum
135 # Additional SchemaInfo members for meta-type 'enum'.
137 # @values: the enumeration type's values, in no particular order.
139 # Values of this type are JSON string on the wire.
141 # Since: 2.5
143 { 'struct': 'SchemaInfoEnum',
144   'data': { 'values': ['str'] } }
147 # @SchemaInfoArray
149 # Additional SchemaInfo members for meta-type 'array'.
151 # @element-type: the array type's element type.
153 # Values of this type are JSON array on the wire.
155 # Since: 2.5
157 { 'struct': 'SchemaInfoArray',
158   'data': { 'element-type': 'str' } }
161 # @SchemaInfoObject
163 # Additional SchemaInfo members for meta-type 'object'.
165 # @members: the object type's (non-variant) members, in no particular order.
167 # @tag: #optional the name of the member serving as type tag.
168 #       An element of @members with this name must exist.
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.
176 # Values of this type are JSON object on the wire.
178 # Since: 2.5
180 { 'struct': 'SchemaInfoObject',
181   'data': { 'members': [ 'SchemaInfoObjectMember' ],
182             '*tag': 'str',
183             '*variants': [ 'SchemaInfoObjectVariant' ] } }
186 # @SchemaInfoObjectMember
188 # An object member.
190 # @name: the member's name, as defined in the QAPI schema.
192 # @type: the name of the member's type.
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.
202 # Since: 2.5
204 { 'struct': 'SchemaInfoObjectMember',
205   'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
206 # @default's type must be null or match @type
209 # @SchemaInfoObjectVariant
211 # The variant members for a value of the type tag.
213 # @case: a value of the type tag.
215 # @type: the name of the object type that provides the variant members
216 #        when the type tag has value @case.
218 # Since: 2.5
220 { 'struct': 'SchemaInfoObjectVariant',
221   'data': { 'case': 'str', 'type': 'str' } }
224 # @SchemaInfoAlternate
226 # Additional SchemaInfo members for meta-type 'alternate'.
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.
232 # On the wire, this can be any of the members.
234 # Since: 2.5
236 { 'struct': 'SchemaInfoAlternate',
237   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
240 # @SchemaInfoAlternateMember
242 # An alternate member.
244 # @type: the name of the member's type.
246 # Since: 2.5
248 { 'struct': 'SchemaInfoAlternateMember',
249   'data': { 'type': 'str' } }
252 # @SchemaInfoCommand
254 # Additional SchemaInfo members for meta-type 'command'.
256 # @arg-type: the name of the object type that provides the command's
257 #            parameters.
259 # @ret-type: the name of the command's result type.
261 # TODO @success-response (currently irrelevant, because it's QGA, not QMP)
263 # Since: 2.5
265 { 'struct': 'SchemaInfoCommand',
266   'data': { 'arg-type': 'str', 'ret-type': 'str' } }
269 # @SchemaInfoEvent
271 # Additional SchemaInfo members for meta-type 'event'.
273 # @arg-type: the name of the object type that provides the event's
274 #            parameters.
276 # Since: 2.5
278 { 'struct': 'SchemaInfoEvent',
279   'data': { 'arg-type': 'str' } }