qemu

introspect.json (8828B)

---

 # -*- Mode: Python -*-
 # vim: filetype=python
 #
 # Copyright (C) 2015 Red Hat, Inc.
 #
 # Authors:
 #  Markus Armbruster <armbru@redhat.com>
 #
 # This work is licensed under the terms of the GNU GPL, version 2 or later.
 # See the COPYING file in the top-level directory.
 
 ##
 # = QMP introspection
 ##
 
 ##
 # @query-qmp-schema:
 #
 # Command query-qmp-schema exposes the QMP wire ABI as an array of
 # SchemaInfo.  This lets QMP clients figure out what commands and
 # events are available in this QEMU, and their parameters and results.
 #
 # However, the SchemaInfo can't reflect all the rules and restrictions
 # that apply to QMP.  It's interface introspection (figuring out
 # what's there), not interface specification.  The specification is in
 # the QAPI schema.
 #
 # Furthermore, while we strive to keep the QMP wire format
 # backwards-compatible across qemu versions, the introspection output
 # is not guaranteed to have the same stability.  For example, one
 # version of qemu may list an object member as an optional
 # non-variant, while another lists the same member only through the
 # object's variants; or the type of a member may change from a generic
 # string into a specific enum or from one specific type into an
 # alternate that includes the original type alongside something else.
 #
 # Returns: array of @SchemaInfo, where each element describes an
 #          entity in the ABI: command, event, type, ...
 #
 #          The order of the various SchemaInfo is unspecified; however, all
 #          names are guaranteed to be unique (no name will be duplicated with
 #          different meta-types).
 #
 # Note: the QAPI schema is also used to help define *internal*
 #       interfaces, by defining QAPI types.  These are not part of the QMP
 #       wire ABI, and therefore not returned by this command.
 #
 # Since: 2.5
 ##
 { 'command': 'query-qmp-schema',
   'returns': [ 'SchemaInfo' ],
   'allow-preconfig': true }
 
 ##
 # @SchemaMetaType:
 #
 # This is a @SchemaInfo's meta type, i.e. the kind of entity it
 # describes.
 #
 # @builtin: a predefined type such as 'int' or 'bool'.
 #
 # @enum: an enumeration type
 #
 # @array: an array type
 #
 # @object: an object type (struct or union)
 #
 # @alternate: an alternate type
 #
 # @command: a QMP command
 #
 # @event: a QMP event
 #
 # Since: 2.5
 ##
 { 'enum': 'SchemaMetaType',
   'data': [ 'builtin', 'enum', 'array', 'object', 'alternate',
             'command', 'event' ] }
 
 ##
 # @SchemaInfo:
 #
 # @name: the entity's name, inherited from @base.
 #        The SchemaInfo is always referenced by this name.
 #        Commands and events have the name defined in the QAPI schema.
 #        Unlike command and event names, type names are not part of
 #        the wire ABI.  Consequently, type names are meaningless
 #        strings here, although they are still guaranteed unique
 #        regardless of @meta-type.
 #
 # @meta-type: the entity's meta type, inherited from @base.
 #
 # @features: names of features associated with the entity, in no
 #            particular order.
 #            (since 4.1 for object types, 4.2 for commands, 5.0 for
 #            the rest)
 #
 # Additional members depend on the value of @meta-type.
 #
 # Since: 2.5
 ##
 { 'union': 'SchemaInfo',
   'base': { 'name': 'str', 'meta-type': 'SchemaMetaType',
             '*features': [ 'str' ] },
   'discriminator': 'meta-type',
   'data': {
       'builtin': 'SchemaInfoBuiltin',
       'enum': 'SchemaInfoEnum',
       'array': 'SchemaInfoArray',
       'object': 'SchemaInfoObject',
       'alternate': 'SchemaInfoAlternate',
       'command': 'SchemaInfoCommand',
       'event': 'SchemaInfoEvent' } }
 
 ##
 # @SchemaInfoBuiltin:
 #
 # Additional SchemaInfo members for meta-type 'builtin'.
 #
 # @json-type: the JSON type used for this type on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoBuiltin',
   'data': { 'json-type': 'JSONType' } }
 
 ##
 # @JSONType:
 #
 # The four primitive and two structured types according to RFC 8259
 # section 1, plus 'int' (split off 'number'), plus the obvious top
 # type 'value'.
 #
 # Since: 2.5
 ##
 { 'enum': 'JSONType',
   'data': [ 'string', 'number', 'int', 'boolean', 'null',
             'object', 'array', 'value' ] }
 
 ##
 # @SchemaInfoEnum:
 #
 # Additional SchemaInfo members for meta-type 'enum'.
 #
 # @members: the enum type's members, in no particular order
 #           (since 6.2).
 #
 # @values: the enumeration type's member names, in no particular order.
 #          Redundant with @members.  Just for backward compatibility.
 #
 # Features:
 # @deprecated: Member @values is deprecated.  Use @members instead.
 #
 # Values of this type are JSON string on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoEnum',
   'data': { 'members': [ 'SchemaInfoEnumMember' ],
             'values': { 'type': [ 'str' ],
                         'features': [ 'deprecated' ] } } }
 
 ##
 # @SchemaInfoEnumMember:
 #
 # An object member.
 #
 # @name: the member's name, as defined in the QAPI schema.
 #
 # @features: names of features associated with the member, in no
 #            particular order.
 #
 # Since: 6.2
 ##
 { 'struct': 'SchemaInfoEnumMember',
   'data': { 'name': 'str', '*features': [ 'str' ] } }
 
 ##
 # @SchemaInfoArray:
 #
 # Additional SchemaInfo members for meta-type 'array'.
 #
 # @element-type: the array type's element type.
 #
 # Values of this type are JSON array on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoArray',
   'data': { 'element-type': 'str' } }
 
 ##
 # @SchemaInfoObject:
 #
 # Additional SchemaInfo members for meta-type 'object'.
 #
 # @members: the object type's (non-variant) members, in no particular order.
 #
 # @tag: the name of the member serving as type tag.
 #       An element of @members with this name must exist.
 #
 # @variants: variant members, i.e. additional members that
 #            depend on the type tag's value.  Present exactly when
 #            @tag is present.  The variants are in no particular order,
 #            and may even differ from the order of the values of the
 #            enum type of the @tag.
 #
 # Values of this type are JSON object on the wire.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoObject',
   'data': { 'members': [ 'SchemaInfoObjectMember' ],
             '*tag': 'str',
             '*variants': [ 'SchemaInfoObjectVariant' ] } }
 
 ##
 # @SchemaInfoObjectMember:
 #
 # An object member.
 #
 # @name: the member's name, as defined in the QAPI schema.
 #
 # @type: the name of the member's type.
 #
 # @default: default when used as command parameter.
 #           If absent, the parameter is mandatory.
 #           If present, the value must be null.  The parameter is
 #           optional, and behavior when it's missing is not specified
 #           here.
 #           Future extension: if present and non-null, the parameter
 #           is optional, and defaults to this value.
 #
 # @features: names of features associated with the member, in no
 #            particular order.  (since 5.0)
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoObjectMember',
   'data': { 'name': 'str', 'type': 'str', '*default': 'any',
 # @default's type must be null or match @type
             '*features': [ 'str' ] } }
 
 ##
 # @SchemaInfoObjectVariant:
 #
 # The variant members for a value of the type tag.
 #
 # @case: a value of the type tag.
 #
 # @type: the name of the object type that provides the variant members
 #        when the type tag has value @case.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoObjectVariant',
   'data': { 'case': 'str', 'type': 'str' } }
 
 ##
 # @SchemaInfoAlternate:
 #
 # Additional SchemaInfo members for meta-type 'alternate'.
 #
 # @members: the alternate type's members, in no particular order.
 #           The members' wire encoding is distinct, see
 #           docs/devel/qapi-code-gen.txt section Alternate types.
 #
 # On the wire, this can be any of the members.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoAlternate',
   'data': { 'members': [ 'SchemaInfoAlternateMember' ] } }
 
 ##
 # @SchemaInfoAlternateMember:
 #
 # An alternate member.
 #
 # @type: the name of the member's type.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoAlternateMember',
   'data': { 'type': 'str' } }
 
 ##
 # @SchemaInfoCommand:
 #
 # Additional SchemaInfo members for meta-type 'command'.
 #
 # @arg-type: the name of the object type that provides the command's
 #            parameters.
 #
 # @ret-type: the name of the command's result type.
 #
 # @allow-oob: whether the command allows out-of-band execution,
 #             defaults to false (Since: 2.12)
 #
 # TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoCommand',
   'data': { 'arg-type': 'str', 'ret-type': 'str',
             '*allow-oob': 'bool' } }
 
 ##
 # @SchemaInfoEvent:
 #
 # Additional SchemaInfo members for meta-type 'event'.
 #
 # @arg-type: the name of the object type that provides the event's
 #            parameters.
 #
 # Since: 2.5
 ##
 { 'struct': 'SchemaInfoEvent',
   'data': { 'arg-type': 'str' } }