qapi/control.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4
   5 ##
   6 # = QMP monitor control
   7 ##
   8
   9 ##
  10 # @qmp_capabilities:
  11 #
  12 # Enable QMP capabilities.
  13 #
  14 # @enable: An optional list of QMPCapability values to enable.  The
  15 #     client must not enable any capability that is not mentioned in
  16 #     the QMP greeting message.  If the field is not provided, it
  17 #     means no QMP capabilities will be enabled.  (since 2.12)
  18 #
  19 # Example:
  20 #
  21 #     -> { "execute": "qmp_capabilities",
  22 #          "arguments": { "enable": [ "oob" ] } }
  23 #     <- { "return": {} }
  24 #
  25 # .. note:: This command is valid exactly when first connecting: it must
  26 #    be issued before any other command will be accepted, and will fail
  27 #    once the monitor is accepting other commands.  (see qemu
  28 #    docs/interop/qmp-spec.rst)
  29 #
  30 # .. note:: The QMP client needs to explicitly enable QMP capabilities,
  31 #    otherwise all the QMP capabilities will be turned off by default.
  32 #
  33 # Since: 0.13
  34 ##
  35 { 'command': 'qmp_capabilities',
  36   'data': { '*enable': [ 'QMPCapability' ] },
  37   'allow-preconfig': true }
  38
  39 ##
  40 # @QMPCapability:
  41 #
  42 # Enumeration of capabilities to be advertised during initial client
  43 # connection, used for agreeing on particular QMP extension behaviors.
  44 #
  45 # @oob: QMP ability to support out-of-band requests.  (Please refer to
  46 #     qmp-spec.rst for more information on OOB)
  47 #
  48 # Since: 2.12
  49 ##
  50 { 'enum': 'QMPCapability',
  51   'data': [ 'oob' ] }
  52
  53 ##
  54 # @VersionTriple:
  55 #
  56 # A three-part version number.
  57 #
  58 # @major: The major version number.
  59 #
  60 # @minor: The minor version number.
  61 #
  62 # @micro: The micro version number.
  63 #
  64 # Since: 2.4
  65 ##
  66 { 'struct': 'VersionTriple',
  67   'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
  68
  69 ##
  70 # @VersionInfo:
  71 #
  72 # A description of QEMU's version.
  73 #
  74 # @qemu: The version of QEMU.  By current convention, a micro version
  75 #     of 50 signifies a development branch.  A micro version greater
  76 #     than or equal to 90 signifies a release candidate for the next
  77 #     minor version.  A micro version of less than 50 signifies a
  78 #     stable release.
  79 #
  80 # @package: QEMU will always set this field to an empty string.
  81 #     Downstream versions of QEMU should set this to a non-empty
  82 #     string.  The exact format depends on the downstream however it
  83 #     highly recommended that a unique name is used.
  84 #
  85 # Since: 0.14
  86 ##
  87 { 'struct': 'VersionInfo',
  88   'data': {'qemu': 'VersionTriple', 'package': 'str'} }
  89
  90 ##
  91 # @query-version:
  92 #
  93 # Returns the current version of QEMU.
  94 #
  95 # Returns: A @VersionInfo object describing the current version of
  96 #     QEMU.
  97 #
  98 # Since: 0.14
  99 #
 100 # Example:
 101 #
 102 #     -> { "execute": "query-version" }
 103 #     <- {
 104 #           "return":{
 105 #              "qemu":{
 106 #                 "major":0,
 107 #                 "minor":11,
 108 #                 "micro":5
 109 #              },
 110 #              "package":""
 111 #           }
 112 #        }
 113 ##
 114 { 'command': 'query-version', 'returns': 'VersionInfo',
 115   'allow-preconfig': true }
 116
 117 ##
 118 # @CommandInfo:
 119 #
 120 # Information about a QMP command
 121 #
 122 # @name: The command name
 123 #
 124 # Since: 0.14
 125 ##
 126 { 'struct': 'CommandInfo', 'data': {'name': 'str'} }
 127
 128 ##
 129 # @query-commands:
 130 #
 131 # Return a list of supported QMP commands by this server
 132 #
 133 # Returns: A list of @CommandInfo for all supported commands
 134 #
 135 # Since: 0.14
 136 #
 137 # Example:
 138 #
 139 #     -> { "execute": "query-commands" }
 140 #     <- {
 141 #          "return":[
 142 #             {
 143 #                "name":"query-balloon"
 144 #             },
 145 #             {
 146 #                "name":"system_powerdown"
 147 #             },
 148 #             ...
 149 #          ]
 150 #        }
 151 #
 152 # This example has been shortened as the real response is too long.
 153 #
 154 ##
 155 { 'command': 'query-commands', 'returns': ['CommandInfo'],
 156   'allow-preconfig': true }
 157
 158 ##
 159 # @quit:
 160 #
 161 # This command will cause the QEMU process to exit gracefully.  While
 162 # every attempt is made to send the QMP response before terminating,
 163 # this is not guaranteed.  When using this interface, a premature EOF
 164 # would not be unexpected.
 165 #
 166 # Since: 0.14
 167 #
 168 # Example:
 169 #
 170 #     -> { "execute": "quit" }
 171 #     <- { "return": {} }
 172 ##
 173 { 'command': 'quit',
 174   'allow-preconfig': true }
 175
 176 ##
 177 # @MonitorMode:
 178 #
 179 # An enumeration of monitor modes.
 180 #
 181 # @readline: HMP monitor (human-oriented command line interface)
 182 #
 183 # @control: QMP monitor (JSON-based machine interface)
 184 #
 185 # Since: 5.0
 186 ##
 187 { 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }
 188
 189 ##
 190 # @MonitorOptions:
 191 #
 192 # Options to be used for adding a new monitor.
 193 #
 194 # @id: Name of the monitor
 195 #
 196 # @mode: Selects the monitor mode (default: readline in the system
 197 #     emulator, control in qemu-storage-daemon)
 198 #
 199 # @pretty: Enables pretty printing (QMP only)
 200 #
 201 # @chardev: Name of a character device to expose the monitor on
 202 #
 203 # Since: 5.0
 204 ##
 205 { 'struct': 'MonitorOptions',
 206   'data': {
 207       '*id': 'str',
 208       '*mode': 'MonitorMode',
 209       '*pretty': 'bool',
 210       'chardev': 'str'
 211   } }