qapi/introspect.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4 # Copyright (C) 2015 Red Hat, Inc.
   5 #
   6 # Authors:
   7 #  Markus Armbruster <armbru@redhat.com>
   8 #
   9 # This work is licensed under the terms of the GNU GPL, version 2 or later.
  10 # See the COPYING file in the top-level directory.
  11
  12 ##
  13 # = QMP introspection
  14 ##
  15
  16 ##
  17 # @query-qmp-schema:
  18 #
  19 # Command query-qmp-schema exposes the QMP wire ABI as an array of
  20 # SchemaInfo.  This lets QMP clients figure out what commands and
  21 # events are available in this QEMU, and their parameters and results.
  22 #
  23 # However, the SchemaInfo can't reflect all the rules and restrictions
  24 # that apply to QMP.  It's interface introspection (figuring out
  25 # what's there), not interface specification.  The specification is in
  26 # the QAPI schema.
  27 #
  28 # Furthermore, while we strive to keep the QMP wire format
  29 # backwards-compatible across qemu versions, the introspection output
  30 # is not guaranteed to have the same stability.  For example, one
  31 # version of qemu may list an object member as an optional
  32 # non-variant, while another lists the same member only through the
  33 # object's variants; or the type of a member may change from a generic
  34 # string into a specific enum or from one specific type into an
  35 # alternate that includes the original type alongside something else.
  36 #
  37 # Returns: array of @SchemaInfo, where each element describes an
  38 #     entity in the ABI: command, event, type, ...
  39 #
  40 #     The order of the various SchemaInfo is unspecified; however, all
  41 #     names are guaranteed to be unique (no name will be duplicated
  42 #     with different meta-types).
  43 #
  44 # Note: the QAPI schema is also used to help define *internal*
  45 #     interfaces, by defining QAPI types.  These are not part of the
  46 #     QMP wire ABI, and therefore not returned by this command.
  47 #
  48 # Since: 2.5
  49 ##
  50 { 'command': 'query-qmp-schema',
  51   'returns': [ 'SchemaInfo' ],
  52   'allow-preconfig': true }
  53
  54 ##
  55 # @SchemaMetaType:
  56 #
  57 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
  58 # describes.
  59 #
  60 # @builtin: a predefined type such as 'int' or 'bool'.
  61 #
  62 # @enum: an enumeration type
  63 #
  64 # @array: an array type
  65 #
  66 # @object: an object type (struct or union)
  67 #
  68 # @alternate: an alternate type
  69 #
  70 # @command: a QMP command
  71 #
  72 # @event: a QMP event
  73 #
  74 # Since: 2.5
  75 ##
  76 { 'enum': 'SchemaMetaType',
  77   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
  78             'command', 'event' ] }
  79
  80 ##
  81 # @SchemaInfo:
  82 #
  83 # @name: the entity's name, inherited from @base.  The SchemaInfo is
  84 #     always referenced by this name.  Commands and events have the
  85 #     name defined in the QAPI schema.  Unlike command and event
  86 #     names, type names are not part of the wire ABI.  Consequently,
  87 #     type names are meaningless strings here, although they are still
  88 #     guaranteed unique 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.  (since 4.1 for object types, 4.2 for
  94 #     commands, 5.0 for the rest)
  95 #
  96 # Additional members depend on the value of @meta-type.
  97 #
  98 # Since: 2.5
  99 ##
 100 { 'union': 'SchemaInfo',
 101   'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
 102             '*features': [ 'str' ] },
 103   'discriminator': 'meta-type',
 104   'data': {
 105       'builtin': 'SchemaInfoBuiltin',
 106       'enum': 'SchemaInfoEnum',
 107       'array': 'SchemaInfoArray',
 108       'object': 'SchemaInfoObject',
 109       'alternate': 'SchemaInfoAlternate',
 110       'command': 'SchemaInfoCommand',
 111       'event': 'SchemaInfoEvent' } }
 112
 113 ##
 114 # @SchemaInfoBuiltin:
 115 #
 116 # Additional SchemaInfo members for meta-type 'builtin'.
 117 #
 118 # @json-type: the JSON type used for this type on the wire.
 119 #
 120 # Since: 2.5
 121 ##
 122 { 'struct': 'SchemaInfoBuiltin',
 123   'data': { 'json-type': 'JSONType' } }
 124
 125 ##
 126 # @JSONType:
 127 #
 128 # The four primitive and two structured types according to RFC 8259
 129 # section 1, plus 'int' (split off 'number'), plus the obvious top
 130 # type 'value'.
 131 #
 132 # Since: 2.5
 133 ##
 134 { 'enum': 'JSONType',
 135   'data': [ 'string', 'number', 'int', 'boolean', 'null',
 136             'object', 'array', 'value' ] }
 137
 138 ##
 139 # @SchemaInfoEnum:
 140 #
 141 # Additional SchemaInfo members for meta-type 'enum'.
 142 #
 143 # @members: the enum type's members, in no particular order (since
 144 #     6.2).
 145 #
 146 # @values: the enumeration type's member names, in no particular
 147 #     order.  Redundant with @members.  Just for backward
 148 #     compatibility.
 149 #
 150 # Features:
 151 #
 152 # @deprecated: Member @values is deprecated.  Use @members instead.
 153 #
 154 # Values of this type are JSON string on the wire.
 155 #
 156 # Since: 2.5
 157 ##
 158 { 'struct': 'SchemaInfoEnum',
 159   'data': { 'members': [ 'SchemaInfoEnumMember' ],
 160             'values': { 'type': [ 'str' ],
 161                         'features': [ 'deprecated' ] } } }
 162
 163 ##
 164 # @SchemaInfoEnumMember:
 165 #
 166 # An object member.
 167 #
 168 # @name: the member's name, as defined in the QAPI schema.
 169 #
 170 # @features: names of features associated with the member, in no
 171 #     particular order.
 172 #
 173 # Since: 6.2
 174 ##
 175 { 'struct': 'SchemaInfoEnumMember',
 176   'data': { 'name': 'str', '*features': [ 'str' ] } }
 177
 178 ##
 179 # @SchemaInfoArray:
 180 #
 181 # Additional SchemaInfo members for meta-type 'array'.
 182 #
 183 # @element-type: the array type's element type.
 184 #
 185 # Values of this type are JSON array on the wire.
 186 #
 187 # Since: 2.5
 188 ##
 189 { 'struct': 'SchemaInfoArray',
 190   'data': { 'element-type': 'str' } }
 191
 192 ##
 193 # @SchemaInfoObject:
 194 #
 195 # Additional SchemaInfo members for meta-type 'object'.
 196 #
 197 # @members: the object type's (non-variant) members, in no particular
 198 #     order.
 199 #
 200 # @tag: the name of the member serving as type tag.  An element of
 201 #     @members with this name must exist.
 202 #
 203 # @variants: variant members, i.e. additional members that depend on
 204 #     the type tag's value.  Present exactly when @tag is present.
 205 #     The variants are in no particular order, and may even differ
 206 #     from the order of the values of the enum type of the @tag.
 207 #
 208 # Values of this type are JSON object on the wire.
 209 #
 210 # Since: 2.5
 211 ##
 212 { 'struct': 'SchemaInfoObject',
 213   'data': { 'members': [ 'SchemaInfoObjectMember' ],
 214             '*tag': 'str',
 215             '*variants': [ 'SchemaInfoObjectVariant' ] } }
 216
 217 ##
 218 # @SchemaInfoObjectMember:
 219 #
 220 # An object member.
 221 #
 222 # @name: the member's name, as defined in the QAPI schema.
 223 #
 224 # @type: the name of the member's type.
 225 #
 226 # @default: default when used as command parameter.  If absent, the
 227 #     parameter is mandatory.  If present, the value must be null.
 228 #     The parameter is optional, and behavior when it's missing is not
 229 #     specified here.  Future extension: if present and non-null, the
 230 #     parameter is optional, and defaults to this value.
 231 #
 232 # @features: names of features associated with the member, in no
 233 #     particular order.  (since 5.0)
 234 #
 235 # Since: 2.5
 236 ##
 237 { 'struct': 'SchemaInfoObjectMember',
 238   'data': { 'name': 'str', 'type': 'str', '*default': 'any',
 239 # @default's type must be null or match @type
 240             '*features': [ 'str' ] } }
 241
 242 ##
 243 # @SchemaInfoObjectVariant:
 244 #
 245 # The variant members for a value of the type tag.
 246 #
 247 # @case: a value of the type tag.
 248 #
 249 # @type: the name of the object type that provides the variant members
 250 #     when the type tag has value @case.
 251 #
 252 # Since: 2.5
 253 ##
 254 { 'struct': 'SchemaInfoObjectVariant',
 255   'data': { 'case': 'str', 'type': 'str' } }
 256
 257 ##
 258 # @SchemaInfoAlternate:
 259 #
 260 # Additional SchemaInfo members for meta-type 'alternate'.
 261 #
 262 # @members: the alternate type's members, in no particular order.  The
 263 #     members' wire encoding is distinct, see
 264 #     docs/devel/qapi-code-gen.txt section Alternate types.
 265 #
 266 # On the wire, this can be any of the members.
 267 #
 268 # Since: 2.5
 269 ##
 270 { 'struct': 'SchemaInfoAlternate',
 271   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
 272
 273 ##
 274 # @SchemaInfoAlternateMember:
 275 #
 276 # An alternate member.
 277 #
 278 # @type: the name of the member's type.
 279 #
 280 # Since: 2.5
 281 ##
 282 { 'struct': 'SchemaInfoAlternateMember',
 283   'data': { 'type': 'str' } }
 284
 285 ##
 286 # @SchemaInfoCommand:
 287 #
 288 # Additional SchemaInfo members for meta-type 'command'.
 289 #
 290 # @arg-type: the name of the object type that provides the command's
 291 #     parameters.
 292 #
 293 # @ret-type: the name of the command's result type.
 294 #
 295 # @allow-oob: whether the command allows out-of-band execution,
 296 #     defaults to false (Since: 2.12)
 297 #
 298 # TODO: @success-response (currently irrelevant, because it's QGA, not
 299 #     QMP)
 300 #
 301 # Since: 2.5
 302 ##
 303 { 'struct': 'SchemaInfoCommand',
 304   'data': { 'arg-type': 'str', 'ret-type': 'str',
 305             '*allow-oob': 'bool' } }
 306
 307 ##
 308 # @SchemaInfoEvent:
 309 #
 310 # Additional SchemaInfo members for meta-type 'event'.
 311 #
 312 # @arg-type: the name of the object type that provides the event's
 313 #     parameters.
 314 #
 315 # Since: 2.5
 316 ##
 317 { 'struct': 'SchemaInfoEvent',
 318   'data': { 'arg-type': 'str' } }