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