# -*- 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)
#
# 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'.
#
# @string: JSON string
#
# @number: JSON number
#
# @int: JSON number that is an integer
#
# @boolean: literal ``false`` or ``true``
#
# @null: literal ``null``
#
# @object: JSON object
#
# @array: JSON array
#
# @value: any JSON 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
#     :doc:`/devel/qapi-code-gen` 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' } }