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