xref: /illumos-kvm-cmd/qmp-commands.hx (revision 68396ea9)
1HXCOMM QMP dispatch table and documentation
2HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
3HXCOMM 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
45    1. The deprecation policy will take efect and be documented soon, please
46       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  = "",
66        .params     = "",
67        .help       = "quit the emulator",
68        .user_print = monitor_user_noop,
69        .mhandler.cmd_new = do_quit,
70    },
71
72SQMP
73quit
74----
75
76Quit the emulator.
77
78Arguments: None.
79
80Example:
81
82-> { "execute": "quit" }
83<- { "return": {} }
84
85EQMP
86
87    {
88        .name       = "eject",
89        .args_type  = "force:-f,device:B",
90        .params     = "[-f] device",
91        .help       = "eject a removable medium (use -f to force it)",
92        .user_print = monitor_user_noop,
93        .mhandler.cmd_new = do_eject,
94    },
95
96SQMP
97eject
98-----
99
100Eject a removable medium.
101
102Arguments:
103
104- force: force ejection (json-bool, optional)
105- device: device name (json-string)
106
107Example:
108
109-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
110<- { "return": {} }
111
112Note: The "force" argument defaults to false.
113
114EQMP
115
116    {
117        .name       = "change",
118        .args_type  = "device:B,target:F,arg:s?",
119        .params     = "device filename [format]",
120        .help       = "change a removable medium, optional format",
121        .user_print = monitor_user_noop,
122        .mhandler.cmd_new = do_change,
123    },
124
125SQMP
126change
127------
128
129Change a removable medium or VNC configuration.
130
131Arguments:
132
133- "device": device name (json-string)
134- "target": filename or item (json-string)
135- "arg": additional argument (json-string, optional)
136
137Examples:
138
1391. Change a removable medium
140
141-> { "execute": "change",
142             "arguments": { "device": "ide1-cd0",
143                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
144<- { "return": {} }
145
1462. Change VNC password
147
148-> { "execute": "change",
149             "arguments": { "device": "vnc", "target": "password",
150                            "arg": "foobar1" } }
151<- { "return": {} }
152
153EQMP
154
155    {
156        .name       = "screendump",
157        .args_type  = "filename:F",
158        .params     = "filename",
159        .help       = "save screen into PPM image 'filename'",
160        .user_print = monitor_user_noop,
161        .mhandler.cmd_new = do_screen_dump,
162    },
163
164SQMP
165screendump
166----------
167
168Save screen into PPM image.
169
170Arguments:
171
172- "filename": file path (json-string)
173
174Example:
175
176-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
177<- { "return": {} }
178
179EQMP
180
181    {
182        .name       = "stop",
183        .args_type  = "",
184        .params     = "",
185        .help       = "stop emulation",
186        .user_print = monitor_user_noop,
187        .mhandler.cmd_new = do_stop,
188    },
189
190SQMP
191stop
192----
193
194Stop the emulator.
195
196Arguments: None.
197
198Example:
199
200-> { "execute": "stop" }
201<- { "return": {} }
202
203EQMP
204
205    {
206        .name       = "cont",
207        .args_type  = "",
208        .params     = "",
209        .help       = "resume emulation",
210        .user_print = monitor_user_noop,
211        .mhandler.cmd_new = do_cont,
212    },
213
214SQMP
215cont
216----
217
218Resume emulation.
219
220Arguments: None.
221
222Example:
223
224-> { "execute": "cont" }
225<- { "return": {} }
226
227EQMP
228
229    {
230        .name       = "system_reset",
231        .args_type  = "",
232        .params     = "",
233        .help       = "reset the system",
234        .user_print = monitor_user_noop,
235        .mhandler.cmd_new = do_system_reset,
236    },
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  = "",
256        .params     = "",
257        .help       = "send system power down event",
258        .user_print = monitor_user_noop,
259        .mhandler.cmd_new = do_system_powerdown,
260    },
261
262SQMP
263system_powerdown
264----------------
265
266Send system power down event.
267
268Arguments: None.
269
270Example:
271
272-> { "execute": "system_powerdown" }
273<- { "return": {} }
274
275EQMP
276
277    {
278        .name       = "device_add",
279        .args_type  = "device:O",
280        .params     = "driver[,prop=value][,...]",
281        .help       = "add device, like -device on the command line",
282        .user_print = monitor_user_noop,
283        .mhandler.cmd_new = do_device_add,
284    },
285
286SQMP
287device_add
288----------
289
290Add a device.
291
292Arguments:
293
294- "driver": the name of the new device's driver (json-string)
295- "bus": the device's parent bus (device tree path, json-string, optional)
296- "id": the device's ID, must be unique (json-string)
297- device properties
298
299Example:
300
301-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
302<- { "return": {} }
303
304Notes:
305
306(1) For detailed information about this command, please refer to the
307    'docs/qdev-device-use.txt' file.
308
309(2) It's possible to list device properties by running QEMU with the
310    "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
311
312EQMP
313
314    {
315        .name       = "device_del",
316        .args_type  = "id:s",
317        .params     = "device",
318        .help       = "remove device",
319        .user_print = monitor_user_noop,
320        .mhandler.cmd_new = do_device_del,
321    },
322
323SQMP
324device_del
325----------
326
327Remove a device.
328
329Arguments:
330
331- "id": the device's ID (json-string)
332
333Example:
334
335-> { "execute": "device_del", "arguments": { "id": "net1" } }
336<- { "return": {} }
337
338EQMP
339
340    {
341        .name       = "cpu",
342        .args_type  = "index:i",
343        .params     = "index",
344        .help       = "set the default CPU",
345        .user_print = monitor_user_noop,
346        .mhandler.cmd_new = do_cpu_set,
347    },
348
349SQMP
350cpu
351---
352
353Set the default CPU.
354
355Arguments:
356
357- "index": the CPU's index (json-int)
358
359Example:
360
361-> { "execute": "cpu", "arguments": { "index": 0 } }
362<- { "return": {} }
363
364Note: CPUs' indexes are obtained with the 'query-cpus' command.
365
366EQMP
367
368    {
369        .name       = "memsave",
370        .args_type  = "val:l,size:i,filename:s",
371        .params     = "addr size file",
372        .help       = "save to disk virtual memory dump starting at 'addr' of size 'size'",
373        .user_print = monitor_user_noop,
374        .mhandler.cmd_new = do_memory_save,
375    },
376
377SQMP
378memsave
379-------
380
381Save to disk virtual memory dump starting at 'val' of size 'size'.
382
383Arguments:
384
385- "val": the starting address (json-int)
386- "size": the memory size, in bytes (json-int)
387- "filename": file path (json-string)
388
389Example:
390
391-> { "execute": "memsave",
392             "arguments": { "val": 10,
393                            "size": 100,
394                            "filename": "/tmp/virtual-mem-dump" } }
395<- { "return": {} }
396
397Note: Depends on the current CPU.
398
399EQMP
400
401    {
402        .name       = "pmemsave",
403        .args_type  = "val:l,size:i,filename:s",
404        .params     = "addr size file",
405        .help       = "save to disk physical memory dump starting at 'addr' of size 'size'",
406        .user_print = monitor_user_noop,
407        .mhandler.cmd_new = do_physical_memory_save,
408    },
409
410SQMP
411pmemsave
412--------
413
414Save to disk physical memory dump starting at 'val' of size 'size'.
415
416Arguments:
417
418- "val": the starting address (json-int)
419- "size": the memory size, in bytes (json-int)
420- "filename": file path (json-string)
421
422Example:
423
424-> { "execute": "pmemsave",
425             "arguments": { "val": 10,
426                            "size": 100,
427                            "filename": "/tmp/physical-mem-dump" } }
428<- { "return": {} }
429
430EQMP
431
432    {
433        .name       = "migrate",
434        .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
435        .params     = "[-d] [-b] [-i] uri",
436        .help       = "migrate to URI (using -d to not wait for completion)"
437		      "\n\t\t\t -b for migration without shared storage with"
438		      " full copy of disk\n\t\t\t -i for migration without "
439		      "shared storage with incremental copy of disk "
440		      "(base image shared between src and destination)",
441        .user_print = monitor_user_noop,
442	.mhandler.cmd_new = do_migrate,
443    },
444
445SQMP
446migrate
447-------
448
449Migrate to URI.
450
451Arguments:
452
453- "blk": block migration, full disk copy (json-bool, optional)
454- "inc": incremental disk copy (json-bool, optional)
455- "uri": Destination URI (json-string)
456
457Example:
458
459-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
460<- { "return": {} }
461
462Notes:
463
464(1) The 'query-migrate' command should be used to check migration's progress
465    and final result (this information is provided by the 'status' member)
466(2) All boolean arguments default to false
467(3) The user Monitor's "detach" argument is invalid in QMP and should not
468    be used
469
470EQMP
471
472    {
473        .name       = "migrate_cancel",
474        .args_type  = "",
475        .params     = "",
476        .help       = "cancel the current VM migration",
477        .user_print = monitor_user_noop,
478        .mhandler.cmd_new = do_migrate_cancel,
479    },
480
481SQMP
482migrate_cancel
483--------------
484
485Cancel the current migration.
486
487Arguments: None.
488
489Example:
490
491-> { "execute": "migrate_cancel" }
492<- { "return": {} }
493
494EQMP
495
496    {
497        .name       = "migrate_set_speed",
498        .args_type  = "value:o",
499        .params     = "value",
500        .help       = "set maximum speed (in bytes) for migrations",
501        .user_print = monitor_user_noop,
502        .mhandler.cmd_new = do_migrate_set_speed,
503    },
504
505SQMP
506client_migrate_info
507------------------
508
509Set the spice/vnc connection info for the migration target.  The spice/vnc
510server will ask the spice/vnc client to automatically reconnect using the
511new parameters (if specified) once the vm migration finished successfully.
512
513Arguments:
514
515- "protocol":     protocol: "spice" or "vnc" (json-string)
516- "hostname":     migration target hostname (json-string)
517- "port":         spice/vnc tcp port for plaintext channels (json-int, optional)
518- "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
519- "cert-subject": server certificate subject (json-string, optional)
520
521Example:
522
523-> { "execute": "client_migrate_info",
524     "arguments": { "protocol": "spice",
525                    "hostname": "virt42.lab.kraxel.org",
526                    "port": 1234 } }
527<- { "return": {} }
528
529EQMP
530
531    {
532        .name       = "client_migrate_info",
533        .args_type  = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
534        .params     = "protocol hostname port tls-port cert-subject",
535        .help       = "send migration info to spice/vnc client",
536        .user_print = monitor_user_noop,
537        .mhandler.cmd_new = client_migrate_info,
538    },
539
540SQMP
541migrate_set_speed
542-----------------
543
544Set maximum speed for migrations.
545
546Arguments:
547
548- "value": maximum speed, in bytes per second (json-int)
549
550Example:
551
552-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
553<- { "return": {} }
554
555EQMP
556
557    {
558        .name       = "migrate_set_downtime",
559        .args_type  = "value:T",
560        .params     = "value",
561        .help       = "set maximum tolerated downtime (in seconds) for migrations",
562        .user_print = monitor_user_noop,
563        .mhandler.cmd_new = do_migrate_set_downtime,
564    },
565
566SQMP
567migrate_set_downtime
568--------------------
569
570Set maximum tolerated downtime (in seconds) for migrations.
571
572Arguments:
573
574- "value": maximum downtime (json-number)
575
576Example:
577
578-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
579<- { "return": {} }
580
581EQMP
582
583    {
584        .name       = "netdev_add",
585        .args_type  = "netdev:O",
586        .params     = "[user|tap|socket],id=str[,prop=value][,...]",
587        .help       = "add host network device",
588        .user_print = monitor_user_noop,
589        .mhandler.cmd_new = do_netdev_add,
590    },
591
592SQMP
593netdev_add
594----------
595
596Add host network device.
597
598Arguments:
599
600- "type": the device type, "tap", "user", ... (json-string)
601- "id": the device's ID, must be unique (json-string)
602- device options
603
604Example:
605
606-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
607<- { "return": {} }
608
609Note: The supported device options are the same ones supported by the '-net'
610      command-line argument, which are listed in the '-help' output or QEMU's
611      manual
612
613EQMP
614
615    {
616        .name       = "netdev_del",
617        .args_type  = "id:s",
618        .params     = "id",
619        .help       = "remove host network device",
620        .user_print = monitor_user_noop,
621        .mhandler.cmd_new = do_netdev_del,
622    },
623
624SQMP
625netdev_del
626----------
627
628Remove host network device.
629
630Arguments:
631
632- "id": the device's ID, must be unique (json-string)
633
634Example:
635
636-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
637<- { "return": {} }
638
639
640EQMP
641
642    {
643        .name       = "block_resize",
644        .args_type  = "device:B,size:o",
645        .params     = "device size",
646        .help       = "resize a block image",
647        .user_print = monitor_user_noop,
648        .mhandler.cmd_new = do_block_resize,
649    },
650
651SQMP
652block_resize
653------------
654
655Resize a block image while a guest is running.
656
657Arguments:
658
659- "device": the device's ID, must be unique (json-string)
660- "size": new size
661
662Example:
663
664-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
665<- { "return": {} }
666
667EQMP
668
669    {
670        .name       = "balloon",
671        .args_type  = "value:M",
672        .params     = "target",
673        .help       = "request VM to change its memory allocation (in MB)",
674        .user_print = monitor_user_noop,
675        .mhandler.cmd_async = do_balloon,
676        .flags      = MONITOR_CMD_ASYNC,
677    },
678
679SQMP
680balloon
681-------
682
683Request VM to change its memory allocation (in bytes).
684
685Arguments:
686
687- "value": New memory allocation (json-int)
688
689Example:
690
691-> { "execute": "balloon", "arguments": { "value": 536870912 } }
692<- { "return": {} }
693
694EQMP
695
696    {
697        .name       = "set_link",
698        .args_type  = "name:s,up:b",
699        .params     = "name on|off",
700        .help       = "change the link status of a network adapter",
701        .user_print = monitor_user_noop,
702        .mhandler.cmd_new = do_set_link,
703    },
704
705SQMP
706set_link
707--------
708
709Change the link status of a network adapter.
710
711Arguments:
712
713- "name": network device name (json-string)
714- "up": status is up (json-bool)
715
716Example:
717
718-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
719<- { "return": {} }
720
721EQMP
722
723    {
724        .name       = "getfd",
725        .args_type  = "fdname:s",
726        .params     = "getfd name",
727        .help       = "receive a file descriptor via SCM rights and assign it a name",
728        .user_print = monitor_user_noop,
729        .mhandler.cmd_new = do_getfd,
730    },
731
732SQMP
733getfd
734-----
735
736Receive a file descriptor via SCM rights and assign it a name.
737
738Arguments:
739
740- "fdname": file descriptor name (json-string)
741
742Example:
743
744-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
745<- { "return": {} }
746
747EQMP
748
749    {
750        .name       = "closefd",
751        .args_type  = "fdname:s",
752        .params     = "closefd name",
753        .help       = "close a file descriptor previously passed via SCM rights",
754        .user_print = monitor_user_noop,
755        .mhandler.cmd_new = do_closefd,
756    },
757
758SQMP
759closefd
760-------
761
762Close a file descriptor previously passed via SCM rights.
763
764Arguments:
765
766- "fdname": file descriptor name (json-string)
767
768Example:
769
770-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
771<- { "return": {} }
772
773EQMP
774
775    {
776        .name       = "block_passwd",
777        .args_type  = "device:B,password:s",
778        .params     = "block_passwd device password",
779        .help       = "set the password of encrypted block devices",
780        .user_print = monitor_user_noop,
781        .mhandler.cmd_new = do_block_set_passwd,
782    },
783
784SQMP
785block_passwd
786------------
787
788Set the password of encrypted block devices.
789
790Arguments:
791
792- "device": device name (json-string)
793- "password": password (json-string)
794
795Example:
796
797-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
798                                               "password": "12345" } }
799<- { "return": {} }
800
801EQMP
802
803    {
804        .name       = "set_password",
805        .args_type  = "protocol:s,password:s,connected:s?",
806        .params     = "protocol password action-if-connected",
807        .help       = "set spice/vnc password",
808        .user_print = monitor_user_noop,
809        .mhandler.cmd_new = set_password,
810    },
811
812SQMP
813set_password
814------------
815
816Set the password for vnc/spice protocols.
817
818Arguments:
819
820- "protocol": protocol name (json-string)
821- "password": password (json-string)
822- "connected": [ keep | disconnect | fail ] (josn-string, optional)
823
824Example:
825
826-> { "execute": "set_password", "arguments": { "protocol": "vnc",
827                                               "password": "secret" } }
828<- { "return": {} }
829
830EQMP
831
832    {
833        .name       = "expire_password",
834        .args_type  = "protocol:s,time:s",
835        .params     = "protocol time",
836        .help       = "set spice/vnc password expire-time",
837        .user_print = monitor_user_noop,
838        .mhandler.cmd_new = expire_password,
839    },
840
841SQMP
842expire_password
843---------------
844
845Set the password expire time for vnc/spice protocols.
846
847Arguments:
848
849- "protocol": protocol name (json-string)
850- "time": [ now | never | +secs | secs ] (json-string)
851
852Example:
853
854-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
855                                                  "time": "+60" } }
856<- { "return": {} }
857
858EQMP
859
860    {
861        .name       = "qmp_capabilities",
862        .args_type  = "",
863        .params     = "",
864        .help       = "enable QMP capabilities",
865        .user_print = monitor_user_noop,
866        .mhandler.cmd_new = do_qmp_capabilities,
867    },
868
869SQMP
870qmp_capabilities
871----------------
872
873Enable QMP capabilities.
874
875Arguments: None.
876
877Example:
878
879-> { "execute": "qmp_capabilities" }
880<- { "return": {} }
881
882Note: This command must be issued before issuing any other command.
883
884EQMP
885
886    {
887        .name       = "human-monitor-command",
888        .args_type  = "command-line:s,cpu-index:i?",
889        .params     = "",
890        .help       = "",
891        .user_print = monitor_user_noop,
892        .mhandler.cmd_new = do_hmp_passthrough,
893    },
894
895SQMP
896human-monitor-command
897---------------------
898
899Execute a Human Monitor command.
900
901Arguments:
902
903- command-line: the command name and its arguments, just like the
904                Human Monitor's shell (json-string)
905- cpu-index: select the CPU number to be used by commands which access CPU
906             data, like 'info registers'. The Monitor selects CPU 0 if this
907             argument is not provided (json-int, optional)
908
909Example:
910
911-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
912<- { "return": "kvm support: enabled\r\n" }
913
914Notes:
915
916(1) The Human Monitor is NOT an stable interface, this means that command
917    names, arguments and responses can change or be removed at ANY time.
918    Applications that rely on long term stability guarantees should NOT
919    use this command
920
921(2) Limitations:
922
923    o This command is stateless, this means that commands that depend
924      on state information (such as getfd) might not work
925
926    o Commands that prompt the user for data (eg. 'cont' when the block
927      device is encrypted) don't currently work
928
9293. Query Commands
930=================
931
932HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
933HXCOMM this! We will possibly move query commands definitions inside those
934HXCOMM sections, just like regular commands.
935
936EQMP
937
938SQMP
939query-version
940-------------
941
942Show QEMU version.
943
944Return a json-object with the following information:
945
946- "qemu": A json-object containing three integer values:
947    - "major": QEMU's major version (json-int)
948    - "minor": QEMU's minor version (json-int)
949    - "micro": QEMU's micro version (json-int)
950- "package": package's version (json-string)
951
952Example:
953
954-> { "execute": "query-version" }
955<- {
956      "return":{
957         "qemu":{
958            "major":0,
959            "minor":11,
960            "micro":5
961         },
962         "package":""
963      }
964   }
965
966EQMP
967
968SQMP
969query-commands
970--------------
971
972List QMP available commands.
973
974Each command is represented by a json-object, the returned value is a json-array
975of all commands.
976
977Each json-object contain:
978
979- "name": command's name (json-string)
980
981Example:
982
983-> { "execute": "query-commands" }
984<- {
985      "return":[
986         {
987            "name":"query-balloon"
988         },
989         {
990            "name":"system_powerdown"
991         }
992      ]
993   }
994
995Note: This example has been shortened as the real response is too long.
996
997EQMP
998
999SQMP
1000query-chardev
1001-------------
1002
1003Each device is represented by a json-object. The returned value is a json-array
1004of all devices.
1005
1006Each json-object contain the following:
1007
1008- "label": device's label (json-string)
1009- "filename": device's file (json-string)
1010
1011Example:
1012
1013-> { "execute": "query-chardev" }
1014<- {
1015      "return":[
1016         {
1017            "label":"monitor",
1018            "filename":"stdio"
1019         },
1020         {
1021            "label":"serial0",
1022            "filename":"vc"
1023         }
1024      ]
1025   }
1026
1027EQMP
1028
1029SQMP
1030query-block
1031-----------
1032
1033Show the block devices.
1034
1035Each block device information is stored in a json-object and the returned value
1036is a json-array of all devices.
1037
1038Each json-object contain the following:
1039
1040- "device": device name (json-string)
1041- "type": device type (json-string)
1042         - Possible values: "hd", "cdrom", "floppy", "unknown"
1043- "removable": true if the device is removable, false otherwise (json-bool)
1044- "locked": true if the device is locked, false otherwise (json-bool)
1045- "inserted": only present if the device is inserted, it is a json-object
1046   containing the following:
1047         - "file": device file name (json-string)
1048         - "ro": true if read-only, false otherwise (json-bool)
1049         - "drv": driver format name (json-string)
1050             - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1051                                "file", "file", "ftp", "ftps", "host_cdrom",
1052                                "host_device", "host_floppy", "http", "https",
1053                                "nbd", "parallels", "qcow", "qcow2", "raw",
1054                                "tftp", "vdi", "vmdk", "vpc", "vvfat"
1055         - "backing_file": backing file name (json-string, optional)
1056         - "encrypted": true if encrypted, false otherwise (json-bool)
1057
1058Example:
1059
1060-> { "execute": "query-block" }
1061<- {
1062      "return":[
1063         {
1064            "device":"ide0-hd0",
1065            "locked":false,
1066            "removable":false,
1067            "inserted":{
1068               "ro":false,
1069               "drv":"qcow2",
1070               "encrypted":false,
1071               "file":"disks/test.img"
1072            },
1073            "type":"hd"
1074         },
1075         {
1076            "device":"ide1-cd0",
1077            "locked":false,
1078            "removable":true,
1079            "type":"cdrom"
1080         },
1081         {
1082            "device":"floppy0",
1083            "locked":false,
1084            "removable":true,
1085            "type": "floppy"
1086         },
1087         {
1088            "device":"sd0",
1089            "locked":false,
1090            "removable":true,
1091            "type":"floppy"
1092         }
1093      ]
1094   }
1095
1096EQMP
1097
1098SQMP
1099query-blockstats
1100----------------
1101
1102Show block device statistics.
1103
1104Each device statistic information is stored in a json-object and the returned
1105value is a json-array of all devices.
1106
1107Each json-object contain the following:
1108
1109- "device": device name (json-string)
1110- "stats": A json-object with the statistics information, it contains:
1111    - "rd_bytes": bytes read (json-int)
1112    - "wr_bytes": bytes written (json-int)
1113    - "rd_operations": read operations (json-int)
1114    - "wr_operations": write operations (json-int)
1115    - "wr_highest_offset": Highest offset of a sector written since the
1116                           BlockDriverState has been opened (json-int)
1117- "parent": Contains recursively the statistics of the underlying
1118            protocol (e.g. the host file for a qcow2 image). If there is
1119            no underlying protocol, this field is omitted
1120            (json-object, optional)
1121
1122Example:
1123
1124-> { "execute": "query-blockstats" }
1125<- {
1126      "return":[
1127         {
1128            "device":"ide0-hd0",
1129            "parent":{
1130               "stats":{
1131                  "wr_highest_offset":3686448128,
1132                  "wr_bytes":9786368,
1133                  "wr_operations":751,
1134                  "rd_bytes":122567168,
1135                  "rd_operations":36772
1136               }
1137            },
1138            "stats":{
1139               "wr_highest_offset":2821110784,
1140               "wr_bytes":9786368,
1141               "wr_operations":692,
1142               "rd_bytes":122739200,
1143               "rd_operations":36604
1144            }
1145         },
1146         {
1147            "device":"ide1-cd0",
1148            "stats":{
1149               "wr_highest_offset":0,
1150               "wr_bytes":0,
1151               "wr_operations":0,
1152               "rd_bytes":0,
1153               "rd_operations":0
1154            }
1155         },
1156         {
1157            "device":"floppy0",
1158            "stats":{
1159               "wr_highest_offset":0,
1160               "wr_bytes":0,
1161               "wr_operations":0,
1162               "rd_bytes":0,
1163               "rd_operations":0
1164            }
1165         },
1166         {
1167            "device":"sd0",
1168            "stats":{
1169               "wr_highest_offset":0,
1170               "wr_bytes":0,
1171               "wr_operations":0,
1172               "rd_bytes":0,
1173               "rd_operations":0
1174            }
1175         }
1176      ]
1177   }
1178
1179EQMP
1180
1181SQMP
1182query-cpus
1183----------
1184
1185Show CPU information.
1186
1187Return a json-array. Each CPU is represented by a json-object, which contains:
1188
1189- "CPU": CPU index (json-int)
1190- "current": true if this is the current CPU, false otherwise (json-bool)
1191- "halted": true if the cpu is halted, false otherwise (json-bool)
1192- Current program counter. The key's name depends on the architecture:
1193     "pc": i386/x86_64 (json-int)
1194     "nip": PPC (json-int)
1195     "pc" and "npc": sparc (json-int)
1196     "PC": mips (json-int)
1197
1198Example:
1199
1200-> { "execute": "query-cpus" }
1201<- {
1202      "return":[
1203         {
1204            "CPU":0,
1205            "current":true,
1206            "halted":false,
1207            "pc":3227107138
1208         },
1209         {
1210            "CPU":1,
1211            "current":false,
1212            "halted":true,
1213            "pc":7108165
1214         }
1215      ]
1216   }
1217
1218EQMP
1219
1220SQMP
1221query-pci
1222---------
1223
1224PCI buses and devices information.
1225
1226The returned value is a json-array of all buses. Each bus is represented by
1227a json-object, which has a key with a json-array of all PCI devices attached
1228to it. Each device is represented by a json-object.
1229
1230The bus json-object contains the following:
1231
1232- "bus": bus number (json-int)
1233- "devices": a json-array of json-objects, each json-object represents a
1234             PCI device
1235
1236The PCI device json-object contains the following:
1237
1238- "bus": identical to the parent's bus number (json-int)
1239- "slot": slot number (json-int)
1240- "function": function number (json-int)
1241- "class_info": a json-object containing:
1242     - "desc": device class description (json-string, optional)
1243     - "class": device class number (json-int)
1244- "id": a json-object containing:
1245     - "device": device ID (json-int)
1246     - "vendor": vendor ID (json-int)
1247- "irq": device's IRQ if assigned (json-int, optional)
1248- "qdev_id": qdev id string (json-string)
1249- "pci_bridge": It's a json-object, only present if this device is a
1250                PCI bridge, contains:
1251     - "bus": bus number (json-int)
1252     - "secondary": secondary bus number (json-int)
1253     - "subordinate": subordinate bus number (json-int)
1254     - "io_range": I/O memory range information, a json-object with the
1255                   following members:
1256                 - "base": base address, in bytes (json-int)
1257                 - "limit": limit address, in bytes (json-int)
1258     - "memory_range": memory range information, a json-object with the
1259                       following members:
1260                 - "base": base address, in bytes (json-int)
1261                 - "limit": limit address, in bytes (json-int)
1262     - "prefetchable_range": Prefetchable memory range information, a
1263                             json-object with the following members:
1264                 - "base": base address, in bytes (json-int)
1265                 - "limit": limit address, in bytes (json-int)
1266     - "devices": a json-array of PCI devices if there's any attached, each
1267                  each element is represented by a json-object, which contains
1268                  the same members of the 'PCI device json-object' described
1269                  above (optional)
1270- "regions": a json-array of json-objects, each json-object represents a
1271             memory region of this device
1272
1273The memory range json-object contains the following:
1274
1275- "base": base memory address (json-int)
1276- "limit": limit value (json-int)
1277
1278The region json-object can be an I/O region or a memory region, an I/O region
1279json-object contains the following:
1280
1281- "type": "io" (json-string, fixed)
1282- "bar": BAR number (json-int)
1283- "address": memory address (json-int)
1284- "size": memory size (json-int)
1285
1286A memory region json-object contains the following:
1287
1288- "type": "memory" (json-string, fixed)
1289- "bar": BAR number (json-int)
1290- "address": memory address (json-int)
1291- "size": memory size (json-int)
1292- "mem_type_64": true or false (json-bool)
1293- "prefetch": true or false (json-bool)
1294
1295Example:
1296
1297-> { "execute": "query-pci" }
1298<- {
1299      "return":[
1300         {
1301            "bus":0,
1302            "devices":[
1303               {
1304                  "bus":0,
1305                  "qdev_id":"",
1306                  "slot":0,
1307                  "class_info":{
1308                     "class":1536,
1309                     "desc":"Host bridge"
1310                  },
1311                  "id":{
1312                     "device":32902,
1313                     "vendor":4663
1314                  },
1315                  "function":0,
1316                  "regions":[
1317
1318                  ]
1319               },
1320               {
1321                  "bus":0,
1322                  "qdev_id":"",
1323                  "slot":1,
1324                  "class_info":{
1325                     "class":1537,
1326                     "desc":"ISA bridge"
1327                  },
1328                  "id":{
1329                     "device":32902,
1330                     "vendor":28672
1331                  },
1332                  "function":0,
1333                  "regions":[
1334
1335                  ]
1336               },
1337               {
1338                  "bus":0,
1339                  "qdev_id":"",
1340                  "slot":1,
1341                  "class_info":{
1342                     "class":257,
1343                     "desc":"IDE controller"
1344                  },
1345                  "id":{
1346                     "device":32902,
1347                     "vendor":28688
1348                  },
1349                  "function":1,
1350                  "regions":[
1351                     {
1352                        "bar":4,
1353                        "size":16,
1354                        "address":49152,
1355                        "type":"io"
1356                     }
1357                  ]
1358               },
1359               {
1360                  "bus":0,
1361                  "qdev_id":"",
1362                  "slot":2,
1363                  "class_info":{
1364                     "class":768,
1365                     "desc":"VGA controller"
1366                  },
1367                  "id":{
1368                     "device":4115,
1369                     "vendor":184
1370                  },
1371                  "function":0,
1372                  "regions":[
1373                     {
1374                        "prefetch":true,
1375                        "mem_type_64":false,
1376                        "bar":0,
1377                        "size":33554432,
1378                        "address":4026531840,
1379                        "type":"memory"
1380                     },
1381                     {
1382                        "prefetch":false,
1383                        "mem_type_64":false,
1384                        "bar":1,
1385                        "size":4096,
1386                        "address":4060086272,
1387                        "type":"memory"
1388                     },
1389                     {
1390                        "prefetch":false,
1391                        "mem_type_64":false,
1392                        "bar":6,
1393                        "size":65536,
1394                        "address":-1,
1395                        "type":"memory"
1396                     }
1397                  ]
1398               },
1399               {
1400                  "bus":0,
1401                  "qdev_id":"",
1402                  "irq":11,
1403                  "slot":4,
1404                  "class_info":{
1405                     "class":1280,
1406                     "desc":"RAM controller"
1407                  },
1408                  "id":{
1409                     "device":6900,
1410                     "vendor":4098
1411                  },
1412                  "function":0,
1413                  "regions":[
1414                     {
1415                        "bar":0,
1416                        "size":32,
1417                        "address":49280,
1418                        "type":"io"
1419                     }
1420                  ]
1421               }
1422            ]
1423         }
1424      ]
1425   }
1426
1427Note: This example has been shortened as the real response is too long.
1428
1429EQMP
1430
1431SQMP
1432query-kvm
1433---------
1434
1435Show KVM information.
1436
1437Return a json-object with the following information:
1438
1439- "enabled": true if KVM support is enabled, false otherwise (json-bool)
1440- "present": true if QEMU has KVM support, false otherwise (json-bool)
1441
1442Example:
1443
1444-> { "execute": "query-kvm" }
1445<- { "return": { "enabled": true, "present": true } }
1446
1447EQMP
1448
1449SQMP
1450query-status
1451------------
1452
1453Return a json-object with the following information:
1454
1455- "running": true if the VM is running, or false if it is paused (json-bool)
1456- "singlestep": true if the VM is in single step mode,
1457                false otherwise (json-bool)
1458
1459Example:
1460
1461-> { "execute": "query-status" }
1462<- { "return": { "running": true, "singlestep": false } }
1463
1464EQMP
1465
1466SQMP
1467query-mice
1468----------
1469
1470Show VM mice information.
1471
1472Each mouse is represented by a json-object, the returned value is a json-array
1473of all mice.
1474
1475The mouse json-object contains the following:
1476
1477- "name": mouse's name (json-string)
1478- "index": mouse's index (json-int)
1479- "current": true if this mouse is receiving events, false otherwise (json-bool)
1480- "absolute": true if the mouse generates absolute input events (json-bool)
1481
1482Example:
1483
1484-> { "execute": "query-mice" }
1485<- {
1486      "return":[
1487         {
1488            "name":"QEMU Microsoft Mouse",
1489            "index":0,
1490            "current":false,
1491            "absolute":false
1492         },
1493         {
1494            "name":"QEMU PS/2 Mouse",
1495            "index":1,
1496            "current":true,
1497            "absolute":true
1498         }
1499      ]
1500   }
1501
1502EQMP
1503
1504SQMP
1505query-vnc
1506---------
1507
1508Show VNC server information.
1509
1510Return a json-object with server information. Connected clients are returned
1511as a json-array of json-objects.
1512
1513The main json-object contains the following:
1514
1515- "enabled": true or false (json-bool)
1516- "host": server's IP address (json-string)
1517- "family": address family (json-string)
1518         - Possible values: "ipv4", "ipv6", "unix", "unknown"
1519- "service": server's port number (json-string)
1520- "auth": authentication method (json-string)
1521         - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1522                            "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1523                            "vencrypt+plain", "vencrypt+tls+none",
1524                            "vencrypt+tls+plain", "vencrypt+tls+sasl",
1525                            "vencrypt+tls+vnc", "vencrypt+x509+none",
1526                            "vencrypt+x509+plain", "vencrypt+x509+sasl",
1527                            "vencrypt+x509+vnc", "vnc"
1528- "clients": a json-array of all connected clients
1529
1530Clients are described by a json-object, each one contain the following:
1531
1532- "host": client's IP address (json-string)
1533- "family": address family (json-string)
1534         - Possible values: "ipv4", "ipv6", "unix", "unknown"
1535- "service": client's port number (json-string)
1536- "x509_dname": TLS dname (json-string, optional)
1537- "sasl_username": SASL username (json-string, optional)
1538
1539Example:
1540
1541-> { "execute": "query-vnc" }
1542<- {
1543      "return":{
1544         "enabled":true,
1545         "host":"0.0.0.0",
1546         "service":"50402",
1547         "auth":"vnc",
1548         "family":"ipv4",
1549         "clients":[
1550            {
1551               "host":"127.0.0.1",
1552               "service":"50401",
1553               "family":"ipv4"
1554            }
1555         ]
1556      }
1557   }
1558
1559EQMP
1560
1561SQMP
1562query-spice
1563-----------
1564
1565Show SPICE server information.
1566
1567Return a json-object with server information. Connected clients are returned
1568as a json-array of json-objects.
1569
1570The main json-object contains the following:
1571
1572- "enabled": true or false (json-bool)
1573- "host": server's IP address (json-string)
1574- "port": server's port number (json-int, optional)
1575- "tls-port": server's port number (json-int, optional)
1576- "auth": authentication method (json-string)
1577         - Possible values: "none", "spice"
1578- "channels": a json-array of all active channels clients
1579
1580Channels are described by a json-object, each one contain the following:
1581
1582- "host": client's IP address (json-string)
1583- "family": address family (json-string)
1584         - Possible values: "ipv4", "ipv6", "unix", "unknown"
1585- "port": client's port number (json-string)
1586- "connection-id": spice connection id.  All channels with the same id
1587                   belong to the same spice session (json-int)
1588- "channel-type": channel type.  "1" is the main control channel, filter for
1589                  this one if you want track spice sessions only (json-int)
1590- "channel-id": channel id.  Usually "0", might be different needed when
1591                multiple channels of the same type exist, such as multiple
1592                display channels in a multihead setup (json-int)
1593- "tls": whevener the channel is encrypted (json-bool)
1594
1595Example:
1596
1597-> { "execute": "query-spice" }
1598<- {
1599      "return": {
1600         "enabled": true,
1601         "auth": "spice",
1602         "port": 5920,
1603         "tls-port": 5921,
1604         "host": "0.0.0.0",
1605         "channels": [
1606            {
1607               "port": "54924",
1608               "family": "ipv4",
1609               "channel-type": 1,
1610               "connection-id": 1804289383,
1611               "host": "127.0.0.1",
1612               "channel-id": 0,
1613               "tls": true
1614            },
1615            {
1616               "port": "36710",
1617               "family": "ipv4",
1618               "channel-type": 4,
1619               "connection-id": 1804289383,
1620               "host": "127.0.0.1",
1621               "channel-id": 0,
1622               "tls": false
1623            },
1624            [ ... more channels follow ... ]
1625         ]
1626      }
1627   }
1628
1629EQMP
1630
1631SQMP
1632query-name
1633----------
1634
1635Show VM name.
1636
1637Return a json-object with the following information:
1638
1639- "name": VM's name (json-string, optional)
1640
1641Example:
1642
1643-> { "execute": "query-name" }
1644<- { "return": { "name": "qemu-name" } }
1645
1646EQMP
1647
1648SQMP
1649query-uuid
1650----------
1651
1652Show VM UUID.
1653
1654Return a json-object with the following information:
1655
1656- "UUID": Universally Unique Identifier (json-string)
1657
1658Example:
1659
1660-> { "execute": "query-uuid" }
1661<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1662
1663EQMP
1664
1665SQMP
1666query-migrate
1667-------------
1668
1669Migration status.
1670
1671Return a json-object. If migration is active there will be another json-object
1672with RAM migration status and if block migration is active another one with
1673block migration status.
1674
1675The main json-object contains the following:
1676
1677- "status": migration status (json-string)
1678     - Possible values: "active", "completed", "failed", "cancelled"
1679- "ram": only present if "status" is "active", it is a json-object with the
1680  following RAM information (in bytes):
1681         - "transferred": amount transferred (json-int)
1682         - "remaining": amount remaining (json-int)
1683         - "total": total (json-int)
1684- "disk": only present if "status" is "active" and it is a block migration,
1685  it is a json-object with the following disk information (in bytes):
1686         - "transferred": amount transferred (json-int)
1687         - "remaining": amount remaining (json-int)
1688         - "total": total (json-int)
1689
1690Examples:
1691
16921. Before the first migration
1693
1694-> { "execute": "query-migrate" }
1695<- { "return": {} }
1696
16972. Migration is done and has succeeded
1698
1699-> { "execute": "query-migrate" }
1700<- { "return": { "status": "completed" } }
1701
17023. Migration is done and has failed
1703
1704-> { "execute": "query-migrate" }
1705<- { "return": { "status": "failed" } }
1706
17074. Migration is being performed and is not a block migration:
1708
1709-> { "execute": "query-migrate" }
1710<- {
1711      "return":{
1712         "status":"active",
1713         "ram":{
1714            "transferred":123,
1715            "remaining":123,
1716            "total":246
1717         }
1718      }
1719   }
1720
17215. Migration is being performed and is a block migration:
1722
1723-> { "execute": "query-migrate" }
1724<- {
1725      "return":{
1726         "status":"active",
1727         "ram":{
1728            "total":1057024,
1729            "remaining":1053304,
1730            "transferred":3720
1731         },
1732         "disk":{
1733            "total":20971520,
1734            "remaining":20880384,
1735            "transferred":91136
1736         }
1737      }
1738   }
1739
1740EQMP
1741
1742SQMP
1743query-balloon
1744-------------
1745
1746Show balloon information.
1747
1748Make an asynchronous request for balloon info. When the request completes a
1749json-object will be returned containing the following data:
1750
1751- "actual": current balloon value in bytes (json-int)
1752- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
1753- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
1754- "major_page_faults": Number of major faults (json-int, optional)
1755- "minor_page_faults": Number of minor faults (json-int, optional)
1756- "free_mem": Total amount of free and unused memory in
1757              bytes (json-int, optional)
1758- "total_mem": Total amount of available memory in bytes (json-int, optional)
1759
1760Example:
1761
1762-> { "execute": "query-balloon" }
1763<- {
1764      "return":{
1765         "actual":1073741824,
1766         "mem_swapped_in":0,
1767         "mem_swapped_out":0,
1768         "major_page_faults":142,
1769         "minor_page_faults":239245,
1770         "free_mem":1014185984,
1771         "total_mem":1044668416
1772      }
1773   }
1774
1775EQMP
1776
1777