aboutsummaryrefslogtreecommitdiff
path: root/qapi/introspect.json
blob: 3d22166b2b9d9f566fd417fef543a848b87c2c6e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
# -*- Mode: Python -*-
#
# Copyright (C) 2015 Red Hat, Inc.
#
# Authors:
#  Markus Armbruster <armbru@redhat.com>
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.

##
# = QMP introspection
##

##
# @query-qmp-schema:
#
# Command query-qmp-schema exposes the QMP wire ABI as an array of
# SchemaInfo.  This lets QMP clients figure out what commands and
# events are available in this QEMU, and their parameters and results.
#
# However, the SchemaInfo can't reflect all the rules and restrictions
# that apply to QMP.  It's interface introspection (figuring out
# what's there), not interface specification.  The specification is in
# the QAPI schema.
#
# Furthermore, while we strive to keep the QMP wire format
# backwards-compatible across qemu versions, the introspection output
# is not guaranteed to have the same stability.  For example, one
# version of qemu may list an object member as an optional
# non-variant, while another lists the same member only through the
# object's variants; or the type of a member may change from a generic
# string into a specific enum or from one specific type into an
# alternate that includes the original type alongside something else.
#
# Returns: array of @SchemaInfo, where each element describes an
# entity in the ABI: command, event, type, ...
#
# The order of the various SchemaInfo is unspecified; however, all
# names are guaranteed to be unique (no name will be duplicated with
# different meta-types).
#
# Note: the QAPI schema is also used to help define *internal*
# interfaces, by defining QAPI types.  These are not part of the QMP
# wire ABI, and therefore not returned by this command.
#
# Since: 2.5
##
{ 'command': 'query-qmp-schema',
  'returns': [ 'SchemaInfo' ],
  'gen': false }                # just to simplify qmp_query_json()

##
# @SchemaMetaType:
#
# This is a @SchemaInfo's meta type, i.e. the kind of entity it
# describes.
#
# @builtin: a predefined type such as 'int' or 'bool'.
#
# @enum: an enumeration type
#
# @array: an array type
#
# @object: an object type (struct or union)
#
# @alternate: an alternate type
#
# @command: a QMP command
#
# @event: a QMP event
#
# Since: 2.5
##
{ 'enum': 'SchemaMetaType',
  'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
            'command', 'event' ] }

##
# @SchemaInfo:
#
# @name: the entity's name, inherited from @base.
#        The SchemaInfo is always referenced by this name.
#        Commands and events have the name defined in the QAPI schema.
#        Unlike command and event names, type names are not part of
#        the wire ABI.  Consequently, type names are meaningless
#        strings here, although they are still guaranteed unique
#        regardless of @meta-type.
#
# @meta-type: the entity's meta type, inherited from @base.
#
# Additional members depend on the value of @meta-type.
#
# Since: 2.5
##
{ 'union': 'SchemaInfo',
  'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' },
  'discriminator': 'meta-type',
  'data': {
      'builtin': 'SchemaInfoBuiltin',
      'enum': 'SchemaInfoEnum',
      'array': 'SchemaInfoArray',
      'object': 'SchemaInfoObject',
      'alternate': 'SchemaInfoAlternate',
      'command': 'SchemaInfoCommand',
      'event': 'SchemaInfoEvent' } }

##
# @SchemaInfoBuiltin:
#
# Additional SchemaInfo members for meta-type 'builtin'.
#
# @json-type: the JSON type used for this type on the wire.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoBuiltin',
  'data': { 'json-type': 'JSONType' } }

##
# @JSONType:
#
# The four primitive and two structured types according to RFC 8259
# section 1, plus 'int' (split off 'number'), plus the obvious top
# type 'value'.
#
# Since: 2.5
##
{ 'enum': 'JSONType',
  'data': [ 'string', 'number', 'int', 'boolean', 'null',
            'object', 'array', 'value' ] }

##
# @SchemaInfoEnum:
#
# Additional SchemaInfo members for meta-type 'enum'.
#
# @values: the enumeration type's values, in no particular order.
#
# Values of this type are JSON string on the wire.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoEnum',
  'data': { 'values': ['str'] } }

##
# @SchemaInfoArray:
#
# Additional SchemaInfo members for meta-type 'array'.
#
# @element-type: the array type's element type.
#
# Values of this type are JSON array on the wire.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoArray',
  'data': { 'element-type': 'str' } }

##
# @SchemaInfoObject:
#
# Additional SchemaInfo members for meta-type 'object'.
#
# @members: the object type's (non-variant) members, in no particular order.
#
# @tag: the name of the member serving as type tag.
#       An element of @members with this name must exist.
#
# @variants: variant members, i.e. additional members that
#            depend on the type tag's value.  Present exactly when
#            @tag is present.  The variants are in no particular order,
#            and may even differ from the order of the values of the
#            enum type of the @tag.
#
# Values of this type are JSON object on the wire.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoObject',
  'data': { 'members': [ 'SchemaInfoObjectMember' ],
            '*tag': 'str',
            '*variants': [ 'SchemaInfoObjectVariant' ] } }

##
# @SchemaInfoObjectMember:
#
# An object member.
#
# @name: the member's name, as defined in the QAPI schema.
#
# @type: the name of the member's type.
#
# @default: default when used as command parameter.
#           If absent, the parameter is mandatory.
#           If present, the value must be null.  The parameter is
#           optional, and behavior when it's missing is not specified
#           here.
#           Future extension: if present and non-null, the parameter
#           is optional, and defaults to this value.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoObjectMember',
  'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
# @default's type must be null or match @type

##
# @SchemaInfoObjectVariant:
#
# The variant members for a value of the type tag.
#
# @case: a value of the type tag.
#
# @type: the name of the object type that provides the variant members
#        when the type tag has value @case.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoObjectVariant',
  'data': { 'case': 'str', 'type': 'str' } }

##
# @SchemaInfoAlternate:
#
# Additional SchemaInfo members for meta-type 'alternate'.
#
# @members: the alternate type's members, in no particular order.
#           The members' wire encoding is distinct, see
#           docs/devel/qapi-code-gen.txt section Alternate types.
#
# On the wire, this can be any of the members.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoAlternate',
  'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }

##
# @SchemaInfoAlternateMember:
#
# An alternate member.
#
# @type: the name of the member's type.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoAlternateMember',
  'data': { 'type': 'str' } }

##
# @SchemaInfoCommand:
#
# Additional SchemaInfo members for meta-type 'command'.
#
# @arg-type: the name of the object type that provides the command's
#            parameters.
#
# @ret-type: the name of the command's result type.
#
# @allow-oob: whether the command allows out-of-band execution,
#             defaults to false (Since: 2.12)
#
# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoCommand',
  'data': { 'arg-type': 'str', 'ret-type': 'str',
            '*allow-oob': 'bool' } }

##
# @SchemaInfoEvent:
#
# Additional SchemaInfo members for meta-type 'event'.
#
# @arg-type: the name of the object type that provides the event's
#            parameters.
#
# Since: 2.5
##
{ 'struct': 'SchemaInfoEvent',
  'data': { 'arg-type': 'str' } }