# -*- Mode: Python -*-
# vim: filetype=python
#

##
# = QMP monitor control
##

##
# @qmp_capabilities:
#
# Enable QMP capabilities.
#
# Arguments:
#
# @enable: An optional list of QMPCapability values to enable.  The
#          client must not enable any capability that is not
#          mentioned in the QMP greeting message.  If the field is not
#          provided, it means no QMP capabilities will be enabled.
#          (since 2.12)
#
# Example:
#
# -> { "execute": "qmp_capabilities",
#      "arguments": { "enable": [ "oob" ] } }
# <- { "return": {} }
#
# Notes: This command is valid exactly when first connecting: it must be
#        issued before any other command will be accepted, and will fail once the
#        monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
#
#        The QMP client needs to explicitly enable QMP capabilities, otherwise
#        all the QMP capabilities will be turned off by default.
#
# Since: 0.13
#
##
{ 'command': 'qmp_capabilities',
  'data': { '*enable': [ 'QMPCapability' ] },
  'allow-preconfig': true }

##
# @QMPCapability:
#
# Enumeration of capabilities to be advertised during initial client
# connection, used for agreeing on particular QMP extension behaviors.
#
# @oob: QMP ability to support out-of-band requests.
#       (Please refer to qmp-spec.txt for more information on OOB)
#
# Since: 2.12
#
##
{ 'enum': 'QMPCapability',
  'data': [ 'oob' ] }

##
# @VersionTriple:
#
# A three-part version number.
#
# @major: The major version number.
#
# @minor: The minor version number.
#
# @micro: The micro version number.
#
# Since: 2.4
##
{ 'struct': 'VersionTriple',
  'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }


##
# @VersionInfo:
#
# A description of QEMU's version.
#
# @qemu: The version of QEMU.  By current convention, a micro
#        version of 50 signifies a development branch.  A micro version
#        greater than or equal to 90 signifies a release candidate for
#        the next minor version.  A micro version of less than 50
#        signifies a stable release.
#
# @package: QEMU will always set this field to an empty string.  Downstream
#           versions of QEMU should set this to a non-empty string.  The
#           exact format depends on the downstream however it highly
#           recommended that a unique name is used.
#
# Since: 0.14.0
##
{ 'struct': 'VersionInfo',
  'data': {'qemu': 'VersionTriple', 'package': 'str'} }

##
# @query-version:
#
# Returns the current version of QEMU.
#
# Returns: A @VersionInfo object describing the current version of QEMU.
#
# Since: 0.14.0
#
# Example:
#
# -> { "execute": "query-version" }
# <- {
#       "return":{
#          "qemu":{
#             "major":0,
#             "minor":11,
#             "micro":5
#          },
#          "package":""
#       }
#    }
#
##
{ 'command': 'query-version', 'returns': 'VersionInfo',
  'allow-preconfig': true }

##
# @CommandInfo:
#
# Information about a QMP command
#
# @name: The command name
#
# Since: 0.14.0
##
{ 'struct': 'CommandInfo', 'data': {'name': 'str'} }

##
# @query-commands:
#
# Return a list of supported QMP commands by this server
#
# Returns: A list of @CommandInfo for all supported commands
#
# Since: 0.14.0
#
# Example:
#
# -> { "execute": "query-commands" }
# <- {
#      "return":[
#         {
#            "name":"query-balloon"
#         },
#         {
#            "name":"system_powerdown"
#         }
#      ]
#    }
#
# Note: This example has been shortened as the real response is too long.
#
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'],
  'allow-preconfig': true }

##
# @EventInfo:
#
# Information about a QMP event
#
# @name: The event name
#
# Since: 1.2.0
##
{ 'struct': 'EventInfo', 'data': {'name': 'str'} }

##
# @query-events:
#
# Return information on QMP events.
#
# Features:
# @deprecated: This command is deprecated, because its output doesn't
#     reflect compile-time configuration.  Use 'query-qmp-schema'
#     instead.
#
# Returns: A list of @EventInfo.
#
# Since: 1.2.0
#
# Example:
#
# -> { "execute": "query-events" }
# <- {
#      "return": [
#          {
#             "name":"SHUTDOWN"
#          },
#          {
#             "name":"RESET"
#          }
#       ]
#    }
#
# Note: This example has been shortened as the real response is too long.
#
##
{ 'command': 'query-events', 'returns': ['EventInfo'],
  'features': [ 'deprecated' ] }

##
# @quit:
#
# This command will cause the QEMU process to exit gracefully.  While every
# attempt is made to send the QMP response before terminating, this is not
# guaranteed.  When using this interface, a premature EOF would not be
# unexpected.
#
# Since: 0.14.0
#
# Example:
#
# -> { "execute": "quit" }
# <- { "return": {} }
##
{ 'command': 'quit' }

##
# @MonitorMode:
#
# An enumeration of monitor modes.
#
# @readline: HMP monitor (human-oriented command line interface)
#
# @control: QMP monitor (JSON-based machine interface)
#
# Since: 5.0
##
{ 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }

##
# @MonitorOptions:
#
# Options to be used for adding a new monitor.
#
# @id:          Name of the monitor
#
# @mode:        Selects the monitor mode (default: readline in the system
#               emulator, control in qemu-storage-daemon)
#
# @pretty:      Enables pretty printing (QMP only)
#
# @chardev:     Name of a character device to expose the monitor on
#
# Since: 5.0
##
{ 'struct': 'MonitorOptions',
  'data': {
      '*id': 'str',
      '*mode': 'MonitorMode',
      '*pretty': 'bool',
      'chardev': 'str'
  } }