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

##
# = QMP monitor control
##

##
# @qmp_capabilities:
#
# Enable QMP capabilities.
#
# @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)
#
# .. qmp-example::
#
#     -> { "execute": "qmp_capabilities",
#          "arguments": { "enable": [ "oob" ] } }
#     <- { "return": {} }
#
# .. note:: 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 :doc:`/interop/qmp-spec`)
#
# .. note:: 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.rst 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
##
{ '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
#
# .. qmp-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
##
{ '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
#
# .. qmp-example::
#
#     -> { "execute": "query-commands" }
#     <- {
#          "return":[
#             {
#                "name":"query-balloon"
#             },
#             {
#                "name":"system_powerdown"
#             },
#             ...
#          ]
#        }
#
# This example has been shortened as the real response is too long.
#
##
{ 'command': 'query-commands', 'returns': ['CommandInfo'],
  'allow-preconfig': true }

##
# @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
#
# .. qmp-example::
#
#     -> { "execute": "quit" }
#     <- { "return": {} }
##
{ 'command': 'quit',
  'allow-preconfig': true }

##
# @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'
  } }