qapi/introspect.json

   1 # -*- Mode: Python -*-
   2 #
   3 # QAPI/QMP introspection
   4 #
   5 # Copyright (C) 2015 Red Hat, Inc.
   6 #
   7 # Authors:
   8 #  Markus Armbruster <armbru@redhat.com>
   9 #
  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.
  12
  13 ##
  14 # @query-qmp-schema
  15 #
  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.
  19 #
  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.
  24 #
  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.
  33 #
  34 # Returns: array of @SchemaInfo, where each element describes an
  35 # entity in the ABI: command, event, type, ...
  36 #
  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).
  40 #
  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.
  44 #
  45 # Since: 2.5
  46 ##
  47 { 'command': 'query-qmp-schema',
  48   'returns': [ 'SchemaInfo' ],
  49   'gen': false }                # just to simplify qmp_query_json()
  50
  51 ##
  52 # @SchemaMetaType
  53 #
  54 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
  55 # describes.
  56 #
  57 # @builtin: a predefined type such as 'int' or 'bool'.
  58 #
  59 # @enum: an enumeration type
  60 #
  61 # @array: an array type
  62 #
  63 # @object: an object type (struct or union)
  64 #
  65 # @alternate: an alternate type
  66 #
  67 # @command: a QMP command
  68 #
  69 # @event: a QMP event
  70 #
  71 # Since: 2.5
  72 ##
  73 { 'enum': 'SchemaMetaType',
  74   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
  75             'command', 'event' ] }
  76
  77 ##
  78 # @SchemaInfo
  79 #
  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.
  86 #
  87 # All references to other SchemaInfo are by name.
  88 #
  89 # @meta-type: the entity's meta type, inherited from @base.
  90 #
  91 # Additional members depend on the value of @meta-type.
  92 #
  93 # Since: 2.5
  94 ##
  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' } }
 106
 107 ##
 108 # @SchemaInfoBuiltin
 109 #
 110 # Additional SchemaInfo members for meta-type 'builtin'.
 111 #
 112 # @json-type: the JSON type used for this type on the wire.
 113 #
 114 # Since: 2.5
 115 ##
 116 { 'struct': 'SchemaInfoBuiltin',
 117   'data': { 'json-type': 'JSONType' } }
 118
 119 ##
 120 # @JSONType
 121 #
 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'.
 125 #
 126 # Since: 2.5
 127 ##
 128 { 'enum': 'JSONType',
 129   'data': [ 'string', 'number', 'int', 'boolean', 'null',
 130             'object', 'array', 'value' ] }
 131
 132 ##
 133 # @SchemaInfoEnum
 134 #
 135 # Additional SchemaInfo members for meta-type 'enum'.
 136 #
 137 # @values: the enumeration type's values, in no particular order.
 138 #
 139 # Values of this type are JSON string on the wire.
 140 #
 141 # Since: 2.5
 142 ##
 143 { 'struct': 'SchemaInfoEnum',
 144   'data': { 'values': ['str'] } }
 145
 146 ##
 147 # @SchemaInfoArray
 148 #
 149 # Additional SchemaInfo members for meta-type 'array'.
 150 #
 151 # @element-type: the array type's element type.
 152 #
 153 # Values of this type are JSON array on the wire.
 154 #
 155 # Since: 2.5
 156 ##
 157 { 'struct': 'SchemaInfoArray',
 158   'data': { 'element-type': 'str' } }
 159
 160 ##
 161 # @SchemaInfoObject
 162 #
 163 # Additional SchemaInfo members for meta-type 'object'.
 164 #
 165 # @members: the object type's (non-variant) members, in no particular order.
 166 #
 167 # @tag: #optional the name of the member serving as type tag.
 168 #       An element of @members with this name must exist.
 169 #
 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.
 175 #
 176 # Values of this type are JSON object on the wire.
 177 #
 178 # Since: 2.5
 179 ##
 180 { 'struct': 'SchemaInfoObject',
 181   'data': { 'members': [ 'SchemaInfoObjectMember' ],
 182             '*tag': 'str',
 183             '*variants': [ 'SchemaInfoObjectVariant' ] } }
 184
 185 ##
 186 # @SchemaInfoObjectMember
 187 #
 188 # An object member.
 189 #
 190 # @name: the member's name, as defined in the QAPI schema.
 191 #
 192 # @type: the name of the member's type.
 193 #
 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.
 201 #
 202 # Since: 2.5
 203 ##
 204 { 'struct': 'SchemaInfoObjectMember',
 205   'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
 206 # @default's type must be null or match @type
 207
 208 ##
 209 # @SchemaInfoObjectVariant
 210 #
 211 # The variant members for a value of the type tag.
 212 #
 213 # @case: a value of the type tag.
 214 #
 215 # @type: the name of the object type that provides the variant members
 216 #        when the type tag has value @case.
 217 #
 218 # Since: 2.5
 219 ##
 220 { 'struct': 'SchemaInfoObjectVariant',
 221   'data': { 'case': 'str', 'type': 'str' } }
 222
 223 ##
 224 # @SchemaInfoAlternate
 225 #
 226 # Additional SchemaInfo members for meta-type 'alternate'.
 227 #
 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.
 231 #
 232 # On the wire, this can be any of the members.
 233 #
 234 # Since: 2.5
 235 ##
 236 { 'struct': 'SchemaInfoAlternate',
 237   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
 238
 239 ##
 240 # @SchemaInfoAlternateMember
 241 #
 242 # An alternate member.
 243 #
 244 # @type: the name of the member's type.
 245 #
 246 # Since: 2.5
 247 ##
 248 { 'struct': 'SchemaInfoAlternateMember',
 249   'data': { 'type': 'str' } }
 250
 251 ##
 252 # @SchemaInfoCommand
 253 #
 254 # Additional SchemaInfo members for meta-type 'command'.
 255 #
 256 # @arg-type: the name of the object type that provides the command's
 257 #            parameters.
 258 #
 259 # @ret-type: the name of the command's result type.
 260 #
 261 # TODO @success-response (currently irrelevant, because it's QGA, not QMP)
 262 #
 263 # Since: 2.5
 264 ##
 265 { 'struct': 'SchemaInfoCommand',
 266   'data': { 'arg-type': 'str', 'ret-type': 'str' } }
 267
 268 ##
 269 # @SchemaInfoEvent
 270 #
 271 # Additional SchemaInfo members for meta-type 'event'.
 272 #
 273 # @arg-type: the name of the object type that provides the event's
 274 #            parameters.
 275 #
 276 # Since: 2.5
 277 ##
 278 { 'struct': 'SchemaInfoEvent',
 279   'data': { 'arg-type': 'str' } }