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