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' } }