blob: 9e05365ccf09aa533dc187a17f68ed76281c39f4 [file] [log] [blame]
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001HXCOMM QMP dispatch table and documentation
Alberto Garcia3599d462015-02-26 16:35:07 +02002HXCOMM Text between SQMP and EQMP is copied to the QMP documentation file and
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003HXCOMM does not show up in the other formats.
4
5SQMP
6 QMP Supported Commands
7 ----------------------
8
9This document describes all commands currently supported by QMP.
10
11Most of the time their usage is exactly the same as in the user Monitor, this
12means that any other document which also describe commands (the manpage,
13QEMU's manual, etc) can and should be consulted.
14
15QMP has two types of commands: regular and query commands. Regular commands
16usually change the Virtual Machine's state someway, while query commands just
17return information. The sections below are divided accordingly.
18
19It's important to observe that all communication examples are formatted in
20a reader-friendly way, so that they're easier to understand. However, in real
21protocol usage, they're emitted as a single line.
22
23Also, the following notation is used to denote data flow:
24
25-> data issued by the Client
26<- Server data response
27
28Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
29information on the Server command and response formats.
30
31NOTE: This document is temporary and will be replaced soon.
32
331. Stability Considerations
34===========================
35
36The current QMP command set (described in this file) may be useful for a
37number of use cases, however it's limited and several commands have bad
38defined semantics, specially with regard to command completion.
39
40These problems are going to be solved incrementally in the next QEMU releases
41and we're going to establish a deprecation policy for badly defined commands.
42
43If you're planning to adopt QMP, please observe the following:
44
Zhi Yong Wuc20cdf82011-07-27 14:32:56 +080045 1. The deprecation policy will take effect and be documented soon, please
Luiz Capitulino82a56f02010-09-13 12:26:00 -030046 check the documentation of each used command as soon as a new release of
47 QEMU is available
48
49 2. DO NOT rely on anything which is not explicit documented
50
51 3. Errors, in special, are not documented. Applications should NOT check
52 for specific errors classes or data (it's strongly recommended to only
53 check for the "error" key)
54
552. Regular Commands
56===================
57
58Server's responses in the examples below are always a success response, please
59refer to the QMP specification for more details on error responses.
60
61EQMP
62
63 {
64 .name = "quit",
65 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +020066 .mhandler.cmd_new = qmp_marshal_quit,
Luiz Capitulino82a56f02010-09-13 12:26:00 -030067 },
68
69SQMP
70quit
71----
72
73Quit the emulator.
74
75Arguments: None.
76
77Example:
78
79-> { "execute": "quit" }
80<- { "return": {} }
81
82EQMP
83
84 {
85 .name = "eject",
86 .args_type = "force:-f,device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +020087 .mhandler.cmd_new = qmp_marshal_eject,
Luiz Capitulino82a56f02010-09-13 12:26:00 -030088 },
89
90SQMP
91eject
92-----
93
94Eject a removable medium.
95
96Arguments:
97
98- force: force ejection (json-bool, optional)
99- device: device name (json-string)
100
101Example:
102
103-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
104<- { "return": {} }
105
106Note: The "force" argument defaults to false.
107
108EQMP
109
110 {
111 .name = "change",
112 .args_type = "device:B,target:F,arg:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200113 .mhandler.cmd_new = qmp_marshal_change,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300114 },
115
116SQMP
117change
118------
119
120Change a removable medium or VNC configuration.
121
122Arguments:
123
124- "device": device name (json-string)
125- "target": filename or item (json-string)
126- "arg": additional argument (json-string, optional)
127
128Examples:
129
1301. Change a removable medium
131
132-> { "execute": "change",
133 "arguments": { "device": "ide1-cd0",
134 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
135<- { "return": {} }
136
1372. Change VNC password
138
139-> { "execute": "change",
140 "arguments": { "device": "vnc", "target": "password",
141 "arg": "foobar1" } }
142<- { "return": {} }
143
144EQMP
145
146 {
147 .name = "screendump",
148 .args_type = "filename:F",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200149 .mhandler.cmd_new = qmp_marshal_screendump,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300150 },
151
152SQMP
153screendump
154----------
155
156Save screen into PPM image.
157
158Arguments:
159
160- "filename": file path (json-string)
161
162Example:
163
164-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
165<- { "return": {} }
166
167EQMP
168
169 {
170 .name = "stop",
171 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200172 .mhandler.cmd_new = qmp_marshal_stop,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300173 },
174
175SQMP
176stop
177----
178
179Stop the emulator.
180
181Arguments: None.
182
183Example:
184
185-> { "execute": "stop" }
186<- { "return": {} }
187
188EQMP
189
190 {
191 .name = "cont",
192 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200193 .mhandler.cmd_new = qmp_marshal_cont,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300194 },
195
196SQMP
197cont
198----
199
200Resume emulation.
201
202Arguments: None.
203
204Example:
205
206-> { "execute": "cont" }
207<- { "return": {} }
208
209EQMP
210
211 {
Gerd Hoffmann9b9df252012-02-23 13:45:21 +0100212 .name = "system_wakeup",
213 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200214 .mhandler.cmd_new = qmp_marshal_system_wakeup,
Gerd Hoffmann9b9df252012-02-23 13:45:21 +0100215 },
216
217SQMP
218system_wakeup
219-------------
220
221Wakeup guest from suspend.
222
223Arguments: None.
224
225Example:
226
227-> { "execute": "system_wakeup" }
228<- { "return": {} }
229
230EQMP
231
232 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300233 .name = "system_reset",
234 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200235 .mhandler.cmd_new = qmp_marshal_system_reset,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300236 },
237
238SQMP
239system_reset
240------------
241
242Reset the system.
243
244Arguments: None.
245
246Example:
247
248-> { "execute": "system_reset" }
249<- { "return": {} }
250
251EQMP
252
253 {
254 .name = "system_powerdown",
255 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200256 .mhandler.cmd_new = qmp_marshal_system_powerdown,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300257 },
258
259SQMP
260system_powerdown
261----------------
262
263Send system power down event.
264
265Arguments: None.
266
267Example:
268
269-> { "execute": "system_powerdown" }
270<- { "return": {} }
271
272EQMP
273
274 {
275 .name = "device_add",
276 .args_type = "device:O",
277 .params = "driver[,prop=value][,...]",
278 .help = "add device, like -device on the command line",
Markus Armbruster485febc2015-03-13 17:25:50 +0100279 .mhandler.cmd_new = qmp_device_add,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300280 },
281
282SQMP
283device_add
284----------
285
286Add a device.
287
288Arguments:
289
290- "driver": the name of the new device's driver (json-string)
291- "bus": the device's parent bus (device tree path, json-string, optional)
292- "id": the device's ID, must be unique (json-string)
293- device properties
294
295Example:
296
297-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
298<- { "return": {} }
299
300Notes:
301
302(1) For detailed information about this command, please refer to the
303 'docs/qdev-device-use.txt' file.
304
305(2) It's possible to list device properties by running QEMU with the
306 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
307
308EQMP
309
310 {
311 .name = "device_del",
312 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200313 .mhandler.cmd_new = qmp_marshal_device_del,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300314 },
315
316SQMP
317device_del
318----------
319
320Remove a device.
321
322Arguments:
323
Daniel P. Berrange6287d822015-09-11 13:33:56 +0100324- "id": the device's ID or QOM path (json-string)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300325
326Example:
327
328-> { "execute": "device_del", "arguments": { "id": "net1" } }
329<- { "return": {} }
330
Daniel P. Berrange6287d822015-09-11 13:33:56 +0100331Example:
332
333-> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
334<- { "return": {} }
335
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300336EQMP
337
338 {
Amos Konge4c8f002012-08-31 10:56:26 +0800339 .name = "send-key",
Paolo Bonzini43d0a2c2015-04-15 13:30:04 +0200340 .args_type = "keys:q,hold-time:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200341 .mhandler.cmd_new = qmp_marshal_send_key,
Amos Konge4c8f002012-08-31 10:56:26 +0800342 },
343
344SQMP
345send-key
346----------
347
348Send keys to VM.
349
350Arguments:
351
352keys array:
Amos Kongf9b1d9b2013-07-16 19:52:14 +0800353 - "key": key sequence (a json-array of key union values,
354 union can be number or qcode enum)
Amos Konge4c8f002012-08-31 10:56:26 +0800355
356- hold-time: time to delay key up events, milliseconds. Defaults to 100
357 (json-int, optional)
358
359Example:
360
361-> { "execute": "send-key",
Amos Kongf9b1d9b2013-07-16 19:52:14 +0800362 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
363 { "type": "qcode", "data": "alt" },
364 { "type": "qcode", "data": "delete" } ] } }
Amos Konge4c8f002012-08-31 10:56:26 +0800365<- { "return": {} }
366
367EQMP
368
369 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300370 .name = "cpu",
371 .args_type = "index:i",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200372 .mhandler.cmd_new = qmp_marshal_cpu,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300373 },
374
375SQMP
376cpu
377---
378
379Set the default CPU.
380
381Arguments:
382
383- "index": the CPU's index (json-int)
384
385Example:
386
387-> { "execute": "cpu", "arguments": { "index": 0 } }
388<- { "return": {} }
389
390Note: CPUs' indexes are obtained with the 'query-cpus' command.
391
392EQMP
393
394 {
Igor Mammedov69ca3ea2013-04-30 15:41:25 +0200395 .name = "cpu-add",
396 .args_type = "id:i",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200397 .mhandler.cmd_new = qmp_marshal_cpu_add,
Igor Mammedov69ca3ea2013-04-30 15:41:25 +0200398 },
399
400SQMP
401cpu-add
402-------
403
404Adds virtual cpu
405
406Arguments:
407
408- "id": cpu id (json-int)
409
410Example:
411
412-> { "execute": "cpu-add", "arguments": { "id": 2 } }
413<- { "return": {} }
414
415EQMP
416
417 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300418 .name = "memsave",
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -0200419 .args_type = "val:l,size:i,filename:s,cpu:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200420 .mhandler.cmd_new = qmp_marshal_memsave,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300421 },
422
423SQMP
424memsave
425-------
426
427Save to disk virtual memory dump starting at 'val' of size 'size'.
428
429Arguments:
430
431- "val": the starting address (json-int)
432- "size": the memory size, in bytes (json-int)
433- "filename": file path (json-string)
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -0200434- "cpu": virtual CPU index (json-int, optional)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300435
436Example:
437
438-> { "execute": "memsave",
439 "arguments": { "val": 10,
440 "size": 100,
441 "filename": "/tmp/virtual-mem-dump" } }
442<- { "return": {} }
443
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300444EQMP
445
446 {
447 .name = "pmemsave",
448 .args_type = "val:l,size:i,filename:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200449 .mhandler.cmd_new = qmp_marshal_pmemsave,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300450 },
451
452SQMP
453pmemsave
454--------
455
456Save to disk physical memory dump starting at 'val' of size 'size'.
457
458Arguments:
459
460- "val": the starting address (json-int)
461- "size": the memory size, in bytes (json-int)
462- "filename": file path (json-string)
463
464Example:
465
466-> { "execute": "pmemsave",
467 "arguments": { "val": 10,
468 "size": 100,
469 "filename": "/tmp/physical-mem-dump" } }
470<- { "return": {} }
471
472EQMP
473
474 {
Lai Jiangshana4046662011-03-07 17:05:15 +0800475 .name = "inject-nmi",
476 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200477 .mhandler.cmd_new = qmp_marshal_inject_nmi,
Lai Jiangshana4046662011-03-07 17:05:15 +0800478 },
479
480SQMP
481inject-nmi
482----------
483
Alexey Kardashevskiy9cb805f2014-08-20 22:16:33 +1000484Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
Lai Jiangshana4046662011-03-07 17:05:15 +0800485
486Arguments: None.
487
488Example:
489
490-> { "execute": "inject-nmi" }
491<- { "return": {} }
492
Luiz Capitulinode253f12012-07-27 16:18:16 -0300493Note: inject-nmi fails when the guest doesn't support injecting.
Lai Jiangshana4046662011-03-07 17:05:15 +0800494
495EQMP
496
497 {
Markus Armbruster3949e592013-02-06 21:27:24 +0100498 .name = "ringbuf-write",
Markus Armbruster82e59a62013-02-06 21:27:14 +0100499 .args_type = "device:s,data:s,format:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200500 .mhandler.cmd_new = qmp_marshal_ringbuf_write,
Lei Li1f590cf2013-01-25 00:03:20 +0800501 },
502
503SQMP
Markus Armbruster3949e592013-02-06 21:27:24 +0100504ringbuf-write
Lei Li1f590cf2013-01-25 00:03:20 +0800505-------------
506
Markus Armbruster3949e592013-02-06 21:27:24 +0100507Write to a ring buffer character device.
Lei Li1f590cf2013-01-25 00:03:20 +0800508
509Arguments:
510
Markus Armbruster3949e592013-02-06 21:27:24 +0100511- "device": ring buffer character device name (json-string)
512- "data": data to write (json-string)
513- "format": data format (json-string, optional)
514 - Possible values: "utf8" (default), "base64"
Lei Li1f590cf2013-01-25 00:03:20 +0800515
516Example:
517
Markus Armbruster3949e592013-02-06 21:27:24 +0100518-> { "execute": "ringbuf-write",
519 "arguments": { "device": "foo",
Lei Li1f590cf2013-01-25 00:03:20 +0800520 "data": "abcdefgh",
521 "format": "utf8" } }
522<- { "return": {} }
523
524EQMP
525
526 {
Markus Armbruster3949e592013-02-06 21:27:24 +0100527 .name = "ringbuf-read",
Lei Li49b6d722013-01-25 00:03:21 +0800528 .args_type = "device:s,size:i,format:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200529 .mhandler.cmd_new = qmp_marshal_ringbuf_read,
Lei Li49b6d722013-01-25 00:03:21 +0800530 },
531
532SQMP
Markus Armbruster3949e592013-02-06 21:27:24 +0100533ringbuf-read
Lei Li49b6d722013-01-25 00:03:21 +0800534-------------
535
Markus Armbruster3949e592013-02-06 21:27:24 +0100536Read from a ring buffer character device.
Lei Li49b6d722013-01-25 00:03:21 +0800537
538Arguments:
539
Markus Armbruster3949e592013-02-06 21:27:24 +0100540- "device": ring buffer character device name (json-string)
541- "size": how many bytes to read at most (json-int)
542 - Number of data bytes, not number of characters in encoded data
543- "format": data format (json-string, optional)
544 - Possible values: "utf8" (default), "base64"
545 - Naturally, format "utf8" works only when the ring buffer
546 contains valid UTF-8 text. Invalid UTF-8 sequences get
547 replaced. Bug: replacement doesn't work. Bug: can screw
548 up on encountering NUL characters, after the ring buffer
549 lost data, and when reading stops because the size limit
550 is reached.
Lei Li49b6d722013-01-25 00:03:21 +0800551
552Example:
553
Markus Armbruster3949e592013-02-06 21:27:24 +0100554-> { "execute": "ringbuf-read",
555 "arguments": { "device": "foo",
Lei Li49b6d722013-01-25 00:03:21 +0800556 "size": 1000,
557 "format": "utf8" } }
Markus Armbruster3ab651f2013-02-06 21:27:15 +0100558<- {"return": "abcdefgh"}
Lei Li49b6d722013-01-25 00:03:21 +0800559
560EQMP
561
562 {
Stefano Stabellinia7ae8352012-01-25 12:24:51 +0000563 .name = "xen-save-devices-state",
564 .args_type = "filename:F",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200565 .mhandler.cmd_new = qmp_marshal_xen_save_devices_state,
Stefano Stabellinia7ae8352012-01-25 12:24:51 +0000566 },
567
568SQMP
569xen-save-devices-state
570-------
571
572Save the state of all devices to file. The RAM and the block devices
573of the VM are not saved by this command.
574
575Arguments:
576
577- "filename": the file to save the state of the devices to as binary
578data. See xen-save-devices-state.txt for a description of the binary
579format.
580
581Example:
582
583-> { "execute": "xen-save-devices-state",
584 "arguments": { "filename": "/tmp/save" } }
585<- { "return": {} }
586
587EQMP
588
589 {
Anthony PERARD39f42432012-10-03 13:48:19 +0000590 .name = "xen-set-global-dirty-log",
591 .args_type = "enable:b",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200592 .mhandler.cmd_new = qmp_marshal_xen_set_global_dirty_log,
Anthony PERARD39f42432012-10-03 13:48:19 +0000593 },
594
595SQMP
596xen-set-global-dirty-log
597-------
598
599Enable or disable the global dirty log mode.
600
601Arguments:
602
603- "enable": Enable it or disable it.
604
605Example:
606
607-> { "execute": "xen-set-global-dirty-log",
608 "arguments": { "enable": true } }
609<- { "return": {} }
610
611EQMP
612
613 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300614 .name = "migrate",
615 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200616 .mhandler.cmd_new = qmp_marshal_migrate,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300617 },
618
619SQMP
620migrate
621-------
622
623Migrate to URI.
624
625Arguments:
626
627- "blk": block migration, full disk copy (json-bool, optional)
628- "inc": incremental disk copy (json-bool, optional)
629- "uri": Destination URI (json-string)
630
631Example:
632
633-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
634<- { "return": {} }
635
636Notes:
637
638(1) The 'query-migrate' command should be used to check migration's progress
639 and final result (this information is provided by the 'status' member)
640(2) All boolean arguments default to false
641(3) The user Monitor's "detach" argument is invalid in QMP and should not
642 be used
643
644EQMP
645
646 {
647 .name = "migrate_cancel",
648 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200649 .mhandler.cmd_new = qmp_marshal_migrate_cancel,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300650 },
651
652SQMP
653migrate_cancel
654--------------
655
656Cancel the current migration.
657
658Arguments: None.
659
660Example:
661
662-> { "execute": "migrate_cancel" }
663<- { "return": {} }
664
665EQMP
Dr. David Alan Gilbertbf1ae1f2015-02-19 11:40:28 +0000666
667 {
668 .name = "migrate-incoming",
669 .args_type = "uri:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200670 .mhandler.cmd_new = qmp_marshal_migrate_incoming,
Dr. David Alan Gilbertbf1ae1f2015-02-19 11:40:28 +0000671 },
672
673SQMP
674migrate-incoming
675----------------
676
677Continue an incoming migration
678
679Arguments:
680
681- "uri": Source/listening URI (json-string)
682
683Example:
684
685-> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
686<- { "return": {} }
687
688Notes:
689
690(1) QEMU must be started with -incoming defer to allow migrate-incoming to
691 be used
Dr. David Alan Gilbert4aab6282015-06-03 19:43:56 +0100692(2) The uri format is the same as for -incoming
Dr. David Alan Gilbertbf1ae1f2015-02-19 11:40:28 +0000693
694EQMP
695 {
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300696 .name = "migrate-set-cache-size",
697 .args_type = "value:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200698 .mhandler.cmd_new = qmp_marshal_migrate_set_cache_size,
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300699 },
700
701SQMP
702migrate-set-cache-size
Juan Quintela817c6042013-02-11 15:11:10 +0100703----------------------
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300704
705Set cache size to be used by XBZRLE migration, the cache size will be rounded
706down to the nearest power of 2
707
708Arguments:
709
710- "value": cache size in bytes (json-int)
711
712Example:
713
714-> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
715<- { "return": {} }
716
717EQMP
718 {
Dr. David Alan Gilbert4886a1b2015-11-05 18:10:56 +0000719 .name = "migrate-start-postcopy",
720 .args_type = "",
721 .mhandler.cmd_new = qmp_marshal_migrate_start_postcopy,
722 },
723
724SQMP
725migrate-start-postcopy
726----------------------
727
728Switch an in-progress migration to postcopy mode. Ignored after the end of
729migration (or once already in postcopy).
730
731Example:
732-> { "execute": "migrate-start-postcopy" }
733<- { "return": {} }
734
735EQMP
736
737 {
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300738 .name = "query-migrate-cache-size",
739 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200740 .mhandler.cmd_new = qmp_marshal_query_migrate_cache_size,
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300741 },
742
743SQMP
744query-migrate-cache-size
Juan Quintela817c6042013-02-11 15:11:10 +0100745------------------------
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +0300746
747Show cache size to be used by XBZRLE migration
748
749returns a json-object with the following information:
750- "size" : json-int
751
752Example:
753
754-> { "execute": "query-migrate-cache-size" }
755<- { "return": 67108864 }
756
757EQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300758
759 {
760 .name = "migrate_set_speed",
Wen Congyang3a019b62010-11-25 09:06:05 +0800761 .args_type = "value:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200762 .mhandler.cmd_new = qmp_marshal_migrate_set_speed,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300763 },
764
765SQMP
766migrate_set_speed
767-----------------
768
769Set maximum speed for migrations.
770
771Arguments:
772
Luiz Capitulino5569fd72010-12-15 17:56:18 -0200773- "value": maximum speed, in bytes per second (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300774
775Example:
776
777-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
778<- { "return": {} }
779
780EQMP
781
782 {
783 .name = "migrate_set_downtime",
784 .args_type = "value:T",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200785 .mhandler.cmd_new = qmp_marshal_migrate_set_downtime,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300786 },
787
788SQMP
789migrate_set_downtime
790--------------------
791
792Set maximum tolerated downtime (in seconds) for migrations.
793
794Arguments:
795
796- "value": maximum downtime (json-number)
797
798Example:
799
800-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
801<- { "return": {} }
802
803EQMP
804
805 {
Jes Sorensenff73edf2011-03-09 14:31:06 +0100806 .name = "client_migrate_info",
807 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
808 .params = "protocol hostname port tls-port cert-subject",
Markus Armbruster13cadef2015-03-05 19:16:58 +0100809 .help = "set migration information for remote display",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200810 .mhandler.cmd_new = qmp_marshal_client_migrate_info,
Jes Sorensenff73edf2011-03-09 14:31:06 +0100811 },
812
813SQMP
814client_migrate_info
Markus Armbruster13cadef2015-03-05 19:16:58 +0100815-------------------
Jes Sorensenff73edf2011-03-09 14:31:06 +0100816
Markus Armbruster13cadef2015-03-05 19:16:58 +0100817Set migration information for remote display. This makes the server
818ask the client to automatically reconnect using the new parameters
819once migration finished successfully. Only implemented for SPICE.
Jes Sorensenff73edf2011-03-09 14:31:06 +0100820
821Arguments:
822
Markus Armbruster13cadef2015-03-05 19:16:58 +0100823- "protocol": must be "spice" (json-string)
Jes Sorensenff73edf2011-03-09 14:31:06 +0100824- "hostname": migration target hostname (json-string)
Markus Armbruster13cadef2015-03-05 19:16:58 +0100825- "port": spice tcp port for plaintext channels (json-int, optional)
Jes Sorensenff73edf2011-03-09 14:31:06 +0100826- "tls-port": spice tcp port for tls-secured channels (json-int, optional)
827- "cert-subject": server certificate subject (json-string, optional)
828
829Example:
830
831-> { "execute": "client_migrate_info",
832 "arguments": { "protocol": "spice",
833 "hostname": "virt42.lab.kraxel.org",
834 "port": 1234 } }
835<- { "return": {} }
836
837EQMP
838
839 {
Wen Congyang783e9b42012-05-07 12:10:47 +0800840 .name = "dump-guest-memory",
Peter Xu228de9c2016-02-18 13:16:47 +0800841 .args_type = "paging:b,protocol:s,detach:b?,begin:i?,end:i?,format:s?",
842 .params = "-p protocol [-d] [begin] [length] [format]",
Wen Congyang783e9b42012-05-07 12:10:47 +0800843 .help = "dump guest memory to file",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200844 .mhandler.cmd_new = qmp_marshal_dump_guest_memory,
Wen Congyang783e9b42012-05-07 12:10:47 +0800845 },
846
847SQMP
848dump
849
850
851Dump guest memory to file. The file can be processed with crash or gdb.
852
853Arguments:
854
855- "paging": do paging to get guest's memory mapping (json-bool)
856- "protocol": destination file(started with "file:") or destination file
857 descriptor (started with "fd:") (json-string)
Peter Xu228de9c2016-02-18 13:16:47 +0800858- "detach": if specified, command will return immediately, without waiting
Peter Xu39ba2ea2016-02-18 13:16:54 +0800859 for the dump to finish. The user can track progress using
860 "query-dump". (json-bool)
Wen Congyang783e9b42012-05-07 12:10:47 +0800861- "begin": the starting physical address. It's optional, and should be specified
862 with length together (json-int)
863- "length": the memory size, in bytes. It's optional, and should be specified
864 with begin together (json-int)
qiaonuohanb53ccc32014-02-18 14:11:36 +0800865- "format": the format of guest memory dump. It's optional, and can be
866 elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
867 conflict with paging and filter, ie. begin and length (json-string)
Wen Congyang783e9b42012-05-07 12:10:47 +0800868
869Example:
870
871-> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
872<- { "return": {} }
873
874Notes:
875
876(1) All boolean arguments default to false
877
878EQMP
879
880 {
qiaonuohan7d6dc7f2014-02-18 14:11:38 +0800881 .name = "query-dump-guest-memory-capability",
882 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200883 .mhandler.cmd_new = qmp_marshal_query_dump_guest_memory_capability,
qiaonuohan7d6dc7f2014-02-18 14:11:38 +0800884 },
885
886SQMP
887query-dump-guest-memory-capability
888----------
889
890Show available formats for 'dump-guest-memory'
891
892Example:
893
894-> { "execute": "query-dump-guest-memory-capability" }
895<- { "return": { "formats":
896 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
897
898EQMP
899
Peter Xu39ba2ea2016-02-18 13:16:54 +0800900 {
901 .name = "query-dump",
902 .args_type = "",
903 .params = "",
904 .help = "query background dump status",
905 .mhandler.cmd_new = qmp_marshal_query_dump,
906 },
907
908SQMP
909query-dump
910----------
911
912Query background dump status.
913
914Arguments: None.
915
916Example:
917
918-> { "execute": "query-dump" }
919<- { "return": { "status": "active", "completed": 1024000,
920 "total": 2048000 } }
921
922EQMP
923
Jason J. Herne7ee0c3e2015-06-26 14:03:16 -0400924#if defined TARGET_S390X
925 {
926 .name = "dump-skeys",
927 .args_type = "filename:F",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200928 .mhandler.cmd_new = qmp_marshal_dump_skeys,
Jason J. Herne7ee0c3e2015-06-26 14:03:16 -0400929 },
930#endif
931
932SQMP
933dump-skeys
934----------
935
936Save guest storage keys to file.
937
938Arguments:
939
940- "filename": file path (json-string)
941
942Example:
943
944-> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
945<- { "return": {} }
946
947EQMP
948
qiaonuohan7d6dc7f2014-02-18 14:11:38 +0800949 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300950 .name = "netdev_add",
951 .args_type = "netdev:O",
Luiz Capitulino928059a2012-04-18 17:34:15 -0300952 .mhandler.cmd_new = qmp_netdev_add,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300953 },
954
955SQMP
956netdev_add
957----------
958
959Add host network device.
960
961Arguments:
962
963- "type": the device type, "tap", "user", ... (json-string)
964- "id": the device's ID, must be unique (json-string)
965- device options
966
967Example:
968
Markus Armbrusterb8a98322015-09-16 13:06:26 +0200969-> { "execute": "netdev_add",
970 "arguments": { "type": "user", "id": "netdev1",
971 "dnssearch": "example.org" } }
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300972<- { "return": {} }
973
Markus Armbrusteraf347aa2013-02-22 18:31:51 +0100974Note: The supported device options are the same ones supported by the '-netdev'
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300975 command-line argument, which are listed in the '-help' output or QEMU's
976 manual
977
978EQMP
979
980 {
981 .name = "netdev_del",
982 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +0200983 .mhandler.cmd_new = qmp_marshal_netdev_del,
Luiz Capitulino82a56f02010-09-13 12:26:00 -0300984 },
985
986SQMP
987netdev_del
988----------
989
990Remove host network device.
991
992Arguments:
993
994- "id": the device's ID, must be unique (json-string)
995
996Example:
997
998-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
999<- { "return": {} }
1000
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001001
1002EQMP
1003
1004 {
Paolo Bonzinicff8b2c2013-12-20 23:21:10 +01001005 .name = "object-add",
1006 .args_type = "qom-type:s,id:s,props:q?",
Markus Armbruster6eb39372015-09-16 13:06:25 +02001007 .mhandler.cmd_new = qmp_marshal_object_add,
Paolo Bonzinicff8b2c2013-12-20 23:21:10 +01001008 },
1009
1010SQMP
1011object-add
1012----------
1013
1014Create QOM object.
1015
1016Arguments:
1017
1018- "qom-type": the object's QOM type, i.e. the class name (json-string)
1019- "id": the object's ID, must be unique (json-string)
1020- "props": a dictionary of object property values (optional, json-dict)
1021
1022Example:
1023
1024-> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
1025 "props": { "filename": "/dev/hwrng" } } }
1026<- { "return": {} }
1027
1028EQMP
1029
1030 {
Paolo Bonziniab2d0532013-12-20 23:21:09 +01001031 .name = "object-del",
1032 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001033 .mhandler.cmd_new = qmp_marshal_object_del,
Paolo Bonziniab2d0532013-12-20 23:21:09 +01001034 },
1035
1036SQMP
1037object-del
1038----------
1039
1040Remove QOM object.
1041
1042Arguments:
1043
1044- "id": the object's ID (json-string)
1045
1046Example:
1047
1048-> { "execute": "object-del", "arguments": { "id": "rng1" } }
1049<- { "return": {} }
1050
1051
1052EQMP
1053
1054
1055 {
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001056 .name = "block_resize",
Benoît Canet3b1dbd12014-01-23 21:31:37 +01001057 .args_type = "device:s?,node-name:s?,size:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001058 .mhandler.cmd_new = qmp_marshal_block_resize,
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001059 },
1060
1061SQMP
1062block_resize
1063------------
1064
1065Resize a block image while a guest is running.
1066
1067Arguments:
1068
1069- "device": the device's ID, must be unique (json-string)
Benoît Canet3b1dbd12014-01-23 21:31:37 +01001070- "node-name": the node name in the block driver state graph (json-string)
Christoph Hellwig6d4a2b32011-01-24 13:32:33 +01001071- "size": new size
1072
1073Example:
1074
1075-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
1076<- { "return": {} }
1077
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001078EQMP
1079
1080 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01001081 .name = "block-stream",
Jeff Cody13d8cc52014-06-25 15:40:11 -04001082 .args_type = "device:B,base:s?,speed:o?,backing-file:s?,on-error:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001083 .mhandler.cmd_new = qmp_marshal_block_stream,
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00001084 },
1085
Stefan Hajnocziec683d62015-04-15 11:43:42 +01001086SQMP
1087block-stream
1088------------
1089
1090Copy data from a backing file into a block device.
1091
1092Arguments:
1093
1094- "device": The device's ID, must be unique (json-string)
1095- "base": The file name of the backing image above which copying starts
1096 (json-string, optional)
1097- "backing-file": The backing file string to write into the active layer. This
1098 filename is not validated.
1099
1100 If a pathname string is such that it cannot be resolved by
1101 QEMU, that means that subsequent QMP or HMP commands must use
1102 node-names for the image in question, as filename lookup
1103 methods will fail.
1104
1105 If not specified, QEMU will automatically determine the
1106 backing file string to use, or error out if there is no
1107 obvious choice. Care should be taken when specifying the
1108 string, to specify a valid filename or protocol.
1109 (json-string, optional) (Since 2.1)
1110- "speed": the maximum speed, in bytes per second (json-int, optional)
1111- "on-error": the action to take on an error (default 'report'). 'stop' and
1112 'enospc' can only be used if the block device supports io-status.
1113 (json-string, optional) (Since 2.1)
1114
1115Example:
1116
1117-> { "execute": "block-stream", "arguments": { "device": "virtio0",
1118 "base": "/tmp/master.qcow2" } }
1119<- { "return": {} }
1120
1121EQMP
1122
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00001123 {
Jeff Codyed61fc12012-09-27 13:29:16 -04001124 .name = "block-commit",
Jeff Cody54e26902014-06-25 15:40:10 -04001125 .args_type = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001126 .mhandler.cmd_new = qmp_marshal_block_commit,
Jeff Codyed61fc12012-09-27 13:29:16 -04001127 },
1128
Jeff Cody37222902014-01-24 09:02:37 -05001129SQMP
1130block-commit
1131------------
1132
1133Live commit of data from overlay image nodes into backing nodes - i.e., writes
1134data between 'top' and 'base' into 'base'.
1135
1136Arguments:
1137
1138- "device": The device's ID, must be unique (json-string)
1139- "base": The file name of the backing image to write data into.
1140 If not specified, this is the deepest backing image
1141 (json-string, optional)
1142- "top": The file name of the backing image within the image chain,
Jeff Cody7676e2c2014-06-30 15:14:15 +02001143 which contains the topmost data to be committed down. If
1144 not specified, this is the active layer. (json-string, optional)
Jeff Cody37222902014-01-24 09:02:37 -05001145
Jeff Cody54e26902014-06-25 15:40:10 -04001146- backing-file: The backing file string to write into the overlay
1147 image of 'top'. If 'top' is the active layer,
1148 specifying a backing file string is an error. This
1149 filename is not validated.
1150
1151 If a pathname string is such that it cannot be
1152 resolved by QEMU, that means that subsequent QMP or
1153 HMP commands must use node-names for the image in
1154 question, as filename lookup methods will fail.
1155
1156 If not specified, QEMU will automatically determine
1157 the backing file string to use, or error out if
1158 there is no obvious choice. Care should be taken
1159 when specifying the string, to specify a valid
1160 filename or protocol.
1161 (json-string, optional) (Since 2.1)
1162
Jeff Cody37222902014-01-24 09:02:37 -05001163 If top == base, that is an error.
1164 If top == active, the job will not be completed by itself,
1165 user needs to complete the job with the block-job-complete
1166 command after getting the ready event. (Since 2.0)
1167
1168 If the base image is smaller than top, then the base image
1169 will be resized to be the same size as top. If top is
1170 smaller than the base image, the base will not be
1171 truncated. If you want the base image size to match the
1172 size of the smaller top, you can safely truncate it
1173 yourself once the commit operation successfully completes.
1174 (json-string)
1175- "speed": the maximum speed, in bytes per second (json-int, optional)
1176
1177
1178Example:
1179
1180-> { "execute": "block-commit", "arguments": { "device": "virtio0",
1181 "top": "/tmp/snap1.qcow2" } }
1182<- { "return": {} }
1183
1184EQMP
1185
Jeff Codyed61fc12012-09-27 13:29:16 -04001186 {
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001187 .name = "drive-backup",
Stefan Hajnoczib53169e2013-06-26 14:11:57 +02001188 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
John Snowd58d8452015-04-17 19:49:58 -04001189 "bitmap:s?,on-source-error:s?,on-target-error:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001190 .mhandler.cmd_new = qmp_marshal_drive_backup,
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001191 },
1192
1193SQMP
1194drive-backup
1195------------
1196
1197Start a point-in-time copy of a block device to a new destination. The
1198status of ongoing drive-backup operations can be checked with
1199query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1200The operation can be stopped before it has completed using the
1201block-job-cancel command.
1202
1203Arguments:
1204
1205- "device": the name of the device which should be copied.
1206 (json-string)
1207- "target": the target of the new image. If the file exists, or if it is a
1208 device, the existing file/device will be used as the new
1209 destination. If it does not exist, a new file will be created.
1210 (json-string)
1211- "format": the format of the new destination, default is to probe if 'mode' is
1212 'existing', else the format of the source
1213 (json-string, optional)
Stefan Hajnoczib53169e2013-06-26 14:11:57 +02001214- "sync": what parts of the disk image should be copied to the destination;
1215 possibilities include "full" for all the disk, "top" for only the sectors
John Snow4b80ab22015-06-04 20:20:34 -04001216 allocated in the topmost image, "incremental" for only the dirty sectors in
John Snowd58d8452015-04-17 19:49:58 -04001217 the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
John Snow4b80ab22015-06-04 20:20:34 -04001218- "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
1219 is "incremental", must NOT be present otherwise.
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001220- "mode": whether and how QEMU should create a new image
1221 (NewImageMode, optional, default 'absolute-paths')
1222- "speed": the maximum speed, in bytes per second (json-int, optional)
1223- "on-source-error": the action to take on an error on the source, default
1224 'report'. 'stop' and 'enospc' can only be used
1225 if the block device supports io-status.
1226 (BlockdevOnError, optional)
1227- "on-target-error": the action to take on an error on the target, default
1228 'report' (no limitations, since this applies to
1229 a different block device than device).
1230 (BlockdevOnError, optional)
1231
1232Example:
1233-> { "execute": "drive-backup", "arguments": { "device": "drive0",
Ian Mainfc5d3f82013-07-26 11:39:04 -07001234 "sync": "full",
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001235 "target": "backup.img" } }
1236<- { "return": {} }
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001237
1238EQMP
1239
1240 {
1241 .name = "blockdev-backup",
1242 .args_type = "sync:s,device:B,target:B,speed:i?,"
1243 "on-source-error:s?,on-target-error:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001244 .mhandler.cmd_new = qmp_marshal_blockdev_backup,
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001245 },
1246
1247SQMP
1248blockdev-backup
1249---------------
1250
1251The device version of drive-backup: this command takes an existing named device
1252as backup target.
1253
1254Arguments:
1255
1256- "device": the name of the device which should be copied.
1257 (json-string)
1258- "target": the name of the backup target device. (json-string)
1259- "sync": what parts of the disk image should be copied to the destination;
1260 possibilities include "full" for all the disk, "top" for only the
1261 sectors allocated in the topmost image, or "none" to only replicate
1262 new I/O (MirrorSyncMode).
1263- "speed": the maximum speed, in bytes per second (json-int, optional)
1264- "on-source-error": the action to take on an error on the source, default
1265 'report'. 'stop' and 'enospc' can only be used
1266 if the block device supports io-status.
1267 (BlockdevOnError, optional)
1268- "on-target-error": the action to take on an error on the target, default
1269 'report' (no limitations, since this applies to
1270 a different block device than device).
1271 (BlockdevOnError, optional)
1272
1273Example:
1274-> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
1275 "sync": "full",
1276 "target": "tgt-id" } }
1277<- { "return": {} }
1278
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02001279EQMP
1280
1281 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01001282 .name = "block-job-set-speed",
Stefan Hajnoczi882ec7c2012-04-25 16:51:02 +01001283 .args_type = "device:B,speed:o",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001284 .mhandler.cmd_new = qmp_marshal_block_job_set_speed,
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +00001285 },
1286
1287 {
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01001288 .name = "block-job-cancel",
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001289 .args_type = "device:B,force:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001290 .mhandler.cmd_new = qmp_marshal_block_job_cancel,
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00001291 },
Jeff Codyc1864022012-02-28 15:54:07 -05001292 {
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001293 .name = "block-job-pause",
1294 .args_type = "device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001295 .mhandler.cmd_new = qmp_marshal_block_job_pause,
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001296 },
1297 {
1298 .name = "block-job-resume",
1299 .args_type = "device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001300 .mhandler.cmd_new = qmp_marshal_block_job_resume,
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02001301 },
1302 {
Paolo Bonziniaeae8832012-10-18 16:49:21 +02001303 .name = "block-job-complete",
1304 .args_type = "device:B",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001305 .mhandler.cmd_new = qmp_marshal_block_job_complete,
Paolo Bonziniaeae8832012-10-18 16:49:21 +02001306 },
1307 {
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001308 .name = "transaction",
John Snow94d16a62015-11-05 18:13:18 -05001309 .args_type = "actions:q,properties:q?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001310 .mhandler.cmd_new = qmp_marshal_transaction,
Jeff Codyc1864022012-02-28 15:54:07 -05001311 },
1312
1313SQMP
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001314transaction
1315-----------
Jeff Codyc1864022012-02-28 15:54:07 -05001316
Kashyap Chamarthya9105232015-10-02 14:12:34 +02001317Atomically operate on one or more block devices. Operations that are
1318currently supported:
1319
1320 - drive-backup
1321 - blockdev-backup
1322 - blockdev-snapshot-sync
1323 - blockdev-snapshot-internal-sync
1324 - abort
1325 - block-dirty-bitmap-add
1326 - block-dirty-bitmap-clear
1327
1328Refer to the qemu/qapi-schema.json file for minimum required QEMU
1329versions for these operations. A list of dictionaries is accepted,
1330that contains the actions to be performed. If there is any failure
1331performing any of the operations, all operations for the group are
1332abandoned.
Jeff Codyc1864022012-02-28 15:54:07 -05001333
Wenchao Xiabbe86012013-09-11 14:04:34 +08001334For external snapshots, the dictionary contains the device, the file to use for
1335the new snapshot, and the format. The default format, if not specified, is
1336qcow2.
Jeff Codyc1864022012-02-28 15:54:07 -05001337
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001338Each new snapshot defaults to being created by QEMU (wiping any
1339contents if the file already exists), but it is also possible to reuse
1340an externally-created file. In the latter case, you should ensure that
1341the new image file has the same contents as the current one; QEMU cannot
1342perform any meaningful check. Typically this is achieved by using the
1343current image file as the backing file for the new image.
1344
Wenchao Xiabbe86012013-09-11 14:04:34 +08001345On failure, the original disks pre-snapshot attempt will be used.
1346
1347For internal snapshots, the dictionary contains the device and the snapshot's
1348name. If an internal snapshot matching name already exists, the request will
1349be rejected. Only some image formats support it, for example, qcow2, rbd,
1350and sheepdog.
1351
1352On failure, qemu will try delete the newly created internal snapshot in the
1353transaction. When an I/O error occurs during deletion, the user needs to fix
1354it later with qemu-img or other command.
1355
Jeff Codyc1864022012-02-28 15:54:07 -05001356Arguments:
1357
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001358actions array:
Kashyap Chamarthya9105232015-10-02 14:12:34 +02001359 - "type": the operation to perform (json-string). Possible
1360 values: "drive-backup", "blockdev-backup",
1361 "blockdev-snapshot-sync",
1362 "blockdev-snapshot-internal-sync",
1363 "abort", "block-dirty-bitmap-add",
1364 "block-dirty-bitmap-clear"
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001365 - "data": a dictionary. The contents depend on the value
1366 of "type". When "type" is "blockdev-snapshot-sync":
1367 - "device": device name to snapshot (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001368 - "node-name": graph node name to snapshot (json-string)
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001369 - "snapshot-file": name of new image file (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001370 - "snapshot-node-name": graph node name of the new snapshot (json-string)
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001371 - "format": format of new image (json-string, optional)
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001372 - "mode": whether and how QEMU should create the snapshot file
1373 (NewImageMode, optional, default "absolute-paths")
Wenchao Xiabbe86012013-09-11 14:04:34 +08001374 When "type" is "blockdev-snapshot-internal-sync":
1375 - "device": device name to snapshot (json-string)
1376 - "name": name of the new snapshot (json-string)
Jeff Codyc1864022012-02-28 15:54:07 -05001377
1378Example:
1379
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001380-> { "execute": "transaction",
1381 "arguments": { "actions": [
Eric Blakecd0c5382014-05-06 09:39:03 -06001382 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001383 "snapshot-file": "/some/place/my-image",
1384 "format": "qcow2" } },
Eric Blakecd0c5382014-05-06 09:39:03 -06001385 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
Benoît Canet0901f672014-01-23 21:31:38 +01001386 "snapshot-file": "/some/place/my-image2",
1387 "snapshot-node-name": "node3432",
1388 "mode": "existing",
1389 "format": "qcow2" } },
Eric Blakecd0c5382014-05-06 09:39:03 -06001390 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001391 "snapshot-file": "/some/place/my-image2",
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001392 "mode": "existing",
Wenchao Xiabbe86012013-09-11 14:04:34 +08001393 "format": "qcow2" } },
Eric Blakecd0c5382014-05-06 09:39:03 -06001394 { "type": "blockdev-snapshot-internal-sync", "data" : {
Wenchao Xiabbe86012013-09-11 14:04:34 +08001395 "device": "ide-hd2",
1396 "name": "snapshot0" } } ] } }
Jeff Codyc1864022012-02-28 15:54:07 -05001397<- { "return": {} }
1398
1399EQMP
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00001400
1401 {
John Snow341ebc22015-04-17 19:49:52 -04001402 .name = "block-dirty-bitmap-add",
1403 .args_type = "node:B,name:s,granularity:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001404 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_add,
John Snow341ebc22015-04-17 19:49:52 -04001405 },
1406
1407SQMP
1408
1409block-dirty-bitmap-add
1410----------------------
1411Since 2.4
1412
1413Create a dirty bitmap with a name on the device, and start tracking the writes.
1414
1415Arguments:
1416
1417- "node": device/node on which to create dirty bitmap (json-string)
1418- "name": name of the new dirty bitmap (json-string)
1419- "granularity": granularity to track writes with (int, optional)
1420
1421Example:
1422
1423-> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
1424 "name": "bitmap0" } }
1425<- { "return": {} }
1426
1427EQMP
1428
1429 {
1430 .name = "block-dirty-bitmap-remove",
1431 .args_type = "node:B,name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001432 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_remove,
John Snow341ebc22015-04-17 19:49:52 -04001433 },
1434
1435SQMP
1436
1437block-dirty-bitmap-remove
1438-------------------------
1439Since 2.4
1440
1441Stop write tracking and remove the dirty bitmap that was created with
1442block-dirty-bitmap-add.
1443
1444Arguments:
1445
1446- "node": device/node on which to remove dirty bitmap (json-string)
1447- "name": name of the dirty bitmap to remove (json-string)
1448
1449Example:
1450
1451-> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
1452 "name": "bitmap0" } }
1453<- { "return": {} }
1454
1455EQMP
1456
1457 {
John Snowe74e6b72015-04-17 19:49:59 -04001458 .name = "block-dirty-bitmap-clear",
1459 .args_type = "node:B,name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001460 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_clear,
John Snowe74e6b72015-04-17 19:49:59 -04001461 },
1462
1463SQMP
1464
1465block-dirty-bitmap-clear
1466------------------------
1467Since 2.4
1468
1469Reset the dirty bitmap associated with a node so that an incremental backup
1470from this point in time forward will only backup clusters modified after this
1471clear operation.
1472
1473Arguments:
1474
1475- "node": device/node on which to remove dirty bitmap (json-string)
1476- "name": name of the dirty bitmap to remove (json-string)
1477
1478Example:
1479
1480-> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1481 "name": "bitmap0" } }
1482<- { "return": {} }
1483
1484EQMP
1485
1486 {
Jes Sorensend967b2f2011-07-11 20:01:09 +02001487 .name = "blockdev-snapshot-sync",
Benoît Canet0901f672014-01-23 21:31:38 +01001488 .args_type = "device:s?,node-name:s?,snapshot-file:s,snapshot-node-name:s?,format:s?,mode:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001489 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_sync,
Jes Sorensend967b2f2011-07-11 20:01:09 +02001490 },
1491
1492SQMP
1493blockdev-snapshot-sync
1494----------------------
1495
1496Synchronous snapshot of a block device. snapshot-file specifies the
1497target of the new image. If the file exists, or if it is a device, the
1498snapshot will be created in the existing file/device. If does not
1499exist, a new file will be created. format specifies the format of the
1500snapshot image, default is qcow2.
1501
1502Arguments:
1503
1504- "device": device name to snapshot (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001505- "node-name": graph node name to snapshot (json-string)
Jes Sorensend967b2f2011-07-11 20:01:09 +02001506- "snapshot-file": name of new image file (json-string)
Benoît Canet0901f672014-01-23 21:31:38 +01001507- "snapshot-node-name": graph node name of the new snapshot (json-string)
Paolo Bonzini6cc2a412012-03-06 18:55:59 +01001508- "mode": whether and how QEMU should create the snapshot file
1509 (NewImageMode, optional, default "absolute-paths")
Jes Sorensend967b2f2011-07-11 20:01:09 +02001510- "format": format of new image (json-string, optional)
1511
1512Example:
1513
Luiz Capitulino7f3850c2011-10-10 17:30:08 -03001514-> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1515 "snapshot-file":
1516 "/some/place/my-image",
1517 "format": "qcow2" } }
Jes Sorensend967b2f2011-07-11 20:01:09 +02001518<- { "return": {} }
1519
1520EQMP
1521
1522 {
Alberto Garcia43de7e22015-10-26 14:27:16 +02001523 .name = "blockdev-snapshot",
1524 .args_type = "node:s,overlay:s",
1525 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot,
1526 },
1527
1528SQMP
1529blockdev-snapshot
1530-----------------
1531Since 2.5
1532
1533Create a snapshot, by installing 'node' as the backing image of
1534'overlay'. Additionally, if 'node' is associated with a block
1535device, the block device changes to using 'overlay' as its new active
1536image.
1537
1538Arguments:
1539
1540- "node": device that will have a snapshot created (json-string)
1541- "overlay": device that will have 'node' as its backing image (json-string)
1542
1543Example:
1544
1545-> { "execute": "blockdev-add",
1546 "arguments": { "options": { "driver": "qcow2",
1547 "node-name": "node1534",
1548 "file": { "driver": "file",
1549 "filename": "hd1.qcow2" },
1550 "backing": "" } } }
1551
1552<- { "return": {} }
1553
1554-> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
1555 "overlay": "node1534" } }
1556<- { "return": {} }
1557
1558EQMP
1559
1560 {
Wenchao Xiaf323bc92013-09-11 14:04:35 +08001561 .name = "blockdev-snapshot-internal-sync",
1562 .args_type = "device:B,name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001563 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_internal_sync,
Wenchao Xiaf323bc92013-09-11 14:04:35 +08001564 },
1565
1566SQMP
1567blockdev-snapshot-internal-sync
1568-------------------------------
1569
1570Synchronously take an internal snapshot of a block device when the format of
1571image used supports it. If the name is an empty string, or a snapshot with
1572name already exists, the operation will fail.
1573
1574Arguments:
1575
1576- "device": device name to snapshot (json-string)
1577- "name": name of the new snapshot (json-string)
1578
1579Example:
1580
1581-> { "execute": "blockdev-snapshot-internal-sync",
1582 "arguments": { "device": "ide-hd0",
1583 "name": "snapshot0" }
1584 }
1585<- { "return": {} }
1586
1587EQMP
1588
1589 {
Wenchao Xia44e3e052013-09-11 14:04:36 +08001590 .name = "blockdev-snapshot-delete-internal-sync",
1591 .args_type = "device:B,id:s?,name:s?",
1592 .mhandler.cmd_new =
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001593 qmp_marshal_blockdev_snapshot_delete_internal_sync,
Wenchao Xia44e3e052013-09-11 14:04:36 +08001594 },
1595
1596SQMP
1597blockdev-snapshot-delete-internal-sync
1598--------------------------------------
1599
1600Synchronously delete an internal snapshot of a block device when the format of
1601image used supports it. The snapshot is identified by name or id or both. One
1602of name or id is required. If the snapshot is not found, the operation will
1603fail.
1604
1605Arguments:
1606
1607- "device": device name (json-string)
1608- "id": ID of the snapshot (json-string, optional)
1609- "name": name of the snapshot (json-string, optional)
1610
1611Example:
1612
1613-> { "execute": "blockdev-snapshot-delete-internal-sync",
1614 "arguments": { "device": "ide-hd0",
1615 "name": "snapshot0" }
1616 }
1617<- { "return": {
1618 "id": "1",
1619 "name": "snapshot0",
1620 "vm-state-size": 0,
1621 "date-sec": 1000012,
1622 "date-nsec": 10,
1623 "vm-clock-sec": 100,
1624 "vm-clock-nsec": 20
1625 }
1626 }
1627
1628EQMP
1629
1630 {
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001631 .name = "drive-mirror",
Paolo Bonzinib952b552012-10-18 16:49:28 +02001632 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
Benoît Canet09158f02014-06-27 18:25:25 +02001633 "node-name:s?,replaces:s?,"
Paolo Bonzinieee13df2013-01-21 17:09:46 +01001634 "on-source-error:s?,on-target-error:s?,"
Fam Zheng0fc9f8e2015-06-08 13:56:08 +08001635 "unmap:b?,"
Paolo Bonzini08e4ed62013-01-22 09:03:13 +01001636 "granularity:i?,buf-size:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001637 .mhandler.cmd_new = qmp_marshal_drive_mirror,
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001638 },
1639
1640SQMP
1641drive-mirror
1642------------
1643
1644Start mirroring a block device's writes to a new destination. target
1645specifies the target of the new image. If the file exists, or if it is
1646a device, it will be used as the new destination for writes. If it does not
1647exist, a new file will be created. format specifies the format of the
1648mirror image, default is to probe if mode='existing', else the format
1649of the source.
1650
1651Arguments:
1652
1653- "device": device name to operate on (json-string)
1654- "target": name of new image file (json-string)
1655- "format": format of new image (json-string, optional)
Benoît Canet4c828dc2014-06-16 12:00:55 +02001656- "node-name": the name of the new block driver state in the node graph
1657 (json-string, optional)
Benoît Canet09158f02014-06-27 18:25:25 +02001658- "replaces": the block driver node name to replace when finished
1659 (json-string, optional)
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001660- "mode": how an image file should be created into the target
1661 file/device (NewImageMode, optional, default 'absolute-paths')
1662- "speed": maximum speed of the streaming job, in bytes per second
1663 (json-int)
Paolo Bonzinieee13df2013-01-21 17:09:46 +01001664- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
Fam Zhengdf925622015-12-24 12:45:05 +08001665- "buf-size": maximum amount of data in flight from source to target, in bytes
Paolo Bonzini08e4ed62013-01-22 09:03:13 +01001666 (json-int, default 10M)
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001667- "sync": what parts of the disk image should be copied to the destination;
1668 possibilities include "full" for all the disk, "top" for only the sectors
1669 allocated in the topmost image, or "none" to only replicate new I/O
1670 (MirrorSyncMode).
Paolo Bonzinib952b552012-10-18 16:49:28 +02001671- "on-source-error": the action to take on an error on the source
1672 (BlockdevOnError, default 'report')
1673- "on-target-error": the action to take on an error on the target
1674 (BlockdevOnError, default 'report')
Fam Zheng0fc9f8e2015-06-08 13:56:08 +08001675- "unmap": whether the target sectors should be discarded where source has only
1676 zeroes. (json-bool, optional, default true)
Paolo Bonzinib952b552012-10-18 16:49:28 +02001677
Paolo Bonzinieee13df2013-01-21 17:09:46 +01001678The default value of the granularity is the image cluster size clamped
1679between 4096 and 65536, if the image format defines one. If the format
1680does not define a cluster size, the default value of the granularity
1681is 65536.
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02001682
1683
1684Example:
1685
1686-> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1687 "target": "/some/place/my-image",
1688 "sync": "full",
1689 "format": "qcow2" } }
1690<- { "return": {} }
1691
1692EQMP
1693
1694 {
Fam Zhengdf925622015-12-24 12:45:05 +08001695 .name = "blockdev-mirror",
1696 .args_type = "sync:s,device:B,target:B,replaces:s?,speed:i?,"
1697 "on-source-error:s?,on-target-error:s?,"
1698 "granularity:i?,buf-size:i?",
1699 .mhandler.cmd_new = qmp_marshal_blockdev_mirror,
1700 },
1701
1702SQMP
1703blockdev-mirror
1704------------
1705
1706Start mirroring a block device's writes to another block device. target
1707specifies the target of mirror operation.
1708
1709Arguments:
1710
1711- "device": device name to operate on (json-string)
1712- "target": device name to mirror to (json-string)
1713- "replaces": the block driver node name to replace when finished
1714 (json-string, optional)
1715- "speed": maximum speed of the streaming job, in bytes per second
1716 (json-int)
1717- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1718- "buf_size": maximum amount of data in flight from source to target, in bytes
1719 (json-int, default 10M)
1720- "sync": what parts of the disk image should be copied to the destination;
1721 possibilities include "full" for all the disk, "top" for only the sectors
1722 allocated in the topmost image, or "none" to only replicate new I/O
1723 (MirrorSyncMode).
1724- "on-source-error": the action to take on an error on the source
1725 (BlockdevOnError, default 'report')
1726- "on-target-error": the action to take on an error on the target
1727 (BlockdevOnError, default 'report')
1728
1729The default value of the granularity is the image cluster size clamped
1730between 4096 and 65536, if the image format defines one. If the format
1731does not define a cluster size, the default value of the granularity
1732is 65536.
1733
1734Example:
1735
1736-> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
1737 "target": "target0",
1738 "sync": "full" } }
1739<- { "return": {} }
1740
1741EQMP
1742 {
Jeff Codyfa40e652014-07-01 09:52:16 +02001743 .name = "change-backing-file",
1744 .args_type = "device:s,image-node-name:s,backing-file:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001745 .mhandler.cmd_new = qmp_marshal_change_backing_file,
Jeff Codyfa40e652014-07-01 09:52:16 +02001746 },
1747
1748SQMP
1749change-backing-file
1750-------------------
1751Since: 2.1
1752
1753Change the backing file in the image file metadata. This does not cause
1754QEMU to reopen the image file to reparse the backing filename (it may,
1755however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1756if needed). The new backing file string is written into the image file
1757metadata, and the QEMU internal strings are updated.
1758
1759Arguments:
1760
1761- "image-node-name": The name of the block driver state node of the
1762 image to modify. The "device" is argument is used to
1763 verify "image-node-name" is in the chain described by
1764 "device".
1765 (json-string, optional)
1766
1767- "device": The name of the device.
1768 (json-string)
1769
1770- "backing-file": The string to write as the backing file. This string is
1771 not validated, so care should be taken when specifying
1772 the string or the image chain may not be able to be
1773 reopened again.
1774 (json-string)
1775
1776Returns: Nothing on success
1777 If "device" does not exist or cannot be determined, DeviceNotFound
1778
1779EQMP
1780
1781 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001782 .name = "balloon",
1783 .args_type = "value:M",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001784 .mhandler.cmd_new = qmp_marshal_balloon,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001785 },
1786
1787SQMP
1788balloon
1789-------
1790
1791Request VM to change its memory allocation (in bytes).
1792
1793Arguments:
1794
1795- "value": New memory allocation (json-int)
1796
1797Example:
1798
1799-> { "execute": "balloon", "arguments": { "value": 536870912 } }
1800<- { "return": {} }
1801
1802EQMP
1803
1804 {
1805 .name = "set_link",
1806 .args_type = "name:s,up:b",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001807 .mhandler.cmd_new = qmp_marshal_set_link,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001808 },
1809
1810SQMP
1811set_link
1812--------
1813
1814Change the link status of a network adapter.
1815
1816Arguments:
1817
1818- "name": network device name (json-string)
1819- "up": status is up (json-bool)
1820
1821Example:
1822
1823-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1824<- { "return": {} }
1825
1826EQMP
1827
1828 {
1829 .name = "getfd",
1830 .args_type = "fdname:s",
1831 .params = "getfd name",
1832 .help = "receive a file descriptor via SCM rights and assign it a name",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001833 .mhandler.cmd_new = qmp_marshal_getfd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001834 },
1835
1836SQMP
1837getfd
1838-----
1839
1840Receive a file descriptor via SCM rights and assign it a name.
1841
1842Arguments:
1843
1844- "fdname": file descriptor name (json-string)
1845
1846Example:
1847
1848-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1849<- { "return": {} }
1850
Corey Bryant208c9d12012-06-22 14:36:09 -04001851Notes:
1852
1853(1) If the name specified by the "fdname" argument already exists,
1854 the file descriptor assigned to it will be closed and replaced
1855 by the received file descriptor.
1856(2) The 'closefd' command can be used to explicitly close the file
1857 descriptor when it is no longer needed.
1858
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001859EQMP
1860
1861 {
1862 .name = "closefd",
1863 .args_type = "fdname:s",
1864 .params = "closefd name",
1865 .help = "close a file descriptor previously passed via SCM rights",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001866 .mhandler.cmd_new = qmp_marshal_closefd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03001867 },
1868
1869SQMP
1870closefd
1871-------
1872
1873Close a file descriptor previously passed via SCM rights.
1874
1875Arguments:
1876
1877- "fdname": file descriptor name (json-string)
1878
1879Example:
1880
1881-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1882<- { "return": {} }
1883
1884EQMP
1885
Corey Bryantba1c0482012-08-14 16:43:43 -04001886 {
1887 .name = "add-fd",
1888 .args_type = "fdset-id:i?,opaque:s?",
1889 .params = "add-fd fdset-id opaque",
1890 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001891 .mhandler.cmd_new = qmp_marshal_add_fd,
Corey Bryantba1c0482012-08-14 16:43:43 -04001892 },
1893
1894SQMP
1895add-fd
1896-------
1897
1898Add a file descriptor, that was passed via SCM rights, to an fd set.
1899
1900Arguments:
1901
1902- "fdset-id": The ID of the fd set to add the file descriptor to.
1903 (json-int, optional)
1904- "opaque": A free-form string that can be used to describe the fd.
1905 (json-string, optional)
1906
1907Return a json-object with the following information:
1908
1909- "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1910- "fd": The file descriptor that was received via SCM rights and added to the
1911 fd set. (json-int)
1912
1913Example:
1914
1915-> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1916<- { "return": { "fdset-id": 1, "fd": 3 } }
1917
1918Notes:
1919
1920(1) The list of fd sets is shared by all monitor connections.
1921(2) If "fdset-id" is not specified, a new fd set will be created.
1922
1923EQMP
1924
1925 {
1926 .name = "remove-fd",
1927 .args_type = "fdset-id:i,fd:i?",
1928 .params = "remove-fd fdset-id fd",
1929 .help = "Remove a file descriptor from an fd set",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001930 .mhandler.cmd_new = qmp_marshal_remove_fd,
Corey Bryantba1c0482012-08-14 16:43:43 -04001931 },
1932
1933SQMP
1934remove-fd
1935---------
1936
1937Remove a file descriptor from an fd set.
1938
1939Arguments:
1940
1941- "fdset-id": The ID of the fd set that the file descriptor belongs to.
1942 (json-int)
1943- "fd": The file descriptor that is to be removed. (json-int, optional)
1944
1945Example:
1946
1947-> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1948<- { "return": {} }
1949
1950Notes:
1951
1952(1) The list of fd sets is shared by all monitor connections.
1953(2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1954 removed.
1955
1956EQMP
1957
1958 {
1959 .name = "query-fdsets",
1960 .args_type = "",
1961 .help = "Return information describing all fd sets",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02001962 .mhandler.cmd_new = qmp_marshal_query_fdsets,
Corey Bryantba1c0482012-08-14 16:43:43 -04001963 },
1964
1965SQMP
1966query-fdsets
1967-------------
1968
1969Return information describing all fd sets.
1970
1971Arguments: None
1972
1973Example:
1974
1975-> { "execute": "query-fdsets" }
1976<- { "return": [
1977 {
1978 "fds": [
1979 {
1980 "fd": 30,
1981 "opaque": "rdonly:/path/to/file"
1982 },
1983 {
1984 "fd": 24,
1985 "opaque": "rdwr:/path/to/file"
1986 }
1987 ],
1988 "fdset-id": 1
1989 },
1990 {
1991 "fds": [
1992 {
1993 "fd": 28
1994 },
1995 {
1996 "fd": 29
1997 }
1998 ],
1999 "fdset-id": 0
2000 }
2001 ]
2002 }
2003
2004Note: The list of fd sets is shared by all monitor connections.
2005
2006EQMP
2007
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002008 {
2009 .name = "block_passwd",
Benoît Canet12d3ba82014-01-23 21:31:35 +01002010 .args_type = "device:s?,node-name:s?,password:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002011 .mhandler.cmd_new = qmp_marshal_block_passwd,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002012 },
2013
2014SQMP
2015block_passwd
2016------------
2017
2018Set the password of encrypted block devices.
2019
2020Arguments:
2021
2022- "device": device name (json-string)
Benoît Canet12d3ba82014-01-23 21:31:35 +01002023- "node-name": name in the block driver state graph (json-string)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002024- "password": password (json-string)
2025
2026Example:
2027
2028-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
2029 "password": "12345" } }
2030<- { "return": {} }
2031
2032EQMP
2033
2034 {
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002035 .name = "block_set_io_throttle",
Alberto Garciadce13202016-02-18 12:27:03 +02002036 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l,bps_max:l?,bps_rd_max:l?,bps_wr_max:l?,iops_max:l?,iops_rd_max:l?,iops_wr_max:l?,bps_max_length:l?,bps_rd_max_length:l?,bps_wr_max_length:l?,iops_max_length:l?,iops_rd_max_length:l?,iops_wr_max_length:l?,iops_size:l?,group:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002037 .mhandler.cmd_new = qmp_marshal_block_set_io_throttle,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002038 },
2039
2040SQMP
2041block_set_io_throttle
2042------------
2043
2044Change I/O throttle limits for a block drive.
2045
2046Arguments:
2047
2048- "device": device name (json-string)
Eric Blake586b5462013-08-30 14:44:11 -06002049- "bps": total throughput limit in bytes per second (json-int)
2050- "bps_rd": read throughput limit in bytes per second (json-int)
2051- "bps_wr": write throughput limit in bytes per second (json-int)
2052- "iops": total I/O operations per second (json-int)
2053- "iops_rd": read I/O operations per second (json-int)
2054- "iops_wr": write I/O operations per second (json-int)
Alberto Garciadce13202016-02-18 12:27:03 +02002055- "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
2056- "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
2057- "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
2058- "iops_max": total I/O operations per second during bursts (json-int, optional)
2059- "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
2060- "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
2061- "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
2062- "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
2063- "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
2064- "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
2065- "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
2066- "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
2067- "iops_size": I/O size in bytes when limiting (json-int, optional)
2068- "group": throttle group name (json-string, optional)
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002069
2070Example:
2071
2072-> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
Eric Blake586b5462013-08-30 14:44:11 -06002073 "bps": 1000000,
2074 "bps_rd": 0,
2075 "bps_wr": 0,
2076 "iops": 0,
2077 "iops_rd": 0,
Benoît Canet3e9fab62013-09-02 14:14:40 +02002078 "iops_wr": 0,
2079 "bps_max": 8000000,
2080 "bps_rd_max": 0,
2081 "bps_wr_max": 0,
2082 "iops_max": 0,
2083 "iops_rd_max": 0,
Benoît Canet2024c1d2013-09-02 14:14:41 +02002084 "iops_wr_max": 0,
Alberto Garciadce13202016-02-18 12:27:03 +02002085 "bps_max_length": 60,
Benoît Canet2024c1d2013-09-02 14:14:41 +02002086 "iops_size": 0 } }
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002087<- { "return": {} }
2088
2089EQMP
2090
2091 {
Gerd Hoffmann75721502010-10-07 12:22:54 +02002092 .name = "set_password",
2093 .args_type = "protocol:s,password:s,connected:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002094 .mhandler.cmd_new = qmp_marshal_set_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02002095 },
2096
2097SQMP
2098set_password
2099------------
2100
2101Set the password for vnc/spice protocols.
2102
2103Arguments:
2104
2105- "protocol": protocol name (json-string)
2106- "password": password (json-string)
Alberto Garcia3599d462015-02-26 16:35:07 +02002107- "connected": [ keep | disconnect | fail ] (json-string, optional)
Gerd Hoffmann75721502010-10-07 12:22:54 +02002108
2109Example:
2110
2111-> { "execute": "set_password", "arguments": { "protocol": "vnc",
2112 "password": "secret" } }
2113<- { "return": {} }
2114
2115EQMP
2116
2117 {
2118 .name = "expire_password",
2119 .args_type = "protocol:s,time:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002120 .mhandler.cmd_new = qmp_marshal_expire_password,
Gerd Hoffmann75721502010-10-07 12:22:54 +02002121 },
2122
2123SQMP
2124expire_password
2125---------------
2126
2127Set the password expire time for vnc/spice protocols.
2128
2129Arguments:
2130
2131- "protocol": protocol name (json-string)
2132- "time": [ now | never | +secs | secs ] (json-string)
2133
2134Example:
2135
2136-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
2137 "time": "+60" } }
2138<- { "return": {} }
2139
2140EQMP
2141
2142 {
Daniel P. Berrange13661082011-06-23 13:31:42 +01002143 .name = "add_client",
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00002144 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002145 .mhandler.cmd_new = qmp_marshal_add_client,
Daniel P. Berrange13661082011-06-23 13:31:42 +01002146 },
2147
2148SQMP
2149add_client
2150----------
2151
2152Add a graphics client
2153
2154Arguments:
2155
2156- "protocol": protocol name (json-string)
2157- "fdname": file descriptor name (json-string)
Daniel P. Berrangef1f5f402012-02-13 13:43:08 +00002158- "skipauth": whether to skip authentication (json-bool, optional)
2159- "tls": whether to perform TLS (json-bool, optional)
Daniel P. Berrange13661082011-06-23 13:31:42 +01002160
2161Example:
2162
2163-> { "execute": "add_client", "arguments": { "protocol": "vnc",
2164 "fdname": "myclient" } }
2165<- { "return": {} }
2166
2167EQMP
2168 {
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002169 .name = "qmp_capabilities",
2170 .args_type = "",
2171 .params = "",
2172 .help = "enable QMP capabilities",
Markus Armbruster485febc2015-03-13 17:25:50 +01002173 .mhandler.cmd_new = qmp_capabilities,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002174 },
2175
2176SQMP
2177qmp_capabilities
2178----------------
2179
2180Enable QMP capabilities.
2181
2182Arguments: None.
2183
2184Example:
2185
2186-> { "execute": "qmp_capabilities" }
2187<- { "return": {} }
2188
2189Note: This command must be issued before issuing any other command.
2190
Luiz Capitulino0268d972010-10-22 10:08:02 -02002191EQMP
2192
2193 {
2194 .name = "human-monitor-command",
2195 .args_type = "command-line:s,cpu-index:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002196 .mhandler.cmd_new = qmp_marshal_human_monitor_command,
Luiz Capitulino0268d972010-10-22 10:08:02 -02002197 },
2198
2199SQMP
2200human-monitor-command
2201---------------------
2202
2203Execute a Human Monitor command.
2204
2205Arguments:
2206
2207- command-line: the command name and its arguments, just like the
2208 Human Monitor's shell (json-string)
2209- cpu-index: select the CPU number to be used by commands which access CPU
2210 data, like 'info registers'. The Monitor selects CPU 0 if this
2211 argument is not provided (json-int, optional)
2212
2213Example:
2214
2215-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
2216<- { "return": "kvm support: enabled\r\n" }
2217
2218Notes:
2219
2220(1) The Human Monitor is NOT an stable interface, this means that command
2221 names, arguments and responses can change or be removed at ANY time.
2222 Applications that rely on long term stability guarantees should NOT
2223 use this command
2224
2225(2) Limitations:
2226
2227 o This command is stateless, this means that commands that depend
2228 on state information (such as getfd) might not work
2229
2230 o Commands that prompt the user for data (eg. 'cont' when the block
2231 device is encrypted) don't currently work
2232
Luiz Capitulino82a56f02010-09-13 12:26:00 -030022333. Query Commands
2234=================
2235
2236HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
2237HXCOMM this! We will possibly move query commands definitions inside those
2238HXCOMM sections, just like regular commands.
2239
2240EQMP
2241
2242SQMP
2243query-version
2244-------------
2245
2246Show QEMU version.
2247
2248Return a json-object with the following information:
2249
2250- "qemu": A json-object containing three integer values:
2251 - "major": QEMU's major version (json-int)
2252 - "minor": QEMU's minor version (json-int)
2253 - "micro": QEMU's micro version (json-int)
2254- "package": package's version (json-string)
2255
2256Example:
2257
2258-> { "execute": "query-version" }
2259<- {
2260 "return":{
2261 "qemu":{
2262 "major":0,
2263 "minor":11,
2264 "micro":5
2265 },
2266 "package":""
2267 }
2268 }
2269
2270EQMP
2271
Luiz Capitulinob9c15f12011-08-26 17:38:13 -03002272 {
2273 .name = "query-version",
2274 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002275 .mhandler.cmd_new = qmp_marshal_query_version,
Luiz Capitulinob9c15f12011-08-26 17:38:13 -03002276 },
2277
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002278SQMP
2279query-commands
2280--------------
2281
2282List QMP available commands.
2283
2284Each command is represented by a json-object, the returned value is a json-array
2285of all commands.
2286
2287Each json-object contain:
2288
2289- "name": command's name (json-string)
2290
2291Example:
2292
2293-> { "execute": "query-commands" }
2294<- {
2295 "return":[
2296 {
2297 "name":"query-balloon"
2298 },
2299 {
2300 "name":"system_powerdown"
2301 }
2302 ]
2303 }
2304
2305Note: This example has been shortened as the real response is too long.
2306
2307EQMP
2308
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -03002309 {
2310 .name = "query-commands",
2311 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002312 .mhandler.cmd_new = qmp_marshal_query_commands,
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -03002313 },
2314
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002315SQMP
Daniel P. Berrange48608532012-05-21 17:59:51 +01002316query-events
2317--------------
2318
2319List QMP available events.
2320
2321Each event is represented by a json-object, the returned value is a json-array
2322of all events.
2323
2324Each json-object contains:
2325
2326- "name": event's name (json-string)
2327
2328Example:
2329
2330-> { "execute": "query-events" }
2331<- {
2332 "return":[
2333 {
2334 "name":"SHUTDOWN"
2335 },
2336 {
2337 "name":"RESET"
2338 }
2339 ]
2340 }
2341
2342Note: This example has been shortened as the real response is too long.
2343
2344EQMP
2345
2346 {
2347 .name = "query-events",
2348 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002349 .mhandler.cmd_new = qmp_marshal_query_events,
Daniel P. Berrange48608532012-05-21 17:59:51 +01002350 },
2351
2352SQMP
Markus Armbruster39a18152015-09-16 13:06:28 +02002353query-qmp-schema
2354----------------
2355
2356Return the QMP wire schema. The returned value is a json-array of
2357named schema entities. Entities are commands, events and various
2358types. See docs/qapi-code-gen.txt for information on their structure
2359and intended use.
2360
2361EQMP
2362
2363 {
2364 .name = "query-qmp-schema",
2365 .args_type = "",
2366 .mhandler.cmd_new = qmp_query_qmp_schema,
2367 },
2368
2369SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002370query-chardev
2371-------------
2372
2373Each device is represented by a json-object. The returned value is a json-array
2374of all devices.
2375
2376Each json-object contain the following:
2377
2378- "label": device's label (json-string)
2379- "filename": device's file (json-string)
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002380- "frontend-open": open/closed state of the frontend device attached to this
2381 backend (json-bool)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002382
2383Example:
2384
2385-> { "execute": "query-chardev" }
2386<- {
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002387 "return": [
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002388 {
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002389 "label": "charchannel0",
2390 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
2391 "frontend-open": false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002392 },
2393 {
Laszlo Ersek32a97ea2014-06-26 17:50:03 +02002394 "label": "charmonitor",
2395 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
2396 "frontend-open": true
2397 },
2398 {
2399 "label": "charserial0",
2400 "filename": "pty:/dev/pts/2",
2401 "frontend-open": true
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002402 }
2403 ]
2404 }
2405
2406EQMP
2407
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -03002408 {
2409 .name = "query-chardev",
2410 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002411 .mhandler.cmd_new = qmp_marshal_query_chardev,
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -03002412 },
2413
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002414SQMP
Martin Kletzander77d1c3c2014-02-01 12:52:42 +01002415query-chardev-backends
2416-------------
2417
2418List available character device backends.
2419
2420Each backend is represented by a json-object, the returned value is a json-array
2421of all backends.
2422
2423Each json-object contains:
2424
2425- "name": backend name (json-string)
2426
2427Example:
2428
2429-> { "execute": "query-chardev-backends" }
2430<- {
2431 "return":[
2432 {
2433 "name":"udp"
2434 },
2435 {
2436 "name":"tcp"
2437 },
2438 {
2439 "name":"unix"
2440 },
2441 {
2442 "name":"spiceport"
2443 }
2444 ]
2445 }
2446
2447EQMP
2448
2449 {
2450 .name = "query-chardev-backends",
2451 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002452 .mhandler.cmd_new = qmp_marshal_query_chardev_backends,
Martin Kletzander77d1c3c2014-02-01 12:52:42 +01002453 },
2454
2455SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002456query-block
2457-----------
2458
2459Show the block devices.
2460
2461Each block device information is stored in a json-object and the returned value
2462is a json-array of all devices.
2463
2464Each json-object contain the following:
2465
2466- "device": device name (json-string)
2467- "type": device type (json-string)
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002468 - deprecated, retained for backward compatibility
2469 - Possible values: "unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002470- "removable": true if the device is removable, false otherwise (json-bool)
2471- "locked": true if the device is locked, false otherwise (json-bool)
Michal Privoznik99f42802013-01-29 17:58:41 +01002472- "tray_open": only present if removable, true if the device has a tray,
Markus Armbrustere4def802011-09-06 18:58:53 +02002473 and it is open (json-bool)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002474- "inserted": only present if the device is inserted, it is a json-object
2475 containing the following:
2476 - "file": device file name (json-string)
2477 - "ro": true if read-only, false otherwise (json-bool)
2478 - "drv": driver format name (json-string)
Stefan Hajnoczi550830f2014-09-16 15:24:24 +01002479 - Possible values: "blkdebug", "bochs", "cloop", "dmg",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002480 "file", "file", "ftp", "ftps", "host_cdrom",
Markus Armbruster92a539d2015-03-17 17:02:20 +01002481 "host_device", "http", "https",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002482 "nbd", "parallels", "qcow", "qcow2", "raw",
2483 "tftp", "vdi", "vmdk", "vpc", "vvfat"
2484 - "backing_file": backing file name (json-string, optional)
Benoît Canet2e3e3312012-08-02 10:22:48 +02002485 - "backing_file_depth": number of files in the backing file chain (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002486 - "encrypted": true if encrypted, false otherwise (json-bool)
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002487 - "bps": limit total bytes per second (json-int)
2488 - "bps_rd": limit read bytes per second (json-int)
2489 - "bps_wr": limit write bytes per second (json-int)
2490 - "iops": limit total I/O operations per second (json-int)
2491 - "iops_rd": limit read operations per second (json-int)
2492 - "iops_wr": limit write operations per second (json-int)
Benoît Canet3e9fab62013-09-02 14:14:40 +02002493 - "bps_max": total max in bytes (json-int)
2494 - "bps_rd_max": read max in bytes (json-int)
2495 - "bps_wr_max": write max in bytes (json-int)
2496 - "iops_max": total I/O operations max (json-int)
2497 - "iops_rd_max": read I/O operations max (json-int)
2498 - "iops_wr_max": write I/O operations max (json-int)
Benoît Canet2024c1d2013-09-02 14:14:41 +02002499 - "iops_size": I/O size when limiting by iops (json-int)
Peter Lieven465bee12014-05-18 00:58:19 +02002500 - "detect_zeroes": detect and optimize zero writing (json-string)
2501 - Possible values: "off", "on", "unmap"
Francesco Romanie2462112015-01-12 14:11:13 +01002502 - "write_threshold": write offset threshold in bytes, a event will be
2503 emitted if crossed. Zero if disabled (json-int)
Wenchao Xia553a7e82013-06-06 12:27:59 +08002504 - "image": the detail of the image, it is a json-object containing
2505 the following:
2506 - "filename": image file name (json-string)
2507 - "format": image format (json-string)
2508 - "virtual-size": image capacity in bytes (json-int)
2509 - "dirty-flag": true if image is not cleanly closed, not present
2510 means clean (json-bool, optional)
2511 - "actual-size": actual size on disk in bytes of the image, not
2512 present when image does not support thin
2513 provision (json-int, optional)
2514 - "cluster-size": size of a cluster in bytes, not present if image
2515 format does not support it (json-int, optional)
2516 - "encrypted": true if the image is encrypted, not present means
2517 false or the image format does not support
2518 encryption (json-bool, optional)
2519 - "backing_file": backing file name, not present means no backing
2520 file is used or the image format does not
2521 support backing file chain
2522 (json-string, optional)
2523 - "full-backing-filename": full path of the backing file, not
2524 present if it equals backing_file or no
2525 backing file is used
2526 (json-string, optional)
2527 - "backing-filename-format": the format of the backing file, not
2528 present means unknown or no backing
2529 file (json-string, optional)
2530 - "snapshots": the internal snapshot info, it is an optional list
2531 of json-object containing the following:
2532 - "id": unique snapshot id (json-string)
2533 - "name": snapshot name (json-string)
2534 - "vm-state-size": size of the VM state in bytes (json-int)
2535 - "date-sec": UTC date of the snapshot in seconds (json-int)
2536 - "date-nsec": fractional part in nanoseconds to be used with
Eric Blake586b5462013-08-30 14:44:11 -06002537 date-sec (json-int)
Wenchao Xia553a7e82013-06-06 12:27:59 +08002538 - "vm-clock-sec": VM clock relative to boot in seconds
2539 (json-int)
2540 - "vm-clock-nsec": fractional part in nanoseconds to be used
2541 with vm-clock-sec (json-int)
2542 - "backing-image": the detail of the backing image, it is an
2543 optional json-object only present when a
2544 backing image present for this image
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002545
Luiz Capitulinof04ef602011-09-26 17:43:54 -03002546- "io-status": I/O operation status, only present if the device supports it
2547 and the VM is configured to stop on errors. It's always reset
2548 to "ok" when the "cont" command is issued (json_string, optional)
2549 - Possible values: "ok", "failed", "nospace"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002550
2551Example:
2552
2553-> { "execute": "query-block" }
2554<- {
2555 "return":[
2556 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03002557 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002558 "device":"ide0-hd0",
2559 "locked":false,
2560 "removable":false,
2561 "inserted":{
2562 "ro":false,
2563 "drv":"qcow2",
2564 "encrypted":false,
Wenchao Xia553a7e82013-06-06 12:27:59 +08002565 "file":"disks/test.qcow2",
2566 "backing_file_depth":1,
Zhi Yong Wu727f0052011-11-08 13:00:31 +08002567 "bps":1000000,
2568 "bps_rd":0,
2569 "bps_wr":0,
2570 "iops":1000000,
2571 "iops_rd":0,
2572 "iops_wr":0,
Benoît Canet3e9fab62013-09-02 14:14:40 +02002573 "bps_max": 8000000,
2574 "bps_rd_max": 0,
2575 "bps_wr_max": 0,
2576 "iops_max": 0,
2577 "iops_rd_max": 0,
2578 "iops_wr_max": 0,
Benoît Canet2024c1d2013-09-02 14:14:41 +02002579 "iops_size": 0,
Peter Lieven465bee12014-05-18 00:58:19 +02002580 "detect_zeroes": "on",
Francesco Romanie2462112015-01-12 14:11:13 +01002581 "write_threshold": 0,
Wenchao Xia553a7e82013-06-06 12:27:59 +08002582 "image":{
2583 "filename":"disks/test.qcow2",
2584 "format":"qcow2",
2585 "virtual-size":2048000,
2586 "backing_file":"base.qcow2",
2587 "full-backing-filename":"disks/base.qcow2",
John Snow54034322015-04-28 15:20:41 -04002588 "backing-filename-format":"qcow2",
Wenchao Xia553a7e82013-06-06 12:27:59 +08002589 "snapshots":[
2590 {
2591 "id": "1",
2592 "name": "snapshot1",
2593 "vm-state-size": 0,
2594 "date-sec": 10000200,
2595 "date-nsec": 12,
2596 "vm-clock-sec": 206,
2597 "vm-clock-nsec": 30
2598 }
2599 ],
2600 "backing-image":{
2601 "filename":"disks/base.qcow2",
2602 "format":"qcow2",
2603 "virtual-size":2048000
2604 }
2605 }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002606 },
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002607 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002608 },
2609 {
Luiz Capitulinof04ef602011-09-26 17:43:54 -03002610 "io-status": "ok",
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002611 "device":"ide1-cd0",
2612 "locked":false,
2613 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002614 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002615 },
2616 {
2617 "device":"floppy0",
2618 "locked":false,
2619 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002620 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002621 },
2622 {
2623 "device":"sd0",
2624 "locked":false,
2625 "removable":true,
Markus Armbrusterd8aeeb32011-05-16 15:04:55 +02002626 "type":"unknown"
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002627 }
2628 ]
2629 }
2630
2631EQMP
2632
Luiz Capitulinob2023812011-09-21 17:16:47 -03002633 {
2634 .name = "query-block",
2635 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002636 .mhandler.cmd_new = qmp_marshal_query_block,
Luiz Capitulinob2023812011-09-21 17:16:47 -03002637 },
2638
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002639SQMP
2640query-blockstats
2641----------------
2642
2643Show block device statistics.
2644
2645Each device statistic information is stored in a json-object and the returned
2646value is a json-array of all devices.
2647
2648Each json-object contain the following:
2649
2650- "device": device name (json-string)
2651- "stats": A json-object with the statistics information, it contains:
2652 - "rd_bytes": bytes read (json-int)
2653 - "wr_bytes": bytes written (json-int)
2654 - "rd_operations": read operations (json-int)
2655 - "wr_operations": write operations (json-int)
Christoph Hellwige8045d62011-08-22 00:25:58 +02002656 - "flush_operations": cache flush operations (json-int)
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002657 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
2658 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
2659 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
Max Reitz53d8f9d2015-10-19 17:53:20 +02002660 - "wr_highest_offset": The offset after the greatest byte written to the
2661 BlockDriverState since it has been opened (json-int)
Peter Lievenf4564d52015-02-02 14:52:18 +01002662 - "rd_merged": number of read requests that have been merged into
2663 another request (json-int)
2664 - "wr_merged": number of write requests that have been merged into
2665 another request (json-int)
Alberto Garciacb38fff2015-10-28 17:33:02 +02002666 - "idle_time_ns": time since the last I/O operation, in
2667 nanoseconds. If the field is absent it means
2668 that there haven't been any operations yet
2669 (json-int, optional)
Alberto Garcia7ee12da2015-10-28 17:33:03 +02002670 - "failed_rd_operations": number of failed read operations
2671 (json-int)
2672 - "failed_wr_operations": number of failed write operations
2673 (json-int)
2674 - "failed_flush_operations": number of failed flush operations
2675 (json-int)
2676 - "invalid_rd_operations": number of invalid read operations
2677 (json-int)
2678 - "invalid_wr_operations": number of invalid write operations
2679 (json-int)
2680 - "invalid_flush_operations": number of invalid flush operations
2681 (json-int)
Alberto Garcia362e9292015-10-28 17:33:04 +02002682 - "account_invalid": whether invalid operations are included in
2683 the last access statistics (json-bool)
2684 - "account_failed": whether failed operations are included in the
2685 latency and last access statistics
2686 (json-bool)
Alberto Garcia979e9b02015-10-28 17:33:05 +02002687 - "timed_stats": A json-array containing statistics collected in
2688 specific intervals, with the following members:
2689 - "interval_length": interval used for calculating the
2690 statistics, in seconds (json-int)
2691 - "min_rd_latency_ns": minimum latency of read operations in
2692 the defined interval, in nanoseconds
2693 (json-int)
2694 - "min_wr_latency_ns": minimum latency of write operations in
2695 the defined interval, in nanoseconds
2696 (json-int)
2697 - "min_flush_latency_ns": minimum latency of flush operations
2698 in the defined interval, in
2699 nanoseconds (json-int)
2700 - "max_rd_latency_ns": maximum latency of read operations in
2701 the defined interval, in nanoseconds
2702 (json-int)
2703 - "max_wr_latency_ns": maximum latency of write operations in
2704 the defined interval, in nanoseconds
2705 (json-int)
2706 - "max_flush_latency_ns": maximum latency of flush operations
2707 in the defined interval, in
2708 nanoseconds (json-int)
2709 - "avg_rd_latency_ns": average latency of read operations in
2710 the defined interval, in nanoseconds
2711 (json-int)
2712 - "avg_wr_latency_ns": average latency of write operations in
2713 the defined interval, in nanoseconds
2714 (json-int)
2715 - "avg_flush_latency_ns": average latency of flush operations
2716 in the defined interval, in
2717 nanoseconds (json-int)
Alberto Garcia96e4ded2015-10-28 17:33:06 +02002718 - "avg_rd_queue_depth": average number of pending read
2719 operations in the defined interval
2720 (json-number)
2721 - "avg_wr_queue_depth": average number of pending write
2722 operations in the defined interval
2723 (json-number).
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002724- "parent": Contains recursively the statistics of the underlying
2725 protocol (e.g. the host file for a qcow2 image). If there is
2726 no underlying protocol, this field is omitted
2727 (json-object, optional)
2728
2729Example:
2730
2731-> { "execute": "query-blockstats" }
2732<- {
2733 "return":[
2734 {
2735 "device":"ide0-hd0",
2736 "parent":{
2737 "stats":{
2738 "wr_highest_offset":3686448128,
2739 "wr_bytes":9786368,
2740 "wr_operations":751,
2741 "rd_bytes":122567168,
2742 "rd_operations":36772
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002743 "wr_total_times_ns":313253456
2744 "rd_total_times_ns":3465673657
2745 "flush_total_times_ns":49653
Christoph Hellwige8045d62011-08-22 00:25:58 +02002746 "flush_operations":61,
Peter Lievenf4564d52015-02-02 14:52:18 +01002747 "rd_merged":0,
Alberto Garciacb38fff2015-10-28 17:33:02 +02002748 "wr_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002749 "idle_time_ns":2953431879,
2750 "account_invalid":true,
2751 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002752 }
2753 },
2754 "stats":{
2755 "wr_highest_offset":2821110784,
2756 "wr_bytes":9786368,
2757 "wr_operations":692,
2758 "rd_bytes":122739200,
2759 "rd_operations":36604
Christoph Hellwige8045d62011-08-22 00:25:58 +02002760 "flush_operations":51,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002761 "wr_total_times_ns":313253456
2762 "rd_total_times_ns":3465673657
Peter Lievenf4564d52015-02-02 14:52:18 +01002763 "flush_total_times_ns":49653,
2764 "rd_merged":0,
Alberto Garciacb38fff2015-10-28 17:33:02 +02002765 "wr_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002766 "idle_time_ns":2953431879,
2767 "account_invalid":true,
2768 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002769 }
2770 },
2771 {
2772 "device":"ide1-cd0",
2773 "stats":{
2774 "wr_highest_offset":0,
2775 "wr_bytes":0,
2776 "wr_operations":0,
2777 "rd_bytes":0,
2778 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02002779 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002780 "wr_total_times_ns":0
2781 "rd_total_times_ns":0
Peter Lievenf4564d52015-02-02 14:52:18 +01002782 "flush_total_times_ns":0,
2783 "rd_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002784 "wr_merged":0,
2785 "account_invalid":false,
2786 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002787 }
2788 },
2789 {
2790 "device":"floppy0",
2791 "stats":{
2792 "wr_highest_offset":0,
2793 "wr_bytes":0,
2794 "wr_operations":0,
2795 "rd_bytes":0,
2796 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02002797 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002798 "wr_total_times_ns":0
2799 "rd_total_times_ns":0
Peter Lievenf4564d52015-02-02 14:52:18 +01002800 "flush_total_times_ns":0,
2801 "rd_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002802 "wr_merged":0,
2803 "account_invalid":false,
2804 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002805 }
2806 },
2807 {
2808 "device":"sd0",
2809 "stats":{
2810 "wr_highest_offset":0,
2811 "wr_bytes":0,
2812 "wr_operations":0,
2813 "rd_bytes":0,
2814 "rd_operations":0
Christoph Hellwige8045d62011-08-22 00:25:58 +02002815 "flush_operations":0,
Christoph Hellwigc488c7f2011-08-25 08:26:10 +02002816 "wr_total_times_ns":0
2817 "rd_total_times_ns":0
Peter Lievenf4564d52015-02-02 14:52:18 +01002818 "flush_total_times_ns":0,
2819 "rd_merged":0,
Alberto Garcia362e9292015-10-28 17:33:04 +02002820 "wr_merged":0,
2821 "account_invalid":false,
2822 "account_failed":false
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002823 }
2824 }
2825 ]
2826 }
2827
2828EQMP
2829
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03002830 {
2831 .name = "query-blockstats",
Fam Zhengf71eaa72014-10-31 11:32:57 +08002832 .args_type = "query-nodes:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002833 .mhandler.cmd_new = qmp_marshal_query_blockstats,
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03002834 },
2835
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002836SQMP
2837query-cpus
2838----------
2839
2840Show CPU information.
2841
2842Return a json-array. Each CPU is represented by a json-object, which contains:
2843
2844- "CPU": CPU index (json-int)
2845- "current": true if this is the current CPU, false otherwise (json-bool)
2846- "halted": true if the cpu is halted, false otherwise (json-bool)
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002847- "qom_path": path to the CPU object in the QOM tree (json-str)
Eric Blake86f4b682015-11-18 01:52:59 -07002848- "arch": architecture of the cpu, which determines what additional
2849 keys will be present (json-str)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002850- Current program counter. The key's name depends on the architecture:
2851 "pc": i386/x86_64 (json-int)
2852 "nip": PPC (json-int)
2853 "pc" and "npc": sparc (json-int)
2854 "PC": mips (json-int)
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01002855- "thread_id": ID of the underlying host thread (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002856
2857Example:
2858
2859-> { "execute": "query-cpus" }
2860<- {
2861 "return":[
2862 {
2863 "CPU":0,
2864 "current":true,
2865 "halted":false,
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002866 "qom_path":"/machine/unattached/device[0]",
Eric Blake86f4b682015-11-18 01:52:59 -07002867 "arch":"x86",
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002868 "pc":3227107138,
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01002869 "thread_id":3134
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002870 },
2871 {
2872 "CPU":1,
2873 "current":false,
2874 "halted":true,
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002875 "qom_path":"/machine/unattached/device[2]",
Eric Blake86f4b682015-11-18 01:52:59 -07002876 "arch":"x86",
Eduardo Habkost58f88d42015-05-08 16:04:22 -03002877 "pc":7108165,
Jan Kiszkadc7a09c2011-03-15 12:26:31 +01002878 "thread_id":3135
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002879 }
2880 ]
2881 }
2882
2883EQMP
2884
Luiz Capitulinode0b36b2011-09-21 16:38:35 -03002885 {
2886 .name = "query-cpus",
2887 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002888 .mhandler.cmd_new = qmp_marshal_query_cpus,
Luiz Capitulinode0b36b2011-09-21 16:38:35 -03002889 },
2890
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002891SQMP
Stefan Hajnoczidc3dd0d2014-02-27 11:48:42 +01002892query-iothreads
2893---------------
2894
2895Returns a list of information about each iothread.
2896
2897Note this list excludes the QEMU main loop thread, which is not declared
2898using the -object iothread command-line option. It is always the main thread
2899of the process.
2900
2901Return a json-array. Each iothread is represented by a json-object, which contains:
2902
2903- "id": name of iothread (json-str)
2904- "thread-id": ID of the underlying host thread (json-int)
2905
2906Example:
2907
2908-> { "execute": "query-iothreads" }
2909<- {
2910 "return":[
2911 {
2912 "id":"iothread0",
2913 "thread-id":3134
2914 },
2915 {
2916 "id":"iothread1",
2917 "thread-id":3135
2918 }
2919 ]
2920 }
2921
2922EQMP
2923
2924 {
2925 .name = "query-iothreads",
2926 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02002927 .mhandler.cmd_new = qmp_marshal_query_iothreads,
Stefan Hajnoczidc3dd0d2014-02-27 11:48:42 +01002928 },
2929
2930SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03002931query-pci
2932---------
2933
2934PCI buses and devices information.
2935
2936The returned value is a json-array of all buses. Each bus is represented by
2937a json-object, which has a key with a json-array of all PCI devices attached
2938to it. Each device is represented by a json-object.
2939
2940The bus json-object contains the following:
2941
2942- "bus": bus number (json-int)
2943- "devices": a json-array of json-objects, each json-object represents a
2944 PCI device
2945
2946The PCI device json-object contains the following:
2947
2948- "bus": identical to the parent's bus number (json-int)
2949- "slot": slot number (json-int)
2950- "function": function number (json-int)
2951- "class_info": a json-object containing:
2952 - "desc": device class description (json-string, optional)
2953 - "class": device class number (json-int)
2954- "id": a json-object containing:
2955 - "device": device ID (json-int)
2956 - "vendor": vendor ID (json-int)
2957- "irq": device's IRQ if assigned (json-int, optional)
2958- "qdev_id": qdev id string (json-string)
2959- "pci_bridge": It's a json-object, only present if this device is a
2960 PCI bridge, contains:
2961 - "bus": bus number (json-int)
2962 - "secondary": secondary bus number (json-int)
2963 - "subordinate": subordinate bus number (json-int)
2964 - "io_range": I/O memory range information, a json-object with the
2965 following members:
2966 - "base": base address, in bytes (json-int)
2967 - "limit": limit address, in bytes (json-int)
2968 - "memory_range": memory range information, a json-object with the
2969 following members:
2970 - "base": base address, in bytes (json-int)
2971 - "limit": limit address, in bytes (json-int)
2972 - "prefetchable_range": Prefetchable memory range information, a
2973 json-object with the following members:
2974 - "base": base address, in bytes (json-int)
2975 - "limit": limit address, in bytes (json-int)
2976 - "devices": a json-array of PCI devices if there's any attached, each
2977 each element is represented by a json-object, which contains
2978 the same members of the 'PCI device json-object' described
2979 above (optional)
2980- "regions": a json-array of json-objects, each json-object represents a
2981 memory region of this device
2982
2983The memory range json-object contains the following:
2984
2985- "base": base memory address (json-int)
2986- "limit": limit value (json-int)
2987
2988The region json-object can be an I/O region or a memory region, an I/O region
2989json-object contains the following:
2990
2991- "type": "io" (json-string, fixed)
2992- "bar": BAR number (json-int)
2993- "address": memory address (json-int)
2994- "size": memory size (json-int)
2995
2996A memory region json-object contains the following:
2997
2998- "type": "memory" (json-string, fixed)
2999- "bar": BAR number (json-int)
3000- "address": memory address (json-int)
3001- "size": memory size (json-int)
3002- "mem_type_64": true or false (json-bool)
3003- "prefetch": true or false (json-bool)
3004
3005Example:
3006
3007-> { "execute": "query-pci" }
3008<- {
3009 "return":[
3010 {
3011 "bus":0,
3012 "devices":[
3013 {
3014 "bus":0,
3015 "qdev_id":"",
3016 "slot":0,
3017 "class_info":{
3018 "class":1536,
3019 "desc":"Host bridge"
3020 },
3021 "id":{
3022 "device":32902,
3023 "vendor":4663
3024 },
3025 "function":0,
3026 "regions":[
3027
3028 ]
3029 },
3030 {
3031 "bus":0,
3032 "qdev_id":"",
3033 "slot":1,
3034 "class_info":{
3035 "class":1537,
3036 "desc":"ISA bridge"
3037 },
3038 "id":{
3039 "device":32902,
3040 "vendor":28672
3041 },
3042 "function":0,
3043 "regions":[
3044
3045 ]
3046 },
3047 {
3048 "bus":0,
3049 "qdev_id":"",
3050 "slot":1,
3051 "class_info":{
3052 "class":257,
3053 "desc":"IDE controller"
3054 },
3055 "id":{
3056 "device":32902,
3057 "vendor":28688
3058 },
3059 "function":1,
3060 "regions":[
3061 {
3062 "bar":4,
3063 "size":16,
3064 "address":49152,
3065 "type":"io"
3066 }
3067 ]
3068 },
3069 {
3070 "bus":0,
3071 "qdev_id":"",
3072 "slot":2,
3073 "class_info":{
3074 "class":768,
3075 "desc":"VGA controller"
3076 },
3077 "id":{
3078 "device":4115,
3079 "vendor":184
3080 },
3081 "function":0,
3082 "regions":[
3083 {
3084 "prefetch":true,
3085 "mem_type_64":false,
3086 "bar":0,
3087 "size":33554432,
3088 "address":4026531840,
3089 "type":"memory"
3090 },
3091 {
3092 "prefetch":false,
3093 "mem_type_64":false,
3094 "bar":1,
3095 "size":4096,
3096 "address":4060086272,
3097 "type":"memory"
3098 },
3099 {
3100 "prefetch":false,
3101 "mem_type_64":false,
3102 "bar":6,
3103 "size":65536,
3104 "address":-1,
3105 "type":"memory"
3106 }
3107 ]
3108 },
3109 {
3110 "bus":0,
3111 "qdev_id":"",
3112 "irq":11,
3113 "slot":4,
3114 "class_info":{
3115 "class":1280,
3116 "desc":"RAM controller"
3117 },
3118 "id":{
3119 "device":6900,
3120 "vendor":4098
3121 },
3122 "function":0,
3123 "regions":[
3124 {
3125 "bar":0,
3126 "size":32,
3127 "address":49280,
3128 "type":"io"
3129 }
3130 ]
3131 }
3132 ]
3133 }
3134 ]
3135 }
3136
3137Note: This example has been shortened as the real response is too long.
3138
3139EQMP
3140
Luiz Capitulino79627472011-10-21 14:15:33 -02003141 {
3142 .name = "query-pci",
3143 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003144 .mhandler.cmd_new = qmp_marshal_query_pci,
Luiz Capitulino79627472011-10-21 14:15:33 -02003145 },
3146
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003147SQMP
3148query-kvm
3149---------
3150
3151Show KVM information.
3152
3153Return a json-object with the following information:
3154
3155- "enabled": true if KVM support is enabled, false otherwise (json-bool)
3156- "present": true if QEMU has KVM support, false otherwise (json-bool)
3157
3158Example:
3159
3160-> { "execute": "query-kvm" }
3161<- { "return": { "enabled": true, "present": true } }
3162
3163EQMP
3164
Luiz Capitulino292a2602011-09-12 15:10:53 -03003165 {
3166 .name = "query-kvm",
3167 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003168 .mhandler.cmd_new = qmp_marshal_query_kvm,
Luiz Capitulino292a2602011-09-12 15:10:53 -03003169 },
3170
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003171SQMP
3172query-status
3173------------
3174
3175Return a json-object with the following information:
3176
3177- "running": true if the VM is running, or false if it is paused (json-bool)
3178- "singlestep": true if the VM is in single step mode,
3179 false otherwise (json-bool)
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03003180- "status": one of the following values (json-string)
3181 "debug" - QEMU is running on a debugger
3182 "inmigrate" - guest is paused waiting for an incoming migration
3183 "internal-error" - An internal error that prevents further guest
3184 execution has occurred
3185 "io-error" - the last IOP has failed and the device is configured
3186 to pause on I/O errors
3187 "paused" - guest has been paused via the 'stop' command
3188 "postmigrate" - guest is paused following a successful 'migrate'
3189 "prelaunch" - QEMU was started with -S and guest has not started
3190 "finish-migrate" - guest is paused to finish the migration process
3191 "restore-vm" - guest is paused to restore VM state
3192 "running" - guest is actively running
3193 "save-vm" - guest is paused to save the VM state
3194 "shutdown" - guest is shut down (and -no-shutdown is in use)
3195 "watchdog" - the watchdog action is configured to pause and
3196 has been triggered
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003197
3198Example:
3199
3200-> { "execute": "query-status" }
Luiz Capitulino9e37b9d2011-08-29 16:02:57 -03003201<- { "return": { "running": true, "singlestep": false, "status": "running" } }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003202
3203EQMP
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -03003204
3205 {
3206 .name = "query-status",
3207 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003208 .mhandler.cmd_new = qmp_marshal_query_status,
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -03003209 },
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003210
3211SQMP
3212query-mice
3213----------
3214
3215Show VM mice information.
3216
3217Each mouse is represented by a json-object, the returned value is a json-array
3218of all mice.
3219
3220The mouse json-object contains the following:
3221
3222- "name": mouse's name (json-string)
3223- "index": mouse's index (json-int)
3224- "current": true if this mouse is receiving events, false otherwise (json-bool)
3225- "absolute": true if the mouse generates absolute input events (json-bool)
3226
3227Example:
3228
3229-> { "execute": "query-mice" }
3230<- {
3231 "return":[
3232 {
3233 "name":"QEMU Microsoft Mouse",
3234 "index":0,
3235 "current":false,
3236 "absolute":false
3237 },
3238 {
3239 "name":"QEMU PS/2 Mouse",
3240 "index":1,
3241 "current":true,
3242 "absolute":true
3243 }
3244 ]
3245 }
3246
3247EQMP
3248
Luiz Capitulinoe235cec2011-09-21 15:29:55 -03003249 {
3250 .name = "query-mice",
3251 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003252 .mhandler.cmd_new = qmp_marshal_query_mice,
Luiz Capitulinoe235cec2011-09-21 15:29:55 -03003253 },
3254
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003255SQMP
3256query-vnc
3257---------
3258
3259Show VNC server information.
3260
3261Return a json-object with server information. Connected clients are returned
3262as a json-array of json-objects.
3263
3264The main json-object contains the following:
3265
3266- "enabled": true or false (json-bool)
3267- "host": server's IP address (json-string)
3268- "family": address family (json-string)
3269 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3270- "service": server's port number (json-string)
3271- "auth": authentication method (json-string)
3272 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
3273 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
3274 "vencrypt+plain", "vencrypt+tls+none",
3275 "vencrypt+tls+plain", "vencrypt+tls+sasl",
3276 "vencrypt+tls+vnc", "vencrypt+x509+none",
3277 "vencrypt+x509+plain", "vencrypt+x509+sasl",
3278 "vencrypt+x509+vnc", "vnc"
3279- "clients": a json-array of all connected clients
3280
3281Clients are described by a json-object, each one contain the following:
3282
3283- "host": client's IP address (json-string)
3284- "family": address family (json-string)
3285 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3286- "service": client's port number (json-string)
3287- "x509_dname": TLS dname (json-string, optional)
3288- "sasl_username": SASL username (json-string, optional)
3289
3290Example:
3291
3292-> { "execute": "query-vnc" }
3293<- {
3294 "return":{
3295 "enabled":true,
3296 "host":"0.0.0.0",
3297 "service":"50402",
3298 "auth":"vnc",
3299 "family":"ipv4",
3300 "clients":[
3301 {
3302 "host":"127.0.0.1",
3303 "service":"50401",
3304 "family":"ipv4"
3305 }
3306 ]
3307 }
3308 }
3309
3310EQMP
3311
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02003312 {
3313 .name = "query-vnc",
3314 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003315 .mhandler.cmd_new = qmp_marshal_query_vnc,
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02003316 },
Gerd Hoffmanndf887682014-12-17 15:49:44 +01003317 {
3318 .name = "query-vnc-servers",
3319 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003320 .mhandler.cmd_new = qmp_marshal_query_vnc_servers,
Gerd Hoffmanndf887682014-12-17 15:49:44 +01003321 },
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02003322
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003323SQMP
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01003324query-spice
3325-----------
3326
3327Show SPICE server information.
3328
3329Return a json-object with server information. Connected clients are returned
3330as a json-array of json-objects.
3331
3332The main json-object contains the following:
3333
3334- "enabled": true or false (json-bool)
3335- "host": server's IP address (json-string)
3336- "port": server's port number (json-int, optional)
3337- "tls-port": server's port number (json-int, optional)
3338- "auth": authentication method (json-string)
3339 - Possible values: "none", "spice"
3340- "channels": a json-array of all active channels clients
3341
3342Channels are described by a json-object, each one contain the following:
3343
3344- "host": client's IP address (json-string)
3345- "family": address family (json-string)
3346 - Possible values: "ipv4", "ipv6", "unix", "unknown"
3347- "port": client's port number (json-string)
3348- "connection-id": spice connection id. All channels with the same id
3349 belong to the same spice session (json-int)
3350- "channel-type": channel type. "1" is the main control channel, filter for
3351 this one if you want track spice sessions only (json-int)
3352- "channel-id": channel id. Usually "0", might be different needed when
3353 multiple channels of the same type exist, such as multiple
3354 display channels in a multihead setup (json-int)
Alberto Garcia3599d462015-02-26 16:35:07 +02003355- "tls": whether the channel is encrypted (json-bool)
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01003356
3357Example:
3358
3359-> { "execute": "query-spice" }
3360<- {
3361 "return": {
3362 "enabled": true,
3363 "auth": "spice",
3364 "port": 5920,
3365 "tls-port": 5921,
3366 "host": "0.0.0.0",
3367 "channels": [
3368 {
3369 "port": "54924",
3370 "family": "ipv4",
3371 "channel-type": 1,
3372 "connection-id": 1804289383,
3373 "host": "127.0.0.1",
3374 "channel-id": 0,
3375 "tls": true
3376 },
3377 {
3378 "port": "36710",
3379 "family": "ipv4",
3380 "channel-type": 4,
3381 "connection-id": 1804289383,
3382 "host": "127.0.0.1",
3383 "channel-id": 0,
3384 "tls": false
3385 },
3386 [ ... more channels follow ... ]
3387 ]
3388 }
3389 }
3390
3391EQMP
3392
Luiz Capitulinod1f29642011-10-20 17:01:33 -02003393#if defined(CONFIG_SPICE)
3394 {
3395 .name = "query-spice",
3396 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003397 .mhandler.cmd_new = qmp_marshal_query_spice,
Luiz Capitulinod1f29642011-10-20 17:01:33 -02003398 },
3399#endif
3400
Gerd Hoffmanncb42a872010-11-30 11:02:51 +01003401SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003402query-name
3403----------
3404
3405Show VM name.
3406
3407Return a json-object with the following information:
3408
3409- "name": VM's name (json-string, optional)
3410
3411Example:
3412
3413-> { "execute": "query-name" }
3414<- { "return": { "name": "qemu-name" } }
3415
3416EQMP
3417
Anthony Liguori48a32be2011-09-02 12:34:48 -05003418 {
3419 .name = "query-name",
3420 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003421 .mhandler.cmd_new = qmp_marshal_query_name,
Anthony Liguori48a32be2011-09-02 12:34:48 -05003422 },
3423
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003424SQMP
3425query-uuid
3426----------
3427
3428Show VM UUID.
3429
3430Return a json-object with the following information:
3431
3432- "UUID": Universally Unique Identifier (json-string)
3433
3434Example:
3435
3436-> { "execute": "query-uuid" }
3437<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
3438
3439EQMP
3440
Luiz Capitulinoefab7672011-09-13 17:16:25 -03003441 {
3442 .name = "query-uuid",
3443 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003444 .mhandler.cmd_new = qmp_marshal_query_uuid,
Luiz Capitulinoefab7672011-09-13 17:16:25 -03003445 },
3446
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003447SQMP
Amos Kong1f8f9872013-04-25 17:50:35 +08003448query-command-line-options
3449--------------------------
3450
3451Show command line option schema.
3452
3453Return a json-array of command line option schema for all options (or for
3454the given option), returning an error if the given option doesn't exist.
3455
3456Each array entry contains the following:
3457
3458- "option": option name (json-string)
3459- "parameters": a json-array describes all parameters of the option:
3460 - "name": parameter name (json-string)
3461 - "type": parameter type (one of 'string', 'boolean', 'number',
3462 or 'size')
3463 - "help": human readable description of the parameter
3464 (json-string, optional)
Chunyan Liue36af942014-06-05 17:20:43 +08003465 - "default": default value string for the parameter
3466 (json-string, optional)
Amos Kong1f8f9872013-04-25 17:50:35 +08003467
3468Example:
3469
3470-> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
3471<- { "return": [
3472 {
3473 "parameters": [
3474 {
3475 "name": "romfile",
3476 "type": "string"
3477 },
3478 {
3479 "name": "bootindex",
3480 "type": "number"
3481 }
3482 ],
3483 "option": "option-rom"
3484 }
3485 ]
3486 }
3487
3488EQMP
3489
3490 {
3491 .name = "query-command-line-options",
3492 .args_type = "option:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003493 .mhandler.cmd_new = qmp_marshal_query_command_line_options,
Amos Kong1f8f9872013-04-25 17:50:35 +08003494 },
3495
3496SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003497query-migrate
3498-------------
3499
3500Migration status.
3501
3502Return a json-object. If migration is active there will be another json-object
3503with RAM migration status and if block migration is active another one with
3504block migration status.
3505
3506The main json-object contains the following:
3507
3508- "status": migration status (json-string)
Peter Feiner3b695952014-05-16 10:40:47 -04003509 - Possible values: "setup", "active", "completed", "failed", "cancelled"
Juan Quintela7aa939a2012-08-18 13:17:10 +02003510- "total-time": total amount of ms since migration started. If
3511 migration has ended, it returns the total migration
Juan Quintela817c6042013-02-11 15:11:10 +01003512 time (json-int)
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003513- "setup-time" amount of setup time in milliseconds _before_ the
3514 iterations begin but _after_ the QMP command is issued.
3515 This is designed to provide an accounting of any activities
3516 (such as RDMA pinning) which may be expensive, but do not
3517 actually occur during the iterative migration rounds
3518 themselves. (json-int)
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02003519- "downtime": only present when migration has finished correctly
3520 total amount in ms for downtime that happened (json-int)
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003521- "expected-downtime": only present while migration is active
3522 total amount in ms for downtime that was calculated on
Juan Quintela817c6042013-02-11 15:11:10 +01003523 the last bitmap round (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003524- "ram": only present if "status" is "active", it is a json-object with the
Juan Quintela817c6042013-02-11 15:11:10 +01003525 following RAM information:
3526 - "transferred": amount transferred in bytes (json-int)
3527 - "remaining": amount remaining to transfer in bytes (json-int)
3528 - "total": total amount of memory in bytes (json-int)
3529 - "duplicate": number of pages filled entirely with the same
3530 byte (json-int)
3531 These are sent over the wire much more efficiently.
Peter Lievenf1c72792013-03-26 10:58:37 +01003532 - "skipped": number of skipped zero pages (json-int)
Stefan Weil805a2502013-04-28 11:49:57 +02003533 - "normal" : number of whole pages transferred. I.e. they
Juan Quintela817c6042013-02-11 15:11:10 +01003534 were not sent as duplicate or xbzrle pages (json-int)
3535 - "normal-bytes" : number of bytes transferred in whole
3536 pages. This is just normal pages times size of one page,
3537 but this way upper levels don't need to care about page
3538 size (json-int)
ChenLiang58570ed2014-04-04 17:57:55 +08003539 - "dirty-sync-count": times that dirty ram was synchronized (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003540- "disk": only present if "status" is "active" and it is a block migration,
Juan Quintela817c6042013-02-11 15:11:10 +01003541 it is a json-object with the following disk information:
3542 - "transferred": amount transferred in bytes (json-int)
3543 - "remaining": amount remaining to transfer in bytes json-int)
3544 - "total": total disk size in bytes (json-int)
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003545- "xbzrle-cache": only present if XBZRLE is active.
3546 It is a json-object with the following XBZRLE information:
Juan Quintela817c6042013-02-11 15:11:10 +01003547 - "cache-size": XBZRLE cache size in bytes
3548 - "bytes": number of bytes transferred for XBZRLE compressed pages
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003549 - "pages": number of XBZRLE compressed pages
Juan Quintela817c6042013-02-11 15:11:10 +01003550 - "cache-miss": number of XBRZRLE page cache misses
ChenLiang8bc39232014-04-04 17:57:56 +08003551 - "cache-miss-rate": rate of XBRZRLE page cache misses
Juan Quintela817c6042013-02-11 15:11:10 +01003552 - "overflow": number of times XBZRLE overflows. This means
3553 that the XBZRLE encoding was bigger than just sent the
3554 whole page, and then we sent the whole page instead (as as
3555 normal page).
3556
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003557Examples:
3558
35591. Before the first migration
3560
3561-> { "execute": "query-migrate" }
3562<- { "return": {} }
3563
35642. Migration is done and has succeeded
3565
3566-> { "execute": "query-migrate" }
Orit Wasserman004d4c12012-08-06 21:42:56 +03003567<- { "return": {
3568 "status": "completed",
3569 "ram":{
3570 "transferred":123,
3571 "remaining":123,
3572 "total":246,
3573 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003574 "setup-time":12345,
Juan Quintela9c5a9fc2012-08-13 09:35:16 +02003575 "downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003576 "duplicate":123,
3577 "normal":123,
ChenLiang58570ed2014-04-04 17:57:55 +08003578 "normal-bytes":123456,
3579 "dirty-sync-count":15
Orit Wasserman004d4c12012-08-06 21:42:56 +03003580 }
3581 }
3582 }
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003583
35843. Migration is done and has failed
3585
3586-> { "execute": "query-migrate" }
3587<- { "return": { "status": "failed" } }
3588
35894. Migration is being performed and is not a block migration:
3590
3591-> { "execute": "query-migrate" }
3592<- {
3593 "return":{
3594 "status":"active",
3595 "ram":{
3596 "transferred":123,
3597 "remaining":123,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03003598 "total":246,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003599 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003600 "setup-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003601 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003602 "duplicate":123,
3603 "normal":123,
ChenLiang58570ed2014-04-04 17:57:55 +08003604 "normal-bytes":123456,
3605 "dirty-sync-count":15
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003606 }
3607 }
3608 }
3609
36105. Migration is being performed and is a block migration:
3611
3612-> { "execute": "query-migrate" }
3613<- {
3614 "return":{
3615 "status":"active",
3616 "ram":{
3617 "total":1057024,
3618 "remaining":1053304,
Orit Wasserman62d4e3f2012-08-06 21:42:55 +03003619 "transferred":3720,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003620 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003621 "setup-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003622 "expected-downtime":12345,
Orit Wasserman004d4c12012-08-06 21:42:56 +03003623 "duplicate":123,
3624 "normal":123,
ChenLiang58570ed2014-04-04 17:57:55 +08003625 "normal-bytes":123456,
3626 "dirty-sync-count":15
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003627 },
3628 "disk":{
3629 "total":20971520,
3630 "remaining":20880384,
3631 "transferred":91136
3632 }
3633 }
3634 }
3635
Orit Wassermanf36d55a2012-08-06 21:42:57 +030036366. Migration is being performed and XBZRLE is active:
3637
3638-> { "execute": "query-migrate" }
3639<- {
3640 "return":{
3641 "status":"active",
3642 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
3643 "ram":{
3644 "total":1057024,
3645 "remaining":1053304,
3646 "transferred":3720,
3647 "total-time":12345,
Michael R. Hines8f3067b2013-08-09 16:05:45 -04003648 "setup-time":12345,
Juan Quintela2c52ddf2012-08-13 09:53:12 +02003649 "expected-downtime":12345,
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003650 "duplicate":10,
3651 "normal":3333,
ChenLiang58570ed2014-04-04 17:57:55 +08003652 "normal-bytes":3412992,
3653 "dirty-sync-count":15
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003654 },
3655 "xbzrle-cache":{
3656 "cache-size":67108864,
3657 "bytes":20971520,
3658 "pages":2444343,
3659 "cache-miss":2244,
ChenLiang8bc39232014-04-04 17:57:56 +08003660 "cache-miss-rate":0.123,
Orit Wassermanf36d55a2012-08-06 21:42:57 +03003661 "overflow":34434
3662 }
3663 }
3664 }
3665
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003666EQMP
3667
Luiz Capitulino791e7c82011-09-13 17:37:16 -03003668 {
3669 .name = "query-migrate",
3670 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003671 .mhandler.cmd_new = qmp_marshal_query_migrate,
Luiz Capitulino791e7c82011-09-13 17:37:16 -03003672 },
3673
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003674SQMP
Orit Wasserman00458432012-08-06 21:42:48 +03003675migrate-set-capabilities
Juan Quintela817c6042013-02-11 15:11:10 +01003676------------------------
Orit Wasserman00458432012-08-06 21:42:48 +03003677
3678Enable/Disable migration capabilities
3679
Juan Quintela817c6042013-02-11 15:11:10 +01003680- "xbzrle": XBZRLE support
zhanghailiangd6d69732014-12-09 14:38:37 +08003681- "rdma-pin-all": pin all pages when using RDMA during migration
3682- "auto-converge": throttle down guest to help convergence of migration
3683- "zero-blocks": compress zero blocks during block migration
zhanghailiang164f59e2016-01-15 11:37:46 +08003684- "compress": use multiple compression threads to accelerate live migration
Juan Quintela72e72e12015-07-08 14:13:10 +02003685- "events": generate events for each migration state change
Dr. David Alan Gilbert32c3db52016-03-11 09:53:36 +00003686- "postcopy-ram": postcopy mode for live migration
Orit Wasserman00458432012-08-06 21:42:48 +03003687
3688Arguments:
3689
3690Example:
3691
3692-> { "execute": "migrate-set-capabilities" , "arguments":
3693 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
3694
3695EQMP
3696
3697 {
3698 .name = "migrate-set-capabilities",
Paolo Bonzini43d0a2c2015-04-15 13:30:04 +02003699 .args_type = "capabilities:q",
Orit Wasserman00458432012-08-06 21:42:48 +03003700 .params = "capability:s,state:b",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003701 .mhandler.cmd_new = qmp_marshal_migrate_set_capabilities,
Orit Wasserman00458432012-08-06 21:42:48 +03003702 },
3703SQMP
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003704query-migrate-capabilities
Juan Quintela817c6042013-02-11 15:11:10 +01003705--------------------------
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003706
3707Query current migration capabilities
3708
3709- "capabilities": migration capabilities state
3710 - "xbzrle" : XBZRLE state (json-bool)
zhanghailiangd6d69732014-12-09 14:38:37 +08003711 - "rdma-pin-all" : RDMA Pin Page state (json-bool)
3712 - "auto-converge" : Auto Converge state (json-bool)
3713 - "zero-blocks" : Zero Blocks state (json-bool)
zhanghailiang164f59e2016-01-15 11:37:46 +08003714 - "compress": Multiple compression threads state (json-bool)
3715 - "events": Migration state change event state (json-bool)
Dr. David Alan Gilbert32c3db52016-03-11 09:53:36 +00003716 - "postcopy-ram": postcopy ram state (json-bool)
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003717
3718Arguments:
3719
3720Example:
3721
3722-> { "execute": "query-migrate-capabilities" }
zhanghailiang164f59e2016-01-15 11:37:46 +08003723<- {"return": [
3724 {"state": false, "capability": "xbzrle"},
3725 {"state": false, "capability": "rdma-pin-all"},
3726 {"state": false, "capability": "auto-converge"},
3727 {"state": false, "capability": "zero-blocks"},
3728 {"state": false, "capability": "compress"},
3729 {"state": true, "capability": "events"},
Dr. David Alan Gilbert32c3db52016-03-11 09:53:36 +00003730 {"state": false, "capability": "postcopy-ram"}
zhanghailiang164f59e2016-01-15 11:37:46 +08003731 ]}
Orit Wassermandbca1b32013-01-31 09:12:17 +02003732
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003733EQMP
3734
3735 {
3736 .name = "query-migrate-capabilities",
3737 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003738 .mhandler.cmd_new = qmp_marshal_query_migrate_capabilities,
Orit Wassermanbbf6da32012-08-06 21:42:47 +03003739 },
3740
3741SQMP
Liang Li85de8322015-03-23 16:32:28 +08003742migrate-set-parameters
3743----------------------
3744
3745Set migration parameters
3746
3747- "compress-level": set compression level during migration (json-int)
3748- "compress-threads": set compression thread count for migration (json-int)
3749- "decompress-threads": set decompression thread count for migration (json-int)
zhanghailiang9c994a92016-01-15 11:37:45 +08003750- "x-cpu-throttle-initial": set initial percentage of time guest cpus are
3751 throttled for auto-converge (json-int)
3752- "x-cpu-throttle-increment": set throttle increasing percentage for
3753 auto-converge (json-int)
Liang Li85de8322015-03-23 16:32:28 +08003754
3755Arguments:
3756
3757Example:
3758
3759-> { "execute": "migrate-set-parameters" , "arguments":
3760 { "compress-level": 1 } }
3761
3762EQMP
3763
3764 {
3765 .name = "migrate-set-parameters",
3766 .args_type =
zhanghailiang9c994a92016-01-15 11:37:45 +08003767 "compress-level:i?,compress-threads:i?,decompress-threads:i?,x-cpu-throttle-initial:i?,x-cpu-throttle-increment:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003768 .mhandler.cmd_new = qmp_marshal_migrate_set_parameters,
Liang Li85de8322015-03-23 16:32:28 +08003769 },
3770SQMP
3771query-migrate-parameters
3772------------------------
3773
3774Query current migration parameters
3775
3776- "parameters": migration parameters value
3777 - "compress-level" : compression level value (json-int)
3778 - "compress-threads" : compression thread count value (json-int)
3779 - "decompress-threads" : decompression thread count value (json-int)
zhanghailiang9c994a92016-01-15 11:37:45 +08003780 - "x-cpu-throttle-initial" : initial percentage of time guest cpus are
3781 throttled (json-int)
3782 - "x-cpu-throttle-increment" : throttle increasing percentage for
3783 auto-converge (json-int)
Liang Li85de8322015-03-23 16:32:28 +08003784
3785Arguments:
3786
3787Example:
3788
3789-> { "execute": "query-migrate-parameters" }
3790<- {
3791 "return": {
zhanghailiang9c994a92016-01-15 11:37:45 +08003792 "decompress-threads": 2,
3793 "x-cpu-throttle-increment": 10,
3794 "compress-threads": 8,
3795 "compress-level": 1,
3796 "x-cpu-throttle-initial": 20
Liang Li85de8322015-03-23 16:32:28 +08003797 }
3798 }
3799
3800EQMP
3801
3802 {
3803 .name = "query-migrate-parameters",
3804 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003805 .mhandler.cmd_new = qmp_marshal_query_migrate_parameters,
Liang Li85de8322015-03-23 16:32:28 +08003806 },
3807
3808SQMP
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003809query-balloon
3810-------------
3811
3812Show balloon information.
3813
3814Make an asynchronous request for balloon info. When the request completes a
3815json-object will be returned containing the following data:
3816
3817- "actual": current balloon value in bytes (json-int)
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003818
3819Example:
3820
3821-> { "execute": "query-balloon" }
3822<- {
3823 "return":{
3824 "actual":1073741824,
Luiz Capitulino82a56f02010-09-13 12:26:00 -03003825 }
3826 }
3827
3828EQMP
3829
Luiz Capitulino96637bc2011-10-21 11:41:37 -02003830 {
3831 .name = "query-balloon",
3832 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003833 .mhandler.cmd_new = qmp_marshal_query_balloon,
Luiz Capitulino96637bc2011-10-21 11:41:37 -02003834 },
Anthony Liguorib4b12c62011-12-12 14:29:34 -06003835
3836 {
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00003837 .name = "query-block-jobs",
3838 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003839 .mhandler.cmd_new = qmp_marshal_query_block_jobs,
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00003840 },
3841
3842 {
Anthony Liguorib4b12c62011-12-12 14:29:34 -06003843 .name = "qom-list",
3844 .args_type = "path:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003845 .mhandler.cmd_new = qmp_marshal_qom_list,
Anthony Liguorib4b12c62011-12-12 14:29:34 -06003846 },
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06003847
3848 {
3849 .name = "qom-set",
Paolo Bonzinib9f89782012-03-22 12:51:11 +01003850 .args_type = "path:s,property:s,value:q",
Markus Armbruster6eb39372015-09-16 13:06:25 +02003851 .mhandler.cmd_new = qmp_marshal_qom_set,
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06003852 },
3853
3854 {
3855 .name = "qom-get",
3856 .args_type = "path:s,property:s",
Markus Armbruster6eb39372015-09-16 13:06:25 +02003857 .mhandler.cmd_new = qmp_marshal_qom_get,
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06003858 },
Luiz Capitulino270b2432011-12-08 11:45:55 -02003859
3860 {
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003861 .name = "nbd-server-start",
Daniel P. Berrangeddffee32016-02-10 18:41:14 +00003862 .args_type = "addr:q,tls-creds:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003863 .mhandler.cmd_new = qmp_marshal_nbd_server_start,
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003864 },
3865 {
3866 .name = "nbd-server-add",
3867 .args_type = "device:B,writable:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003868 .mhandler.cmd_new = qmp_marshal_nbd_server_add,
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003869 },
3870 {
3871 .name = "nbd-server-stop",
3872 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003873 .mhandler.cmd_new = qmp_marshal_nbd_server_stop,
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003874 },
3875
3876 {
Luiz Capitulino270b2432011-12-08 11:45:55 -02003877 .name = "change-vnc-password",
3878 .args_type = "password:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003879 .mhandler.cmd_new = qmp_marshal_change_vnc_password,
Luiz Capitulino270b2432011-12-08 11:45:55 -02003880 },
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06003881 {
3882 .name = "qom-list-types",
3883 .args_type = "implements:s?,abstract:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003884 .mhandler.cmd_new = qmp_marshal_qom_list_types,
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06003885 },
Anthony Liguori1daa31b2012-08-10 11:04:09 -05003886
3887 {
3888 .name = "device-list-properties",
3889 .args_type = "typename:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003890 .mhandler.cmd_new = qmp_marshal_device_list_properties,
Anthony Liguori1daa31b2012-08-10 11:04:09 -05003891 },
3892
Anthony Liguori01d3c802012-08-10 11:04:11 -05003893 {
3894 .name = "query-machines",
3895 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003896 .mhandler.cmd_new = qmp_marshal_query_machines,
Anthony Liguori01d3c802012-08-10 11:04:11 -05003897 },
3898
Anthony Liguorie4e31c62012-08-10 11:04:13 -05003899 {
3900 .name = "query-cpu-definitions",
3901 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003902 .mhandler.cmd_new = qmp_marshal_query_cpu_definitions,
Anthony Liguorie4e31c62012-08-10 11:04:13 -05003903 },
3904
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003905 {
3906 .name = "query-target",
3907 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003908 .mhandler.cmd_new = qmp_marshal_query_target,
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003909 },
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003910
3911 {
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003912 .name = "query-tpm",
3913 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003914 .mhandler.cmd_new = qmp_marshal_query_tpm,
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003915 },
3916
Corey Bryant28c4fa32013-03-20 12:34:49 -04003917SQMP
3918query-tpm
3919---------
3920
3921Return information about the TPM device.
3922
3923Arguments: None
3924
3925Example:
3926
3927-> { "execute": "query-tpm" }
3928<- { "return":
3929 [
3930 { "model": "tpm-tis",
3931 "options":
3932 { "type": "passthrough",
3933 "data":
3934 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
3935 "path": "/dev/tpm0"
3936 }
3937 },
3938 "id": "tpm0"
3939 }
3940 ]
3941 }
3942
3943EQMP
3944
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003945 {
3946 .name = "query-tpm-models",
3947 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003948 .mhandler.cmd_new = qmp_marshal_query_tpm_models,
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003949 },
3950
Corey Bryant28c4fa32013-03-20 12:34:49 -04003951SQMP
3952query-tpm-models
3953----------------
3954
3955Return a list of supported TPM models.
3956
3957Arguments: None
3958
3959Example:
3960
3961-> { "execute": "query-tpm-models" }
3962<- { "return": [ "tpm-tis" ] }
3963
3964EQMP
3965
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003966 {
3967 .name = "query-tpm-types",
3968 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003969 .mhandler.cmd_new = qmp_marshal_query_tpm_types,
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003970 },
3971
Corey Bryant28c4fa32013-03-20 12:34:49 -04003972SQMP
3973query-tpm-types
3974---------------
3975
3976Return a list of supported TPM types.
3977
3978Arguments: None
3979
3980Example:
3981
3982-> { "execute": "query-tpm-types" }
3983<- { "return": [ "passthrough" ] }
3984
3985EQMP
3986
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003987 {
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003988 .name = "chardev-add",
3989 .args_type = "id:s,backend:q",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02003990 .mhandler.cmd_new = qmp_marshal_chardev_add,
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003991 },
3992
3993SQMP
3994chardev-add
3995----------------
3996
3997Add a chardev.
3998
3999Arguments:
4000
4001- "id": the chardev's ID, must be unique (json-string)
4002- "backend": chardev backend type + parameters
4003
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01004004Examples:
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01004005
4006-> { "execute" : "chardev-add",
4007 "arguments" : { "id" : "foo",
4008 "backend" : { "type" : "null", "data" : {} } } }
4009<- { "return": {} }
4010
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01004011-> { "execute" : "chardev-add",
4012 "arguments" : { "id" : "bar",
4013 "backend" : { "type" : "file",
4014 "data" : { "out" : "/tmp/bar.log" } } } }
4015<- { "return": {} }
4016
Gerd Hoffmann0a1a7fa2012-12-20 14:39:13 +01004017-> { "execute" : "chardev-add",
4018 "arguments" : { "id" : "baz",
4019 "backend" : { "type" : "pty", "data" : {} } } }
4020<- { "return": { "pty" : "/dev/pty/42" } }
4021
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01004022EQMP
4023
4024 {
4025 .name = "chardev-remove",
4026 .args_type = "id:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004027 .mhandler.cmd_new = qmp_marshal_chardev_remove,
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01004028 },
4029
4030
4031SQMP
4032chardev-remove
4033--------------
4034
4035Remove a chardev.
4036
4037Arguments:
4038
4039- "id": the chardev's ID, must exist and not be in use (json-string)
4040
4041Example:
4042
4043-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
4044<- { "return": {} }
4045
4046EQMP
Amos Kongb1be4282013-06-14 15:45:52 +08004047 {
4048 .name = "query-rx-filter",
4049 .args_type = "name:s?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004050 .mhandler.cmd_new = qmp_marshal_query_rx_filter,
Amos Kongb1be4282013-06-14 15:45:52 +08004051 },
4052
4053SQMP
4054query-rx-filter
4055---------------
4056
4057Show rx-filter information.
4058
4059Returns a json-array of rx-filter information for all NICs (or for the
4060given NIC), returning an error if the given NIC doesn't exist, or
4061given NIC doesn't support rx-filter querying, or given net client
4062isn't a NIC.
4063
4064The query will clear the event notification flag of each NIC, then qemu
4065will start to emit event to QMP monitor.
4066
4067Each array entry contains the following:
4068
4069- "name": net client name (json-string)
4070- "promiscuous": promiscuous mode is enabled (json-bool)
4071- "multicast": multicast receive state (one of 'normal', 'none', 'all')
4072- "unicast": unicast receive state (one of 'normal', 'none', 'all')
Amos Kongf7bc8ef2014-03-26 08:19:43 +08004073- "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
Amos Kongb1be4282013-06-14 15:45:52 +08004074- "broadcast-allowed": allow to receive broadcast (json-bool)
4075- "multicast-overflow": multicast table is overflowed (json-bool)
4076- "unicast-overflow": unicast table is overflowed (json-bool)
4077- "main-mac": main macaddr string (json-string)
4078- "vlan-table": a json-array of active vlan id
4079- "unicast-table": a json-array of unicast macaddr string
4080- "multicast-table": a json-array of multicast macaddr string
4081
4082Example:
4083
4084-> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
4085<- { "return": [
4086 {
4087 "promiscuous": true,
4088 "name": "vnet0",
4089 "main-mac": "52:54:00:12:34:56",
4090 "unicast": "normal",
Amos Kongf7bc8ef2014-03-26 08:19:43 +08004091 "vlan": "normal",
Amos Kongb1be4282013-06-14 15:45:52 +08004092 "vlan-table": [
4093 4,
4094 0
4095 ],
4096 "unicast-table": [
4097 ],
4098 "multicast": "normal",
4099 "multicast-overflow": false,
4100 "unicast-overflow": false,
4101 "multicast-table": [
4102 "01:00:5e:00:00:01",
4103 "33:33:00:00:00:01",
4104 "33:33:ff:12:34:56"
4105 ],
4106 "broadcast-allowed": false
4107 }
4108 ]
4109 }
4110
4111EQMP
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004112
4113 {
4114 .name = "blockdev-add",
4115 .args_type = "options:q",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004116 .mhandler.cmd_new = qmp_marshal_blockdev_add,
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004117 },
4118
4119SQMP
4120blockdev-add
4121------------
4122
4123Add a block device.
4124
Markus Armbrusterda2cf4e2015-03-20 14:32:17 +01004125This command is still a work in progress. It doesn't support all
Alberto Garcia81b936a2015-11-02 16:51:55 +02004126block drivers among other things. Stay away from it unless you want
4127to help with its development.
Markus Armbrusterda2cf4e2015-03-20 14:32:17 +01004128
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004129Arguments:
4130
4131- "options": block driver options
4132
4133Example (1):
4134
4135-> { "execute": "blockdev-add",
4136 "arguments": { "options" : { "driver": "qcow2",
4137 "file": { "driver": "file",
4138 "filename": "test.qcow2" } } } }
4139<- { "return": {} }
4140
4141Example (2):
4142
4143-> { "execute": "blockdev-add",
4144 "arguments": {
4145 "options": {
4146 "driver": "qcow2",
4147 "id": "my_disk",
4148 "discard": "unmap",
4149 "cache": {
4150 "direct": true,
4151 "writeback": true
4152 },
4153 "file": {
4154 "driver": "file",
4155 "filename": "/tmp/test.qcow2"
4156 },
4157 "backing": {
4158 "driver": "raw",
4159 "file": {
4160 "driver": "file",
4161 "filename": "/dev/fdset/4"
4162 }
4163 }
4164 }
4165 }
4166 }
4167
4168<- { "return": {} }
4169
4170EQMP
Benoît Canetc13163f2014-01-23 21:31:34 +01004171
4172 {
Alberto Garcia81b936a2015-11-02 16:51:55 +02004173 .name = "x-blockdev-del",
4174 .args_type = "id:s?,node-name:s?",
4175 .mhandler.cmd_new = qmp_marshal_x_blockdev_del,
4176 },
4177
4178SQMP
4179x-blockdev-del
4180------------
4181Since 2.5
4182
4183Deletes a block device thas has been added using blockdev-add.
4184The selected device can be either a block backend or a graph node.
4185
4186In the former case the backend will be destroyed, along with its
4187inserted medium if there's any. The command will fail if the backend
4188or its medium are in use.
4189
4190In the latter case the node will be destroyed. The command will fail
4191if the node is attached to a block backend or is otherwise being
4192used.
4193
4194One of "id" or "node-name" must be specified, but not both.
4195
4196This command is still a work in progress and is considered
4197experimental. Stay away from it unless you want to help with its
4198development.
4199
4200Arguments:
4201
4202- "id": Name of the block backend device to delete (json-string, optional)
4203- "node-name": Name of the graph node to delete (json-string, optional)
4204
4205Example:
4206
4207-> { "execute": "blockdev-add",
4208 "arguments": {
4209 "options": {
4210 "driver": "qcow2",
4211 "id": "drive0",
4212 "file": {
4213 "driver": "file",
4214 "filename": "test.qcow2"
4215 }
4216 }
4217 }
4218 }
4219
4220<- { "return": {} }
4221
4222-> { "execute": "x-blockdev-del",
4223 "arguments": { "id": "drive0" }
4224 }
4225<- { "return": {} }
4226
4227EQMP
4228
4229 {
Max Reitz7d8a9f72015-10-26 21:39:08 +01004230 .name = "blockdev-open-tray",
4231 .args_type = "device:s,force:b?",
4232 .mhandler.cmd_new = qmp_marshal_blockdev_open_tray,
4233 },
4234
4235SQMP
4236blockdev-open-tray
4237------------------
4238
4239Opens a block device's tray. If there is a block driver state tree inserted as a
4240medium, it will become inaccessible to the guest (but it will remain associated
4241to the block device, so closing the tray will make it accessible again).
4242
4243If the tray was already open before, this will be a no-op.
4244
4245Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
4246which no such event will be generated, these include:
4247- if the guest has locked the tray, @force is false and the guest does not
4248 respond to the eject request
4249- if the BlockBackend denoted by @device does not have a guest device attached
4250 to it
4251- if the guest device does not have an actual tray and is empty, for instance
4252 for floppy disk drives
4253
4254Arguments:
4255
4256- "device": block device name (json-string)
4257- "force": if false (the default), an eject request will be sent to the guest if
4258 it has locked the tray (and the tray will not be opened immediately);
4259 if true, the tray will be opened regardless of whether it is locked
4260 (json-bool, optional)
4261
4262Example:
4263
4264-> { "execute": "blockdev-open-tray",
4265 "arguments": { "device": "ide1-cd0" } }
4266
4267<- { "timestamp": { "seconds": 1418751016,
4268 "microseconds": 716996 },
4269 "event": "DEVICE_TRAY_MOVED",
4270 "data": { "device": "ide1-cd0",
4271 "tray-open": true } }
4272
4273<- { "return": {} }
4274
4275EQMP
4276
4277 {
Max Reitzabaaf592015-10-26 21:39:09 +01004278 .name = "blockdev-close-tray",
4279 .args_type = "device:s",
4280 .mhandler.cmd_new = qmp_marshal_blockdev_close_tray,
4281 },
4282
4283SQMP
4284blockdev-close-tray
4285-------------------
4286
4287Closes a block device's tray. If there is a block driver state tree associated
4288with the block device (which is currently ejected), that tree will be loaded as
4289the medium.
4290
4291If the tray was already closed before, this will be a no-op.
4292
4293Arguments:
4294
4295- "device": block device name (json-string)
4296
4297Example:
4298
4299-> { "execute": "blockdev-close-tray",
4300 "arguments": { "device": "ide1-cd0" } }
4301
4302<- { "timestamp": { "seconds": 1418751345,
4303 "microseconds": 272147 },
4304 "event": "DEVICE_TRAY_MOVED",
4305 "data": { "device": "ide1-cd0",
4306 "tray-open": false } }
4307
4308<- { "return": {} }
4309
4310EQMP
4311
4312 {
Max Reitz6e0abc22015-12-11 16:23:05 +01004313 .name = "x-blockdev-remove-medium",
Max Reitz2814f672015-10-26 21:39:10 +01004314 .args_type = "device:s",
Max Reitz6e0abc22015-12-11 16:23:05 +01004315 .mhandler.cmd_new = qmp_marshal_x_blockdev_remove_medium,
Max Reitz2814f672015-10-26 21:39:10 +01004316 },
4317
4318SQMP
Max Reitz6e0abc22015-12-11 16:23:05 +01004319x-blockdev-remove-medium
4320------------------------
Max Reitz2814f672015-10-26 21:39:10 +01004321
4322Removes a medium (a block driver state tree) from a block device. That block
4323device's tray must currently be open (unless there is no attached guest device).
4324
4325If the tray is open and there is no medium inserted, this will be a no-op.
4326
Max Reitz6e0abc22015-12-11 16:23:05 +01004327This command is still a work in progress and is considered experimental.
4328Stay away from it unless you want to help with its development.
4329
Max Reitz2814f672015-10-26 21:39:10 +01004330Arguments:
4331
4332- "device": block device name (json-string)
4333
4334Example:
4335
Max Reitz6e0abc22015-12-11 16:23:05 +01004336-> { "execute": "x-blockdev-remove-medium",
Max Reitz2814f672015-10-26 21:39:10 +01004337 "arguments": { "device": "ide1-cd0" } }
4338
4339<- { "error": { "class": "GenericError",
4340 "desc": "Tray of device 'ide1-cd0' is not open" } }
4341
4342-> { "execute": "blockdev-open-tray",
4343 "arguments": { "device": "ide1-cd0" } }
4344
4345<- { "timestamp": { "seconds": 1418751627,
4346 "microseconds": 549958 },
4347 "event": "DEVICE_TRAY_MOVED",
4348 "data": { "device": "ide1-cd0",
4349 "tray-open": true } }
4350
4351<- { "return": {} }
4352
Max Reitz6e0abc22015-12-11 16:23:05 +01004353-> { "execute": "x-blockdev-remove-medium",
Max Reitz2814f672015-10-26 21:39:10 +01004354 "arguments": { "device": "ide1-cd0" } }
4355
4356<- { "return": {} }
4357
4358EQMP
4359
4360 {
Max Reitz6e0abc22015-12-11 16:23:05 +01004361 .name = "x-blockdev-insert-medium",
Max Reitzd1299882015-10-26 21:39:11 +01004362 .args_type = "device:s,node-name:s",
Max Reitz6e0abc22015-12-11 16:23:05 +01004363 .mhandler.cmd_new = qmp_marshal_x_blockdev_insert_medium,
Max Reitzd1299882015-10-26 21:39:11 +01004364 },
4365
4366SQMP
Max Reitz6e0abc22015-12-11 16:23:05 +01004367x-blockdev-insert-medium
4368------------------------
Max Reitzd1299882015-10-26 21:39:11 +01004369
4370Inserts a medium (a block driver state tree) into a block device. That block
4371device's tray must currently be open (unless there is no attached guest device)
4372and there must be no medium inserted already.
4373
Max Reitz6e0abc22015-12-11 16:23:05 +01004374This command is still a work in progress and is considered experimental.
4375Stay away from it unless you want to help with its development.
4376
Max Reitzd1299882015-10-26 21:39:11 +01004377Arguments:
4378
4379- "device": block device name (json-string)
4380- "node-name": root node of the BDS tree to insert into the block device
4381
4382Example:
4383
4384-> { "execute": "blockdev-add",
4385 "arguments": { "options": { "node-name": "node0",
4386 "driver": "raw",
4387 "file": { "driver": "file",
4388 "filename": "fedora.iso" } } } }
4389
4390<- { "return": {} }
4391
Max Reitz6e0abc22015-12-11 16:23:05 +01004392-> { "execute": "x-blockdev-insert-medium",
Max Reitzd1299882015-10-26 21:39:11 +01004393 "arguments": { "device": "ide1-cd0",
4394 "node-name": "node0" } }
4395
4396<- { "return": {} }
4397
4398EQMP
4399
4400 {
Benoît Canetc13163f2014-01-23 21:31:34 +01004401 .name = "query-named-block-nodes",
4402 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004403 .mhandler.cmd_new = qmp_marshal_query_named_block_nodes,
Benoît Canetc13163f2014-01-23 21:31:34 +01004404 },
4405
4406SQMP
4407@query-named-block-nodes
4408------------------------
4409
4410Return a list of BlockDeviceInfo for all the named block driver nodes
4411
4412Example:
4413
4414-> { "execute": "query-named-block-nodes" }
4415<- { "return": [ { "ro":false,
4416 "drv":"qcow2",
4417 "encrypted":false,
4418 "file":"disks/test.qcow2",
4419 "node-name": "my-node",
4420 "backing_file_depth":1,
4421 "bps":1000000,
4422 "bps_rd":0,
4423 "bps_wr":0,
4424 "iops":1000000,
4425 "iops_rd":0,
4426 "iops_wr":0,
4427 "bps_max": 8000000,
4428 "bps_rd_max": 0,
4429 "bps_wr_max": 0,
4430 "iops_max": 0,
4431 "iops_rd_max": 0,
4432 "iops_wr_max": 0,
4433 "iops_size": 0,
Francesco Romanie2462112015-01-12 14:11:13 +01004434 "write_threshold": 0,
Benoît Canetc13163f2014-01-23 21:31:34 +01004435 "image":{
4436 "filename":"disks/test.qcow2",
4437 "format":"qcow2",
4438 "virtual-size":2048000,
4439 "backing_file":"base.qcow2",
4440 "full-backing-filename":"disks/base.qcow2",
John Snow54034322015-04-28 15:20:41 -04004441 "backing-filename-format":"qcow2",
Benoît Canetc13163f2014-01-23 21:31:34 +01004442 "snapshots":[
4443 {
4444 "id": "1",
4445 "name": "snapshot1",
4446 "vm-state-size": 0,
4447 "date-sec": 10000200,
4448 "date-nsec": 12,
4449 "vm-clock-sec": 206,
4450 "vm-clock-nsec": 30
4451 }
4452 ],
4453 "backing-image":{
4454 "filename":"disks/base.qcow2",
4455 "format":"qcow2",
4456 "virtual-size":2048000
4457 }
Michael S. Tsirkinc0594512014-06-16 15:20:18 +03004458 } } ] }
Benoît Canetc13163f2014-01-23 21:31:34 +01004459
4460EQMP
Hu Tao76b5d852014-06-16 18:05:41 +08004461
4462 {
Max Reitz24fb4132015-11-06 16:27:06 +01004463 .name = "blockdev-change-medium",
Max Reitz39ff43d2015-11-11 04:49:44 +01004464 .args_type = "device:B,filename:F,format:s?,read-only-mode:s?",
Max Reitz24fb4132015-11-06 16:27:06 +01004465 .mhandler.cmd_new = qmp_marshal_blockdev_change_medium,
4466 },
4467
4468SQMP
4469blockdev-change-medium
4470----------------------
4471
4472Changes the medium inserted into a block device by ejecting the current medium
4473and loading a new image file which is inserted as the new medium.
4474
4475Arguments:
4476
4477- "device": device name (json-string)
4478- "filename": filename of the new image (json-string)
4479- "format": format of the new image (json-string, optional)
Max Reitz39ff43d2015-11-11 04:49:44 +01004480- "read-only-mode": new read-only mode (json-string, optional)
4481 - Possible values: "retain" (default), "read-only", "read-write"
Max Reitz24fb4132015-11-06 16:27:06 +01004482
4483Examples:
4484
44851. Change a removable medium
4486
4487-> { "execute": "blockdev-change-medium",
4488 "arguments": { "device": "ide1-cd0",
4489 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
4490 "format": "raw" } }
4491<- { "return": {} }
4492
Max Reitz39ff43d2015-11-11 04:49:44 +010044932. Load a read-only medium into a writable drive
4494
4495-> { "execute": "blockdev-change-medium",
4496 "arguments": { "device": "isa-fd0",
4497 "filename": "/srv/images/ro.img",
4498 "format": "raw",
4499 "read-only-mode": "retain" } }
4500
4501<- { "error":
4502 { "class": "GenericError",
4503 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
4504
4505-> { "execute": "blockdev-change-medium",
4506 "arguments": { "device": "isa-fd0",
4507 "filename": "/srv/images/ro.img",
4508 "format": "raw",
4509 "read-only-mode": "read-only" } }
4510
4511<- { "return": {} }
4512
Max Reitz24fb4132015-11-06 16:27:06 +01004513EQMP
4514
4515 {
Hu Tao76b5d852014-06-16 18:05:41 +08004516 .name = "query-memdev",
4517 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004518 .mhandler.cmd_new = qmp_marshal_query_memdev,
Hu Tao76b5d852014-06-16 18:05:41 +08004519 },
4520
4521SQMP
4522query-memdev
4523------------
4524
4525Show memory devices information.
4526
4527
4528Example (1):
4529
4530-> { "execute": "query-memdev" }
4531<- { "return": [
4532 {
4533 "size": 536870912,
4534 "merge": false,
4535 "dump": true,
4536 "prealloc": false,
4537 "host-nodes": [0, 1],
4538 "policy": "bind"
4539 },
4540 {
4541 "size": 536870912,
4542 "merge": false,
4543 "dump": true,
4544 "prealloc": true,
4545 "host-nodes": [2, 3],
4546 "policy": "preferred"
4547 }
4548 ]
4549 }
4550
4551EQMP
Igor Mammedov6f2e2732014-06-16 19:12:25 +02004552
4553 {
4554 .name = "query-memory-devices",
4555 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004556 .mhandler.cmd_new = qmp_marshal_query_memory_devices,
Igor Mammedov6f2e2732014-06-16 19:12:25 +02004557 },
4558
4559SQMP
4560@query-memory-devices
4561--------------------
4562
4563Return a list of memory devices.
4564
4565Example:
4566-> { "execute": "query-memory-devices" }
4567<- { "return": [ { "data":
4568 { "addr": 5368709120,
4569 "hotpluggable": true,
4570 "hotplugged": true,
4571 "id": "d1",
4572 "memdev": "/objects/memX",
4573 "node": 0,
4574 "size": 1073741824,
4575 "slot": 0},
4576 "type": "dimm"
4577 } ] }
4578EQMP
Igor Mammedov02419bc2014-06-16 19:12:28 +02004579
4580 {
4581 .name = "query-acpi-ospm-status",
4582 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004583 .mhandler.cmd_new = qmp_marshal_query_acpi_ospm_status,
Igor Mammedov02419bc2014-06-16 19:12:28 +02004584 },
4585
4586SQMP
4587@query-acpi-ospm-status
4588--------------------
4589
4590Return list of ACPIOSTInfo for devices that support status reporting
4591via ACPI _OST method.
4592
4593Example:
4594-> { "execute": "query-acpi-ospm-status" }
4595<- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
4596 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
4597 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
4598 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
4599 ]}
4600EQMP
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004601
4602#if defined TARGET_I386
4603 {
4604 .name = "rtc-reset-reinjection",
4605 .args_type = "",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004606 .mhandler.cmd_new = qmp_marshal_rtc_reset_reinjection,
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004607 },
4608#endif
4609
4610SQMP
4611rtc-reset-reinjection
4612---------------------
4613
4614Reset the RTC interrupt reinjection backlog.
4615
4616Arguments: None.
4617
4618Example:
4619
4620-> { "execute": "rtc-reset-reinjection" }
4621<- { "return": {} }
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004622EQMP
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004623
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004624 {
4625 .name = "trace-event-get-state",
4626 .args_type = "name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004627 .mhandler.cmd_new = qmp_marshal_trace_event_get_state,
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004628 },
4629
4630SQMP
4631trace-event-get-state
4632---------------------
4633
4634Query the state of events.
4635
4636Example:
4637
4638-> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
4639<- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
4640EQMP
4641
4642 {
4643 .name = "trace-event-set-state",
4644 .args_type = "name:s,enable:b,ignore-unavailable:b?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004645 .mhandler.cmd_new = qmp_marshal_trace_event_set_state,
Lluís Vilanova1dde0f42014-08-25 13:19:57 +02004646 },
4647
4648SQMP
4649trace-event-set-state
4650---------------------
4651
4652Set the state of events.
4653
4654Example:
4655
4656-> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
4657<- { "return": {} }
Marcelo Tosattif2ae8ab2014-06-24 18:55:11 -03004658EQMP
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004659
4660 {
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004661 .name = "input-send-event",
Amos Kong51fc4472014-11-07 12:41:25 +08004662 .args_type = "console:i?,events:q",
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004663 .mhandler.cmd_new = qmp_marshal_input_send_event,
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004664 },
4665
4666SQMP
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004667@input-send-event
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004668-----------------
4669
4670Send input event to guest.
4671
4672Arguments:
4673
Gerd Hoffmannb98d26e2016-01-12 12:11:14 +01004674- "device": display device (json-string, optional)
4675- "head": display head (json-int, optional)
4676- "events": list of input events
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004677
4678The consoles are visible in the qom tree, under
4679/backend/console[$index]. They have a device link and head property, so
4680it is possible to map which console belongs to which device and display.
4681
Gerd Hoffmanndf5b2ad2014-11-25 14:54:17 +01004682Note: this command is experimental, and not a stable API.
4683
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004684Example (1):
4685
4686Press left mouse button.
4687
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004688-> { "execute": "input-send-event",
Gerd Hoffmannb98d26e2016-01-12 12:11:14 +01004689 "arguments": { "device": "video0",
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004690 "events": [ { "type": "btn",
Gerd Hoffmannf22d0af2016-01-12 12:14:12 +01004691 "data" : { "down": true, "button": "left" } } ] } }
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004692<- { "return": {} }
4693
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004694-> { "execute": "input-send-event",
Gerd Hoffmannb98d26e2016-01-12 12:11:14 +01004695 "arguments": { "device": "video0",
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004696 "events": [ { "type": "btn",
Gerd Hoffmannf22d0af2016-01-12 12:14:12 +01004697 "data" : { "down": false, "button": "left" } } ] } }
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004698<- { "return": {} }
4699
4700Example (2):
4701
4702Press ctrl-alt-del.
4703
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004704-> { "execute": "input-send-event",
Gerd Hoffmannb98d26e2016-01-12 12:11:14 +01004705 "arguments": { "events": [
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004706 { "type": "key", "data" : { "down": true,
4707 "key": {"type": "qcode", "data": "ctrl" } } },
4708 { "type": "key", "data" : { "down": true,
4709 "key": {"type": "qcode", "data": "alt" } } },
4710 { "type": "key", "data" : { "down": true,
4711 "key": {"type": "qcode", "data": "delete" } } } ] } }
4712<- { "return": {} }
4713
4714Example (3):
4715
4716Move mouse pointer to absolute coordinates (20000, 400).
4717
Gerd Hoffmann6575ccd2016-01-12 12:39:33 +01004718-> { "execute": "input-send-event" ,
Gerd Hoffmannb98d26e2016-01-12 12:11:14 +01004719 "arguments": { "events": [
Gerd Hoffmann01df5142016-01-12 12:34:20 +01004720 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
4721 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
Marcelo Tosatti50c66172014-09-30 18:10:17 -03004722<- { "return": {} }
4723
4724EQMP
Francesco Romanie2462112015-01-12 14:11:13 +01004725
4726 {
4727 .name = "block-set-write-threshold",
4728 .args_type = "node-name:s,write-threshold:l",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004729 .mhandler.cmd_new = qmp_marshal_block_set_write_threshold,
Francesco Romanie2462112015-01-12 14:11:13 +01004730 },
4731
4732SQMP
4733block-set-write-threshold
4734------------
4735
4736Change the write threshold for a block drive. The threshold is an offset,
4737thus must be non-negative. Default is no write threshold.
4738Setting the threshold to zero disables it.
4739
4740Arguments:
4741
4742- "node-name": the node name in the block driver state graph (json-string)
4743- "write-threshold": the write threshold in bytes (json-int)
4744
4745Example:
4746
4747-> { "execute": "block-set-write-threshold",
4748 "arguments": { "node-name": "mydev",
4749 "write-threshold": 17179869184 } }
4750<- { "return": {} }
4751
4752EQMP
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004753
4754 {
4755 .name = "query-rocker",
4756 .args_type = "name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004757 .mhandler.cmd_new = qmp_marshal_query_rocker,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004758 },
4759
4760SQMP
4761Show rocker switch
4762------------------
4763
4764Arguments:
4765
4766- "name": switch name
4767
4768Example:
4769
4770-> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
4771<- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
4772
4773EQMP
4774
4775 {
4776 .name = "query-rocker-ports",
4777 .args_type = "name:s",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004778 .mhandler.cmd_new = qmp_marshal_query_rocker_ports,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004779 },
4780
4781SQMP
4782Show rocker switch ports
4783------------------------
4784
4785Arguments:
4786
4787- "name": switch name
4788
4789Example:
4790
4791-> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
4792<- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
4793 "autoneg": "off", "link-up": true, "speed": 10000},
4794 {"duplex": "full", "enabled": true, "name": "sw1.2",
4795 "autoneg": "off", "link-up": true, "speed": 10000}
4796 ]}
4797
4798EQMP
4799
4800 {
4801 .name = "query-rocker-of-dpa-flows",
4802 .args_type = "name:s,tbl-id:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004803 .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_flows,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004804 },
4805
4806SQMP
4807Show rocker switch OF-DPA flow tables
4808-------------------------------------
4809
4810Arguments:
4811
4812- "name": switch name
4813- "tbl-id": (optional) flow table ID
4814
4815Example:
4816
4817-> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
4818<- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
4819 "hits": 138,
4820 "cookie": 0,
4821 "action": {"goto-tbl": 10},
4822 "mask": {"in-pport": 4294901760}
4823 },
4824 {...more...},
4825 ]}
4826
4827EQMP
4828
4829 {
4830 .name = "query-rocker-of-dpa-groups",
4831 .args_type = "name:s,type:i?",
Markus Armbruster7fad30f2015-09-16 13:06:19 +02004832 .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_groups,
Scott Feldmanfafa4d52015-06-10 18:21:21 -07004833 },
4834
4835SQMP
4836Show rocker OF-DPA group tables
4837-------------------------------
4838
4839Arguments:
4840
4841- "name": switch name
4842- "type": (optional) group type
4843
4844Example:
4845
4846-> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
4847<- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
4848 "pop-vlan": 1, "id": 251723778},
4849 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
4850 "pop-vlan": 1, "id": 251723776},
4851 {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
4852 "pop-vlan": 1, "id": 251658241},
4853 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
4854 "pop-vlan": 1, "id": 251658240}
4855 ]}