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 # Returns: array of @SchemaInfo, where each element describes an
  26 # entity in the ABI: command, event, type, ...
  27 #
  28 # Note: the QAPI schema is also used to help define *internal*
  29 # interfaces, by defining QAPI types.  These are not part of the QMP
  30 # wire ABI, and therefore not returned by this command.
  31 #
  32 # Since: 2.5
  33 ##
  34 { 'command': 'query-qmp-schema',
  35   'returns': [ 'SchemaInfo' ],
  36   'gen': false }                # just to simplify qmp_query_json()
  37
  38 ##
  39 # @SchemaMetaType
  40 #
  41 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
  42 # describes.
  43 #
  44 # @builtin: a predefined type such as 'int' or 'bool'.
  45 #
  46 # @enum: an enumeration type
  47 #
  48 # @array: an array type
  49 #
  50 # @object: an object type (struct or union)
  51 #
  52 # @alternate: an alternate type
  53 #
  54 # @command: a QMP command
  55 #
  56 # @event: a QMP event
  57 #
  58 # Since: 2.5
  59 ##
  60 { 'enum': 'SchemaMetaType',
  61   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
  62             'command', 'event' ] }
  63
  64 ##
  65 # @SchemaInfoBase
  66 #
  67 # Members common to any @SchemaInfo.
  68 #
  69 # Since: 2.5
  70 ##
  71 { 'struct': 'SchemaInfoBase',
  72   'data': { 'name': 'str', 'meta-type': 'SchemaMetaType' } }
  73
  74 ##
  75 # @SchemaInfo
  76 #
  77 # @name: the entity's name, inherited from @base.
  78 #        Commands and events have the name defined in the QAPI schema.
  79 #        Unlike command and event names, type names are not part of
  80 #        the wire ABI.  Consequently, type names are meaningless
  81 #        strings here.
  82 #
  83 # All references to other SchemaInfo are by name.
  84 #
  85 # @meta-type: the entity's meta type, inherited from @base.
  86 #
  87 # Additional members depend on the value of @meta-type.
  88 #
  89 # Since: 2.5
  90 ##
  91 { 'union': 'SchemaInfo',
  92   'base': 'SchemaInfoBase',
  93   'discriminator': 'meta-type',
  94   'data': {
  95       'builtin': 'SchemaInfoBuiltin',
  96       'enum': 'SchemaInfoEnum',
  97       'array': 'SchemaInfoArray',
  98       'object': 'SchemaInfoObject',
  99       'alternate': 'SchemaInfoAlternate',
 100       'command': 'SchemaInfoCommand',
 101       'event': 'SchemaInfoEvent' } }
 102
 103 ##
 104 # @SchemaInfoBuiltin
 105 #
 106 # Additional SchemaInfo members for meta-type 'builtin'.
 107 #
 108 # @json-type: the JSON type used for this type on the wire.
 109 #
 110 # Since: 2.5
 111 ##
 112 { 'struct': 'SchemaInfoBuiltin',
 113   'data': { 'json-type': 'JSONType' } }
 114
 115 ##
 116 # @JSONType
 117 #
 118 # The four primitive and two structured types according to RFC 7159
 119 # section 1, plus 'int' (split off 'number'), plus the obvious top
 120 # type 'value'.
 121 #
 122 # Since: 2.5
 123 ##
 124 { 'enum': 'JSONType',
 125   'data': [ 'string', 'number', 'int', 'boolean', 'null',
 126             'object', 'array', 'value' ] }
 127
 128 ##
 129 # @SchemaInfoEnum
 130 #
 131 # Additional SchemaInfo members for meta-type 'enum'.
 132 #
 133 # @values: the enumeration type's values.
 134 #
 135 # Values of this type are JSON string on the wire.
 136 #
 137 # Since: 2.5
 138 ##
 139 { 'struct': 'SchemaInfoEnum',
 140   'data': { 'values': ['str'] } }
 141
 142 ##
 143 # @SchemaInfoArray
 144 #
 145 # Additional SchemaInfo members for meta-type 'array'.
 146 #
 147 # @element-type: the array type's element type.
 148 #
 149 # Values of this type are JSON array on the wire.
 150 #
 151 # Since: 2.5
 152 ##
 153 { 'struct': 'SchemaInfoArray',
 154   'data': { 'element-type': 'str' } }
 155
 156 ##
 157 # @SchemaInfoObject
 158 #
 159 # Additional SchemaInfo members for meta-type 'object'.
 160 #
 161 # @members: the object type's (non-variant) members.
 162 #
 163 # @tag: #optional the name of the member serving as type tag.
 164 #       An element of @members with this name must exist.
 165 #
 166 # @variants: #optional variant members, i.e. additional members that
 167 #            depend on the type tag's value.  Present exactly when
 168 #            @tag is present.
 169 #
 170 # Values of this type are JSON object on the wire.
 171 #
 172 # Since: 2.5
 173 ##
 174 { 'struct': 'SchemaInfoObject',
 175   'data': { 'members': [ 'SchemaInfoObjectMember' ],
 176             '*tag': 'str',
 177             '*variants': [ 'SchemaInfoObjectVariant' ] } }
 178
 179 ##
 180 # @SchemaInfoObjectMember
 181 #
 182 # An object member.
 183 #
 184 # @name: the member's name, as defined in the QAPI schema.
 185 #
 186 # @type: the name of the member's type.
 187 #
 188 # @default: #optional default when used as command parameter.
 189 #           If absent, the parameter is mandatory.
 190 #           If present, the value must be null.  The parameter is
 191 #           optional, and behavior when it's missing is not specified
 192 #           here.
 193 #           Future extension: if present and non-null, the parameter
 194 #           is optional, and defaults to this value.
 195 #
 196 # Since: 2.5
 197 ##
 198 { 'struct': 'SchemaInfoObjectMember',
 199   'data': { 'name': 'str', 'type': 'str', '*default': 'any' } }
 200 # @default's type must be null or match @type
 201
 202 ##
 203 # @SchemaInfoObjectVariant
 204 #
 205 # The variant members for a value of the type tag.
 206 #
 207 # @case: a value of the type tag.
 208 #
 209 # @type: the name of the object type that provides the variant members
 210 #        when the type tag has value @case.
 211 #
 212 # Since: 2.5
 213 ##
 214 { 'struct': 'SchemaInfoObjectVariant',
 215   'data': { 'case': 'str', 'type': 'str' } }
 216
 217 ##
 218 # @SchemaInfoAlternate
 219 #
 220 # Additional SchemaInfo members for meta-type 'alternate'.
 221 #
 222 # @members: the alternate type's members.
 223 #           The members' wire encoding is distinct, see
 224 #           docs/qapi-code-gen.txt section Alternate types.
 225 #
 226 # On the wire, this can be any of the members.
 227 #
 228 # Since: 2.5
 229 ##
 230 { 'struct': 'SchemaInfoAlternate',
 231   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
 232
 233 ##
 234 # @SchemaInfoAlternateMember
 235 #
 236 # An alternate member.
 237 #
 238 # @type: the name of the member's type.
 239 #
 240 # Since: 2.5
 241 ##
 242 { 'struct': 'SchemaInfoAlternateMember',
 243   'data': { 'type': 'str' } }
 244
 245 ##
 246 # @SchemaInfoCommand
 247 #
 248 # Additional SchemaInfo members for meta-type 'command'.
 249 #
 250 # @arg-type: the name of the object type that provides the command's
 251 #            parameters.
 252 #
 253 # @ret-type: the name of the command's result type.
 254 #
 255 # TODO @success-response (currently irrelevant, because it's QGA, not QMP)
 256 #
 257 # Since: 2.5
 258 ##
 259 { 'struct': 'SchemaInfoCommand',
 260   'data': { 'arg-type': 'str', 'ret-type': 'str' } }
 261
 262 ##
 263 # @SchemaInfoEvent
 264 #
 265 # Additional SchemaInfo members for meta-type 'event'.
 266 #
 267 # @arg-type: the name of the object type that provides the event's
 268 #            parameters.
 269 #
 270 # Since: 2.5
 271 ##
 272 { 'struct': 'SchemaInfoEvent',
 273   'data': { 'arg-type': 'str' } }