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