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