docs/qmp-commands.txt

   1                         QMP Supported Commands
   2                         ----------------------
   3
   4 This document describes all commands currently supported by QMP.
   5
   6 Most of the time their usage is exactly the same as in the user Monitor, this
   7 means that any other document which also describe commands (the manpage,
   8 QEMU's manual, etc) can and should be consulted.
   9
  10 QMP has two types of commands: regular and query commands. Regular commands
  11 usually change the Virtual Machine's state someway, while query commands just
  12 return information. The sections below are divided accordingly.
  13
  14 It's important to observe that all communication examples are formatted in
  15 a reader-friendly way, so that they're easier to understand. However, in real
  16 protocol usage, they're emitted as a single line.
  17
  18 Also, the following notation is used to denote data flow:
  19
  20 -> data issued by the Client
  21 <- Server data response
  22
  23 Please, refer to the QMP specification (docs/qmp-spec.txt) for detailed
  24 information on the Server command and response formats.
  25
  26 NOTE: This document is temporary and will be replaced soon.
  27
  28 1. Stability Considerations
  29 ===========================
  30
  31 The current QMP command set (described in this file) may be useful for a
  32 number of use cases, however it's limited and several commands have bad
  33 defined semantics, specially with regard to command completion.
  34
  35 These problems are going to be solved incrementally in the next QEMU releases
  36 and we're going to establish a deprecation policy for badly defined commands.
  37
  38 If you're planning to adopt QMP, please observe the following:
  39
  40     1. The deprecation policy will take effect and be documented soon, please
  41        check the documentation of each used command as soon as a new release of
  42        QEMU is available
  43
  44     2. DO NOT rely on anything which is not explicit documented
  45
  46     3. Errors, in special, are not documented. Applications should NOT check
  47        for specific errors classes or data (it's strongly recommended to only
  48        check for the "error" key)
  49
  50 2. Regular Commands
  51 ===================
  52
  53 Server's responses in the examples below are always a success response, please
  54 refer to the QMP specification for more details on error responses.
  55
  56 device_add
  57 ----------
  58
  59 Add a device.
  60
  61 Arguments:
  62
  63 - "driver": the name of the new device's driver (json-string)
  64 - "bus": the device's parent bus (device tree path, json-string, optional)
  65 - "id": the device's ID, must be unique (json-string)
  66 - device properties
  67
  68 Example:
  69
  70 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
  71 <- { "return": {} }
  72
  73 Notes:
  74
  75 (1) For detailed information about this command, please refer to the
  76     'docs/qdev-device-use.txt' file.
  77
  78 (2) It's possible to list device properties by running QEMU with the
  79     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
  80
  81 cpu
  82 ---
  83
  84 Set the default CPU.
  85
  86 Arguments:
  87
  88 - "index": the CPU's index (json-int)
  89
  90 Example:
  91
  92 -> { "execute": "cpu", "arguments": { "index": 0 } }
  93 <- { "return": {} }
  94
  95 Note: CPUs' indexes are obtained with the 'query-cpus' command.
  96
  97 xen-load-devices-state
  98 ----------------------
  99
 100 Load the state of all devices from file. The RAM and the block devices
 101 of the VM are not loaded by this command.
 102
 103 Arguments:
 104
 105 - "filename": the file to load the state of the devices from as binary
 106 data. See xen-save-devices-state.txt for a description of the binary
 107 format.
 108
 109 Example:
 110
 111 -> { "execute": "xen-load-devices-state",
 112      "arguments": { "filename": "/tmp/resume" } }
 113 <- { "return": {} }
 114
 115 migrate-set-cache-size
 116 ----------------------
 117
 118 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 119 down to the nearest power of 2
 120
 121 Arguments:
 122
 123 - "value": cache size in bytes (json-int)
 124
 125 Example:
 126
 127 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 128 <- { "return": {} }
 129
 130 x-colo-lost-heartbeat
 131 --------------------
 132
 133 Tell COLO that heartbeat is lost, a failover or takeover is needed.
 134
 135 Example:
 136
 137 -> { "execute": "x-colo-lost-heartbeat" }
 138 <- { "return": {} }
 139
 140 query-dump
 141 ----------
 142
 143 Query background dump status.
 144
 145 Arguments: None.
 146
 147 Example:
 148
 149 -> { "execute": "query-dump" }
 150 <- { "return": { "status": "active", "completed": 1024000,
 151                  "total": 2048000 } }
 152
 153 blockdev-mirror
 154 ------------
 155
 156 Start mirroring a block device's writes to another block device. target
 157 specifies the target of mirror operation.
 158
 159 Arguments:
 160
 161 - "job-id": Identifier for the newly-created block job. If omitted,
 162             the device name will be used. (json-string, optional)
 163 - "device": The device name or node-name of a root node whose writes should be
 164             mirrored (json-string)
 165 - "target": device name to mirror to (json-string)
 166 - "replaces": the block driver node name to replace when finished
 167               (json-string, optional)
 168 - "speed": maximum speed of the streaming job, in bytes per second
 169   (json-int)
 170 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 171 - "buf_size": maximum amount of data in flight from source to target, in bytes
 172   (json-int, default 10M)
 173 - "sync": what parts of the disk image should be copied to the destination;
 174   possibilities include "full" for all the disk, "top" for only the sectors
 175   allocated in the topmost image, or "none" to only replicate new I/O
 176   (MirrorSyncMode).
 177 - "on-source-error": the action to take on an error on the source
 178   (BlockdevOnError, default 'report')
 179 - "on-target-error": the action to take on an error on the target
 180   (BlockdevOnError, default 'report')
 181
 182 The default value of the granularity is the image cluster size clamped
 183 between 4096 and 65536, if the image format defines one.  If the format
 184 does not define a cluster size, the default value of the granularity
 185 is 65536.
 186
 187 Example:
 188
 189 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
 190                                                   "target": "target0",
 191                                                   "sync": "full" } }
 192 <- { "return": {} }
 193
 194 qmp_capabilities
 195 ----------------
 196
 197 Enable QMP capabilities.
 198
 199 Arguments: None.
 200
 201 Example:
 202
 203 -> { "execute": "qmp_capabilities" }
 204 <- { "return": {} }
 205
 206 Note: This command must be issued before issuing any other command.
 207
 208 3. Query Commands
 209 =================
 210
 211
 212 query-qmp-schema
 213 ----------------
 214
 215 Return the QMP wire schema.  The returned value is a json-array of
 216 named schema entities.  Entities are commands, events and various
 217 types.  See docs/qapi-code-gen.txt for information on their structure
 218 and intended use.
 219
 220 x-blockdev-change
 221 -----------------
 222
 223 Dynamically reconfigure the block driver state graph. It can be used
 224 to add, remove, insert or replace a graph node. Currently only the
 225 Quorum driver implements this feature to add or remove its child. This
 226 is useful to fix a broken quorum child.
 227
 228 If @node is specified, it will be inserted under @parent. @child
 229 may not be specified in this case. If both @parent and @child are
 230 specified but @node is not, @child will be detached from @parent.
 231
 232 Arguments:
 233 - "parent": the id or name of the parent node (json-string)
 234 - "child": the name of a child under the given parent node (json-string, optional)
 235 - "node": the name of the node that will be added (json-string, optional)
 236
 237 Note: this command is experimental, and not a stable API. It doesn't
 238 support all kinds of operations, all kinds of children, nor all block
 239 drivers.
 240
 241 Warning: The data in a new quorum child MUST be consistent with that of
 242 the rest of the array.
 243
 244 Example:
 245
 246 Add a new node to a quorum
 247 -> { "execute": "blockdev-add",
 248      "arguments": { "driver": "raw",
 249                     "node-name": "new_node",
 250                     "file": { "driver": "file",
 251                               "filename": "test.raw" } } }
 252 <- { "return": {} }
 253 -> { "execute": "x-blockdev-change",
 254      "arguments": { "parent": "disk1",
 255                     "node": "new_node" } }
 256 <- { "return": {} }
 257
 258 Delete a quorum's node
 259 -> { "execute": "x-blockdev-change",
 260      "arguments": { "parent": "disk1",
 261                     "child": "children.1" } }
 262 <- { "return": {} }
 263
 264 trace-event-get-state
 265 ---------------------
 266
 267 Query the state of events.
 268
 269 Arguments:
 270
 271 - "name": Event name pattern (json-string).
 272 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
 273
 274 An event is returned if:
 275 - its name matches the "name" pattern, and
 276 - if "vcpu" is given, the event has the "vcpu" property.
 277
 278 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
 279 returning their state on the specified vCPU. Special case: if "name" is an exact
 280 match, "vcpu" is given and the event does not have the "vcpu" property, an error
 281 is returned.
 282
 283 Example:
 284
 285 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
 286 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
 287
 288 trace-event-set-state
 289 ---------------------
 290
 291 Set the state of events.
 292
 293 Arguments:
 294
 295 - "name": Event name pattern (json-string).
 296 - "enable": Whether to enable or disable the event (json-bool).
 297 - "ignore-unavailable": Whether to ignore errors for events that cannot be
 298   changed (json-bool, optional).
 299 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
 300
 301 An event's state is modified if:
 302 - its name matches the "name" pattern, and
 303 - if "vcpu" is given, the event has the "vcpu" property.
 304
 305 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
 306 setting their state on the specified vCPU. Special case: if "name" is an exact
 307 match, "vcpu" is given and the event does not have the "vcpu" property, an error
 308 is returned.
 309
 310 Example:
 311
 312 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
 313 <- { "return": {} }
 314
 315 query-gic-capabilities
 316 ---------------
 317
 318 Return a list of GICCapability objects, describing supported GIC
 319 (Generic Interrupt Controller) versions.
 320
 321 Arguments: None
 322
 323 Example:
 324
 325 -> { "execute": "query-gic-capabilities" }
 326 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
 327                 { "version": 3, "emulated": false, "kernel": true } ] }
 328
 329 Show existing/possible CPUs
 330 ---------------------------
 331
 332 Arguments: None.
 333
 334 Example for pseries machine type started with
 335 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
 336
 337 -> { "execute": "query-hotpluggable-cpus" }
 338 <- {"return": [
 339      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
 340        "vcpus-count": 1 },
 341      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
 342        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
 343    ]}'
 344
 345 Example for pc machine type started with
 346 -smp 1,maxcpus=2:
 347     -> { "execute": "query-hotpluggable-cpus" }
 348     <- {"return": [
 349          {
 350             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
 351             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
 352          },
 353          {
 354             "qom-path": "/machine/unattached/device[0]",
 355             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
 356             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
 357          }
 358        ]}