Statistics
| Branch: | Revision:

root / qmp-commands.hx @ e120d449

History | View | Annotate | Download (53.4 kB)

1
HXCOMM QMP dispatch table and documentation
2
HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
3
HXCOMM does not show up in the other formats.
4

    
5
SQMP
6
                        QMP Supported Commands
7
                        ----------------------
8

    
9
This document describes all commands currently supported by QMP.
10

    
11
Most of the time their usage is exactly the same as in the user Monitor, this
12
means that any other document which also describe commands (the manpage,
13
QEMU's manual, etc) can and should be consulted.
14

    
15
QMP has two types of commands: regular and query commands. Regular commands
16
usually change the Virtual Machine's state someway, while query commands just
17
return information. The sections below are divided accordingly.
18

    
19
It's important to observe that all communication examples are formatted in
20
a reader-friendly way, so that they're easier to understand. However, in real
21
protocol usage, they're emitted as a single line.
22

    
23
Also, the following notation is used to denote data flow:
24

    
25
-> data issued by the Client
26
<- Server data response
27

    
28
Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
29
information on the Server command and response formats.
30

    
31
NOTE: This document is temporary and will be replaced soon.
32

    
33
1. Stability Considerations
34
===========================
35

    
36
The current QMP command set (described in this file) may be useful for a
37
number of use cases, however it's limited and several commands have bad
38
defined semantics, specially with regard to command completion.
39

    
40
These problems are going to be solved incrementally in the next QEMU releases
41
and we're going to establish a deprecation policy for badly defined commands.
42

    
43
If you're planning to adopt QMP, please observe the following:
44

    
45
    1. The deprecation policy will take effect 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

    
55
2. Regular Commands
56
===================
57

    
58
Server's responses in the examples below are always a success response, please
59
refer to the QMP specification for more details on error responses.
60

    
61
EQMP
62

    
63
    {
64
        .name       = "quit",
65
        .args_type  = "",
66
        .mhandler.cmd_new = qmp_marshal_input_quit,
67
    },
68

    
69
SQMP
70
quit
71
----
72

    
73
Quit the emulator.
74

    
75
Arguments: None.
76

    
77
Example:
78

    
79
-> { "execute": "quit" }
80
<- { "return": {} }
81

    
82
EQMP
83

    
84
    {
85
        .name       = "eject",
86
        .args_type  = "force:-f,device:B",
87
        .mhandler.cmd_new = qmp_marshal_input_eject,
88
    },
89

    
90
SQMP
91
eject
92
-----
93

    
94
Eject a removable medium.
95

    
96
Arguments: 
97

    
98
- force: force ejection (json-bool, optional)
99
- device: device name (json-string)
100

    
101
Example:
102

    
103
-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
104
<- { "return": {} }
105

    
106
Note: The "force" argument defaults to false.
107

    
108
EQMP
109

    
110
    {
111
        .name       = "change",
112
        .args_type  = "device:B,target:F,arg:s?",
113
        .mhandler.cmd_new = qmp_marshal_input_change,
114
    },
115

    
116
SQMP
117
change
118
------
119

    
120
Change a removable medium or VNC configuration.
121

    
122
Arguments:
123

    
124
- "device": device name (json-string)
125
- "target": filename or item (json-string)
126
- "arg": additional argument (json-string, optional)
127

    
128
Examples:
129

    
130
1. 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

    
137
2. Change VNC password
138

    
139
-> { "execute": "change",
140
             "arguments": { "device": "vnc", "target": "password",
141
                            "arg": "foobar1" } }
142
<- { "return": {} }
143

    
144
EQMP
145

    
146
    {
147
        .name       = "screendump",
148
        .args_type  = "filename:F",
149
        .params     = "filename",
150
        .help       = "save screen into PPM image 'filename'",
151
        .user_print = monitor_user_noop,
152
        .mhandler.cmd_new = do_screen_dump,
153
    },
154

    
155
SQMP
156
screendump
157
----------
158

    
159
Save screen into PPM image.
160

    
161
Arguments:
162

    
163
- "filename": file path (json-string)
164

    
165
Example:
166

    
167
-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
168
<- { "return": {} }
169

    
170
EQMP
171

    
172
    {
173
        .name       = "stop",
174
        .args_type  = "",
175
        .mhandler.cmd_new = qmp_marshal_input_stop,
176
    },
177

    
178
SQMP
179
stop
180
----
181

    
182
Stop the emulator.
183

    
184
Arguments: None.
185

    
186
Example:
187

    
188
-> { "execute": "stop" }
189
<- { "return": {} }
190

    
191
EQMP
192

    
193
    {
194
        .name       = "cont",
195
        .args_type  = "",
196
        .mhandler.cmd_new = qmp_marshal_input_cont,
197
    },
198

    
199
SQMP
200
cont
201
----
202

    
203
Resume emulation.
204

    
205
Arguments: None.
206

    
207
Example:
208

    
209
-> { "execute": "cont" }
210
<- { "return": {} }
211

    
212
EQMP
213

    
214
    {
215
        .name       = "system_wakeup",
216
        .args_type  = "",
217
        .mhandler.cmd_new = qmp_marshal_input_system_wakeup,
218
    },
219

    
220
SQMP
221
system_wakeup
222
-------------
223

    
224
Wakeup guest from suspend.
225

    
226
Arguments: None.
227

    
228
Example:
229

    
230
-> { "execute": "system_wakeup" }
231
<- { "return": {} }
232

    
233
EQMP
234

    
235
    {
236
        .name       = "system_reset",
237
        .args_type  = "",
238
        .mhandler.cmd_new = qmp_marshal_input_system_reset,
239
    },
240

    
241
SQMP
242
system_reset
243
------------
244

    
245
Reset the system.
246

    
247
Arguments: None.
248

    
249
Example:
250

    
251
-> { "execute": "system_reset" }
252
<- { "return": {} }
253

    
254
EQMP
255

    
256
    {
257
        .name       = "system_powerdown",
258
        .args_type  = "",
259
        .mhandler.cmd_new = qmp_marshal_input_system_powerdown,
260
    },
261

    
262
SQMP
263
system_powerdown
264
----------------
265

    
266
Send system power down event.
267

    
268
Arguments: None.
269

    
270
Example:
271

    
272
-> { "execute": "system_powerdown" }
273
<- { "return": {} }
274

    
275
EQMP
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

    
286
SQMP
287
device_add
288
----------
289

    
290
Add a device.
291

    
292
Arguments:
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

    
299
Example:
300

    
301
-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
302
<- { "return": {} }
303

    
304
Notes:
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

    
312
EQMP
313

    
314
    {
315
        .name       = "device_del",
316
        .args_type  = "id:s",
317
        .mhandler.cmd_new = qmp_marshal_input_device_del,
318
    },
319

    
320
SQMP
321
device_del
322
----------
323

    
324
Remove a device.
325

    
326
Arguments:
327

    
328
- "id": the device's ID (json-string)
329

    
330
Example:
331

    
332
-> { "execute": "device_del", "arguments": { "id": "net1" } }
333
<- { "return": {} }
334

    
335
EQMP
336

    
337
    {
338
        .name       = "cpu",
339
        .args_type  = "index:i",
340
        .mhandler.cmd_new = qmp_marshal_input_cpu,
341
    },
342

    
343
SQMP
344
cpu
345
---
346

    
347
Set the default CPU.
348

    
349
Arguments:
350

    
351
- "index": the CPU's index (json-int)
352

    
353
Example:
354

    
355
-> { "execute": "cpu", "arguments": { "index": 0 } }
356
<- { "return": {} }
357

    
358
Note: CPUs' indexes are obtained with the 'query-cpus' command.
359

    
360
EQMP
361

    
362
    {
363
        .name       = "memsave",
364
        .args_type  = "val:l,size:i,filename:s,cpu:i?",
365
        .mhandler.cmd_new = qmp_marshal_input_memsave,
366
    },
367

    
368
SQMP
369
memsave
370
-------
371

    
372
Save to disk virtual memory dump starting at 'val' of size 'size'.
373

    
374
Arguments:
375

    
376
- "val": the starting address (json-int)
377
- "size": the memory size, in bytes (json-int)
378
- "filename": file path (json-string)
379
- "cpu": virtual CPU index (json-int, optional)
380

    
381
Example:
382

    
383
-> { "execute": "memsave",
384
             "arguments": { "val": 10,
385
                            "size": 100,
386
                            "filename": "/tmp/virtual-mem-dump" } }
387
<- { "return": {} }
388

    
389
EQMP
390

    
391
    {
392
        .name       = "pmemsave",
393
        .args_type  = "val:l,size:i,filename:s",
394
        .mhandler.cmd_new = qmp_marshal_input_pmemsave,
395
    },
396

    
397
SQMP
398
pmemsave
399
--------
400

    
401
Save to disk physical memory dump starting at 'val' of size 'size'.
402

    
403
Arguments:
404

    
405
- "val": the starting address (json-int)
406
- "size": the memory size, in bytes (json-int)
407
- "filename": file path (json-string)
408

    
409
Example:
410

    
411
-> { "execute": "pmemsave",
412
             "arguments": { "val": 10,
413
                            "size": 100,
414
                            "filename": "/tmp/physical-mem-dump" } }
415
<- { "return": {} }
416

    
417
EQMP
418

    
419
    {
420
        .name       = "inject-nmi",
421
        .args_type  = "",
422
        .mhandler.cmd_new = qmp_marshal_input_inject_nmi,
423
    },
424

    
425
SQMP
426
inject-nmi
427
----------
428

    
429
Inject an NMI on guest's CPUs.
430

    
431
Arguments: None.
432

    
433
Example:
434

    
435
-> { "execute": "inject-nmi" }
436
<- { "return": {} }
437

    
438
Note: inject-nmi is only supported for x86 guest currently, it will
439
      returns "Unsupported" error for non-x86 guest.
440

    
441
EQMP
442

    
443
    {
444
        .name       = "xen-save-devices-state",
445
        .args_type  = "filename:F",
446
    .mhandler.cmd_new = qmp_marshal_input_xen_save_devices_state,
447
    },
448

    
449
SQMP
450
xen-save-devices-state
451
-------
452

    
453
Save the state of all devices to file. The RAM and the block devices
454
of the VM are not saved by this command.
455

    
456
Arguments:
457

    
458
- "filename": the file to save the state of the devices to as binary
459
data. See xen-save-devices-state.txt for a description of the binary
460
format.
461

    
462
Example:
463

    
464
-> { "execute": "xen-save-devices-state",
465
     "arguments": { "filename": "/tmp/save" } }
466
<- { "return": {} }
467

    
468
EQMP
469

    
470
    {
471
        .name       = "migrate",
472
        .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
473
        .mhandler.cmd_new = qmp_marshal_input_migrate,
474
    },
475

    
476
SQMP
477
migrate
478
-------
479

    
480
Migrate to URI.
481

    
482
Arguments:
483

    
484
- "blk": block migration, full disk copy (json-bool, optional)
485
- "inc": incremental disk copy (json-bool, optional)
486
- "uri": Destination URI (json-string)
487

    
488
Example:
489

    
490
-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
491
<- { "return": {} }
492

    
493
Notes:
494

    
495
(1) The 'query-migrate' command should be used to check migration's progress
496
    and final result (this information is provided by the 'status' member)
497
(2) All boolean arguments default to false
498
(3) The user Monitor's "detach" argument is invalid in QMP and should not
499
    be used
500

    
501
EQMP
502

    
503
    {
504
        .name       = "migrate_cancel",
505
        .args_type  = "",
506
        .mhandler.cmd_new = qmp_marshal_input_migrate_cancel,
507
    },
508

    
509
SQMP
510
migrate_cancel
511
--------------
512

    
513
Cancel the current migration.
514

    
515
Arguments: None.
516

    
517
Example:
518

    
519
-> { "execute": "migrate_cancel" }
520
<- { "return": {} }
521

    
522
EQMP
523

    
524
    {
525
        .name       = "migrate_set_speed",
526
        .args_type  = "value:o",
527
        .mhandler.cmd_new = qmp_marshal_input_migrate_set_speed,
528
    },
529

    
530
SQMP
531
migrate_set_speed
532
-----------------
533

    
534
Set maximum speed for migrations.
535

    
536
Arguments:
537

    
538
- "value": maximum speed, in bytes per second (json-int)
539

    
540
Example:
541

    
542
-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
543
<- { "return": {} }
544

    
545
EQMP
546

    
547
    {
548
        .name       = "migrate_set_downtime",
549
        .args_type  = "value:T",
550
        .mhandler.cmd_new = qmp_marshal_input_migrate_set_downtime,
551
    },
552

    
553
SQMP
554
migrate_set_downtime
555
--------------------
556

    
557
Set maximum tolerated downtime (in seconds) for migrations.
558

    
559
Arguments:
560

    
561
- "value": maximum downtime (json-number)
562

    
563
Example:
564

    
565
-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
566
<- { "return": {} }
567

    
568
EQMP
569

    
570
    {
571
        .name       = "client_migrate_info",
572
        .args_type  = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
573
        .params     = "protocol hostname port tls-port cert-subject",
574
        .help       = "send migration info to spice/vnc client",
575
        .user_print = monitor_user_noop,
576
        .mhandler.cmd_async = client_migrate_info,
577
        .flags      = MONITOR_CMD_ASYNC,
578
    },
579

    
580
SQMP
581
client_migrate_info
582
------------------
583

    
584
Set the spice/vnc connection info for the migration target.  The spice/vnc
585
server will ask the spice/vnc client to automatically reconnect using the
586
new parameters (if specified) once the vm migration finished successfully.
587

    
588
Arguments:
589

    
590
- "protocol":     protocol: "spice" or "vnc" (json-string)
591
- "hostname":     migration target hostname (json-string)
592
- "port":         spice/vnc tcp port for plaintext channels (json-int, optional)
593
- "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
594
- "cert-subject": server certificate subject (json-string, optional)
595

    
596
Example:
597

    
598
-> { "execute": "client_migrate_info",
599
     "arguments": { "protocol": "spice",
600
                    "hostname": "virt42.lab.kraxel.org",
601
                    "port": 1234 } }
602
<- { "return": {} }
603

    
604
EQMP
605

    
606
    {
607
        .name       = "netdev_add",
608
        .args_type  = "netdev:O",
609
        .params     = "[user|tap|socket],id=str[,prop=value][,...]",
610
        .help       = "add host network device",
611
        .user_print = monitor_user_noop,
612
        .mhandler.cmd_new = do_netdev_add,
613
    },
614

    
615
SQMP
616
netdev_add
617
----------
618

    
619
Add host network device.
620

    
621
Arguments:
622

    
623
- "type": the device type, "tap", "user", ... (json-string)
624
- "id": the device's ID, must be unique (json-string)
625
- device options
626

    
627
Example:
628

    
629
-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
630
<- { "return": {} }
631

    
632
Note: The supported device options are the same ones supported by the '-net'
633
      command-line argument, which are listed in the '-help' output or QEMU's
634
      manual
635

    
636
EQMP
637

    
638
    {
639
        .name       = "netdev_del",
640
        .args_type  = "id:s",
641
        .params     = "id",
642
        .help       = "remove host network device",
643
        .user_print = monitor_user_noop,
644
        .mhandler.cmd_new = do_netdev_del,
645
    },
646

    
647
SQMP
648
netdev_del
649
----------
650

    
651
Remove host network device.
652

    
653
Arguments:
654

    
655
- "id": the device's ID, must be unique (json-string)
656

    
657
Example:
658

    
659
-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
660
<- { "return": {} }
661

    
662

    
663
EQMP
664

    
665
    {
666
        .name       = "block_resize",
667
        .args_type  = "device:B,size:o",
668
        .mhandler.cmd_new = qmp_marshal_input_block_resize,
669
    },
670

    
671
SQMP
672
block_resize
673
------------
674

    
675
Resize a block image while a guest is running.
676

    
677
Arguments:
678

    
679
- "device": the device's ID, must be unique (json-string)
680
- "size": new size
681

    
682
Example:
683

    
684
-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
685
<- { "return": {} }
686

    
687
EQMP
688

    
689
    {
690
        .name       = "block-stream",
691
        .args_type  = "device:B,base:s?,speed:o?",
692
        .mhandler.cmd_new = qmp_marshal_input_block_stream,
693
    },
694

    
695
    {
696
        .name       = "block-job-set-speed",
697
        .args_type  = "device:B,speed:o",
698
        .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
699
    },
700

    
701
    {
702
        .name       = "block-job-cancel",
703
        .args_type  = "device:B",
704
        .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
705
    },
706
    {
707
        .name       = "transaction",
708
        .args_type  = "actions:q",
709
        .mhandler.cmd_new = qmp_marshal_input_transaction,
710
    },
711

    
712
SQMP
713
transaction
714
-----------
715

    
716
Atomically operate on one or more block devices.  The only supported
717
operation for now is snapshotting.  If there is any failure performing
718
any of the operations, all snapshots for the group are abandoned, and
719
the original disks pre-snapshot attempt are used.
720

    
721
A list of dictionaries is accepted, that contains the actions to be performed.
722
For snapshots this is the device, the file to use for the new snapshot,
723
and the format.  The default format, if not specified, is qcow2.
724

    
725
Each new snapshot defaults to being created by QEMU (wiping any
726
contents if the file already exists), but it is also possible to reuse
727
an externally-created file.  In the latter case, you should ensure that
728
the new image file has the same contents as the current one; QEMU cannot
729
perform any meaningful check.  Typically this is achieved by using the
730
current image file as the backing file for the new image.
731

    
732
Arguments:
733

    
734
actions array:
735
    - "type": the operation to perform.  The only supported
736
      value is "blockdev-snapshot-sync". (json-string)
737
    - "data": a dictionary.  The contents depend on the value
738
      of "type".  When "type" is "blockdev-snapshot-sync":
739
      - "device": device name to snapshot (json-string)
740
      - "snapshot-file": name of new image file (json-string)
741
      - "format": format of new image (json-string, optional)
742
      - "mode": whether and how QEMU should create the snapshot file
743
        (NewImageMode, optional, default "absolute-paths")
744

    
745
Example:
746

    
747
-> { "execute": "transaction",
748
     "arguments": { "actions": [
749
         { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd0",
750
                                         "snapshot-file": "/some/place/my-image",
751
                                         "format": "qcow2" } },
752
         { 'type': 'blockdev-snapshot-sync', 'data' : { "device": "ide-hd1",
753
                                         "snapshot-file": "/some/place/my-image2",
754
                                         "mode": "existing",
755
                                         "format": "qcow2" } } ] } }
756
<- { "return": {} }
757

    
758
EQMP
759

    
760
    {
761
        .name       = "blockdev-snapshot-sync",
762
        .args_type  = "device:B,snapshot-file:s,format:s?",
763
        .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
764
    },
765

    
766
SQMP
767
blockdev-snapshot-sync
768
----------------------
769

    
770
Synchronous snapshot of a block device. snapshot-file specifies the
771
target of the new image. If the file exists, or if it is a device, the
772
snapshot will be created in the existing file/device. If does not
773
exist, a new file will be created. format specifies the format of the
774
snapshot image, default is qcow2.
775

    
776
Arguments:
777

    
778
- "device": device name to snapshot (json-string)
779
- "snapshot-file": name of new image file (json-string)
780
- "mode": whether and how QEMU should create the snapshot file
781
  (NewImageMode, optional, default "absolute-paths")
782
- "format": format of new image (json-string, optional)
783

    
784
Example:
785

    
786
-> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
787
                                                         "snapshot-file":
788
                                                        "/some/place/my-image",
789
                                                        "format": "qcow2" } }
790
<- { "return": {} }
791

    
792
EQMP
793

    
794
    {
795
        .name       = "balloon",
796
        .args_type  = "value:M",
797
        .mhandler.cmd_new = qmp_marshal_input_balloon,
798
    },
799

    
800
SQMP
801
balloon
802
-------
803

    
804
Request VM to change its memory allocation (in bytes).
805

    
806
Arguments:
807

    
808
- "value": New memory allocation (json-int)
809

    
810
Example:
811

    
812
-> { "execute": "balloon", "arguments": { "value": 536870912 } }
813
<- { "return": {} }
814

    
815
EQMP
816

    
817
    {
818
        .name       = "set_link",
819
        .args_type  = "name:s,up:b",
820
        .mhandler.cmd_new = qmp_marshal_input_set_link,
821
    },
822

    
823
SQMP
824
set_link
825
--------
826

    
827
Change the link status of a network adapter.
828

    
829
Arguments:
830

    
831
- "name": network device name (json-string)
832
- "up": status is up (json-bool)
833

    
834
Example:
835

    
836
-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
837
<- { "return": {} }
838

    
839
EQMP
840

    
841
    {
842
        .name       = "getfd",
843
        .args_type  = "fdname:s",
844
        .params     = "getfd name",
845
        .help       = "receive a file descriptor via SCM rights and assign it a name",
846
        .user_print = monitor_user_noop,
847
        .mhandler.cmd_new = do_getfd,
848
    },
849

    
850
SQMP
851
getfd
852
-----
853

    
854
Receive a file descriptor via SCM rights and assign it a name.
855

    
856
Arguments:
857

    
858
- "fdname": file descriptor name (json-string)
859

    
860
Example:
861

    
862
-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
863
<- { "return": {} }
864

    
865
EQMP
866

    
867
    {
868
        .name       = "closefd",
869
        .args_type  = "fdname:s",
870
        .params     = "closefd name",
871
        .help       = "close a file descriptor previously passed via SCM rights",
872
        .user_print = monitor_user_noop,
873
        .mhandler.cmd_new = do_closefd,
874
    },
875

    
876
SQMP
877
closefd
878
-------
879

    
880
Close a file descriptor previously passed via SCM rights.
881

    
882
Arguments:
883

    
884
- "fdname": file descriptor name (json-string)
885

    
886
Example:
887

    
888
-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
889
<- { "return": {} }
890

    
891
EQMP
892

    
893
    {
894
        .name       = "block_passwd",
895
        .args_type  = "device:B,password:s",
896
        .mhandler.cmd_new = qmp_marshal_input_block_passwd,
897
    },
898

    
899
SQMP
900
block_passwd
901
------------
902

    
903
Set the password of encrypted block devices.
904

    
905
Arguments:
906

    
907
- "device": device name (json-string)
908
- "password": password (json-string)
909

    
910
Example:
911

    
912
-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
913
                                               "password": "12345" } }
914
<- { "return": {} }
915

    
916
EQMP
917

    
918
    {
919
        .name       = "block_set_io_throttle",
920
        .args_type  = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l",
921
        .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
922
    },
923

    
924
SQMP
925
block_set_io_throttle
926
------------
927

    
928
Change I/O throttle limits for a block drive.
929

    
930
Arguments:
931

    
932
- "device": device name (json-string)
933
- "bps":  total throughput limit in bytes per second(json-int)
934
- "bps_rd":  read throughput limit in bytes per second(json-int)
935
- "bps_wr":  read throughput limit in bytes per second(json-int)
936
- "iops":  total I/O operations per second(json-int)
937
- "iops_rd":  read I/O operations per second(json-int)
938
- "iops_wr":  write I/O operations per second(json-int)
939

    
940
Example:
941

    
942
-> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
943
                                               "bps": "1000000",
944
                                               "bps_rd": "0",
945
                                               "bps_wr": "0",
946
                                               "iops": "0",
947
                                               "iops_rd": "0",
948
                                               "iops_wr": "0" } }
949
<- { "return": {} }
950

    
951
EQMP
952

    
953
    {
954
        .name       = "set_password",
955
        .args_type  = "protocol:s,password:s,connected:s?",
956
        .mhandler.cmd_new = qmp_marshal_input_set_password,
957
    },
958

    
959
SQMP
960
set_password
961
------------
962

    
963
Set the password for vnc/spice protocols.
964

    
965
Arguments:
966

    
967
- "protocol": protocol name (json-string)
968
- "password": password (json-string)
969
- "connected": [ keep | disconnect | fail ] (josn-string, optional)
970

    
971
Example:
972

    
973
-> { "execute": "set_password", "arguments": { "protocol": "vnc",
974
                                               "password": "secret" } }
975
<- { "return": {} }
976

    
977
EQMP
978

    
979
    {
980
        .name       = "expire_password",
981
        .args_type  = "protocol:s,time:s",
982
        .mhandler.cmd_new = qmp_marshal_input_expire_password,
983
    },
984

    
985
SQMP
986
expire_password
987
---------------
988

    
989
Set the password expire time for vnc/spice protocols.
990

    
991
Arguments:
992

    
993
- "protocol": protocol name (json-string)
994
- "time": [ now | never | +secs | secs ] (json-string)
995

    
996
Example:
997

    
998
-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
999
                                                  "time": "+60" } }
1000
<- { "return": {} }
1001

    
1002
EQMP
1003

    
1004
    {
1005
        .name       = "add_client",
1006
        .args_type  = "protocol:s,fdname:s,skipauth:b?,tls:b?",
1007
        .params     = "protocol fdname skipauth tls",
1008
        .help       = "add a graphics client",
1009
        .user_print = monitor_user_noop,
1010
        .mhandler.cmd_new = add_graphics_client,
1011
    },
1012

    
1013
SQMP
1014
add_client
1015
----------
1016

    
1017
Add a graphics client
1018

    
1019
Arguments:
1020

    
1021
- "protocol": protocol name (json-string)
1022
- "fdname": file descriptor name (json-string)
1023
- "skipauth": whether to skip authentication (json-bool, optional)
1024
- "tls": whether to perform TLS (json-bool, optional)
1025

    
1026
Example:
1027

    
1028
-> { "execute": "add_client", "arguments": { "protocol": "vnc",
1029
                                             "fdname": "myclient" } }
1030
<- { "return": {} }
1031

    
1032
EQMP
1033
    {
1034
        .name       = "qmp_capabilities",
1035
        .args_type  = "",
1036
        .params     = "",
1037
        .help       = "enable QMP capabilities",
1038
        .user_print = monitor_user_noop,
1039
        .mhandler.cmd_new = do_qmp_capabilities,
1040
    },
1041

    
1042
SQMP
1043
qmp_capabilities
1044
----------------
1045

    
1046
Enable QMP capabilities.
1047

    
1048
Arguments: None.
1049

    
1050
Example:
1051

    
1052
-> { "execute": "qmp_capabilities" }
1053
<- { "return": {} }
1054

    
1055
Note: This command must be issued before issuing any other command.
1056

    
1057
EQMP
1058

    
1059
    {
1060
        .name       = "human-monitor-command",
1061
        .args_type  = "command-line:s,cpu-index:i?",
1062
        .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
1063
    },
1064

    
1065
SQMP
1066
human-monitor-command
1067
---------------------
1068

    
1069
Execute a Human Monitor command.
1070

    
1071
Arguments: 
1072

    
1073
- command-line: the command name and its arguments, just like the
1074
                Human Monitor's shell (json-string)
1075
- cpu-index: select the CPU number to be used by commands which access CPU
1076
             data, like 'info registers'. The Monitor selects CPU 0 if this
1077
             argument is not provided (json-int, optional)
1078

    
1079
Example:
1080

    
1081
-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1082
<- { "return": "kvm support: enabled\r\n" }
1083

    
1084
Notes:
1085

    
1086
(1) The Human Monitor is NOT an stable interface, this means that command
1087
    names, arguments and responses can change or be removed at ANY time.
1088
    Applications that rely on long term stability guarantees should NOT
1089
    use this command
1090

    
1091
(2) Limitations:
1092

    
1093
    o This command is stateless, this means that commands that depend
1094
      on state information (such as getfd) might not work
1095

    
1096
    o Commands that prompt the user for data (eg. 'cont' when the block
1097
      device is encrypted) don't currently work
1098

    
1099
3. Query Commands
1100
=================
1101

    
1102
HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1103
HXCOMM this! We will possibly move query commands definitions inside those
1104
HXCOMM sections, just like regular commands.
1105

    
1106
EQMP
1107

    
1108
SQMP
1109
query-version
1110
-------------
1111

    
1112
Show QEMU version.
1113

    
1114
Return a json-object with the following information:
1115

    
1116
- "qemu": A json-object containing three integer values:
1117
    - "major": QEMU's major version (json-int)
1118
    - "minor": QEMU's minor version (json-int)
1119
    - "micro": QEMU's micro version (json-int)
1120
- "package": package's version (json-string)
1121

    
1122
Example:
1123

    
1124
-> { "execute": "query-version" }
1125
<- {
1126
      "return":{
1127
         "qemu":{
1128
            "major":0,
1129
            "minor":11,
1130
            "micro":5
1131
         },
1132
         "package":""
1133
      }
1134
   }
1135

    
1136
EQMP
1137

    
1138
    {
1139
        .name       = "query-version",
1140
        .args_type  = "",
1141
        .mhandler.cmd_new = qmp_marshal_input_query_version,
1142
    },
1143

    
1144
SQMP
1145
query-commands
1146
--------------
1147

    
1148
List QMP available commands.
1149

    
1150
Each command is represented by a json-object, the returned value is a json-array
1151
of all commands.
1152

    
1153
Each json-object contain:
1154

    
1155
- "name": command's name (json-string)
1156

    
1157
Example:
1158

    
1159
-> { "execute": "query-commands" }
1160
<- {
1161
      "return":[
1162
         {
1163
            "name":"query-balloon"
1164
         },
1165
         {
1166
            "name":"system_powerdown"
1167
         }
1168
      ]
1169
   }
1170

    
1171
Note: This example has been shortened as the real response is too long.
1172

    
1173
EQMP
1174

    
1175
    {
1176
        .name       = "query-commands",
1177
        .args_type  = "",
1178
        .mhandler.cmd_new = qmp_marshal_input_query_commands,
1179
    },
1180

    
1181
SQMP
1182
query-chardev
1183
-------------
1184

    
1185
Each device is represented by a json-object. The returned value is a json-array
1186
of all devices.
1187

    
1188
Each json-object contain the following:
1189

    
1190
- "label": device's label (json-string)
1191
- "filename": device's file (json-string)
1192

    
1193
Example:
1194

    
1195
-> { "execute": "query-chardev" }
1196
<- {
1197
      "return":[
1198
         {
1199
            "label":"monitor",
1200
            "filename":"stdio"
1201
         },
1202
         {
1203
            "label":"serial0",
1204
            "filename":"vc"
1205
         }
1206
      ]
1207
   }
1208

    
1209
EQMP
1210

    
1211
    {
1212
        .name       = "query-chardev",
1213
        .args_type  = "",
1214
        .mhandler.cmd_new = qmp_marshal_input_query_chardev,
1215
    },
1216

    
1217
SQMP
1218
query-block
1219
-----------
1220

    
1221
Show the block devices.
1222

    
1223
Each block device information is stored in a json-object and the returned value
1224
is a json-array of all devices.
1225

    
1226
Each json-object contain the following:
1227

    
1228
- "device": device name (json-string)
1229
- "type": device type (json-string)
1230
         - deprecated, retained for backward compatibility
1231
         - Possible values: "unknown"
1232
- "removable": true if the device is removable, false otherwise (json-bool)
1233
- "locked": true if the device is locked, false otherwise (json-bool)
1234
- "tray-open": only present if removable, true if the device has a tray,
1235
               and it is open (json-bool)
1236
- "inserted": only present if the device is inserted, it is a json-object
1237
   containing the following:
1238
         - "file": device file name (json-string)
1239
         - "ro": true if read-only, false otherwise (json-bool)
1240
         - "drv": driver format name (json-string)
1241
             - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1242
                                "file", "file", "ftp", "ftps", "host_cdrom",
1243
                                "host_device", "host_floppy", "http", "https",
1244
                                "nbd", "parallels", "qcow", "qcow2", "raw",
1245
                                "tftp", "vdi", "vmdk", "vpc", "vvfat"
1246
         - "backing_file": backing file name (json-string, optional)
1247
         - "encrypted": true if encrypted, false otherwise (json-bool)
1248
         - "bps": limit total bytes per second (json-int)
1249
         - "bps_rd": limit read bytes per second (json-int)
1250
         - "bps_wr": limit write bytes per second (json-int)
1251
         - "iops": limit total I/O operations per second (json-int)
1252
         - "iops_rd": limit read operations per second (json-int)
1253
         - "iops_wr": limit write operations per second (json-int)
1254

    
1255
- "io-status": I/O operation status, only present if the device supports it
1256
               and the VM is configured to stop on errors. It's always reset
1257
               to "ok" when the "cont" command is issued (json_string, optional)
1258
             - Possible values: "ok", "failed", "nospace"
1259

    
1260
Example:
1261

    
1262
-> { "execute": "query-block" }
1263
<- {
1264
      "return":[
1265
         {
1266
            "io-status": "ok",
1267
            "device":"ide0-hd0",
1268
            "locked":false,
1269
            "removable":false,
1270
            "inserted":{
1271
               "ro":false,
1272
               "drv":"qcow2",
1273
               "encrypted":false,
1274
               "file":"disks/test.img",
1275
               "bps":1000000,
1276
               "bps_rd":0,
1277
               "bps_wr":0,
1278
               "iops":1000000,
1279
               "iops_rd":0,
1280
               "iops_wr":0,
1281
            },
1282
            "type":"unknown"
1283
         },
1284
         {
1285
            "io-status": "ok",
1286
            "device":"ide1-cd0",
1287
            "locked":false,
1288
            "removable":true,
1289
            "type":"unknown"
1290
         },
1291
         {
1292
            "device":"floppy0",
1293
            "locked":false,
1294
            "removable":true,
1295
            "type":"unknown"
1296
         },
1297
         {
1298
            "device":"sd0",
1299
            "locked":false,
1300
            "removable":true,
1301
            "type":"unknown"
1302
         }
1303
      ]
1304
   }
1305

    
1306
EQMP
1307

    
1308
    {
1309
        .name       = "query-block",
1310
        .args_type  = "",
1311
        .mhandler.cmd_new = qmp_marshal_input_query_block,
1312
    },
1313

    
1314
SQMP
1315
query-blockstats
1316
----------------
1317

    
1318
Show block device statistics.
1319

    
1320
Each device statistic information is stored in a json-object and the returned
1321
value is a json-array of all devices.
1322

    
1323
Each json-object contain the following:
1324

    
1325
- "device": device name (json-string)
1326
- "stats": A json-object with the statistics information, it contains:
1327
    - "rd_bytes": bytes read (json-int)
1328
    - "wr_bytes": bytes written (json-int)
1329
    - "rd_operations": read operations (json-int)
1330
    - "wr_operations": write operations (json-int)
1331
    - "flush_operations": cache flush operations (json-int)
1332
    - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1333
    - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1334
    - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1335
    - "wr_highest_offset": Highest offset of a sector written since the
1336
                           BlockDriverState has been opened (json-int)
1337
- "parent": Contains recursively the statistics of the underlying
1338
            protocol (e.g. the host file for a qcow2 image). If there is
1339
            no underlying protocol, this field is omitted
1340
            (json-object, optional)
1341

    
1342
Example:
1343

    
1344
-> { "execute": "query-blockstats" }
1345
<- {
1346
      "return":[
1347
         {
1348
            "device":"ide0-hd0",
1349
            "parent":{
1350
               "stats":{
1351
                  "wr_highest_offset":3686448128,
1352
                  "wr_bytes":9786368,
1353
                  "wr_operations":751,
1354
                  "rd_bytes":122567168,
1355
                  "rd_operations":36772
1356
                  "wr_total_times_ns":313253456
1357
                  "rd_total_times_ns":3465673657
1358
                  "flush_total_times_ns":49653
1359
                  "flush_operations":61,
1360
               }
1361
            },
1362
            "stats":{
1363
               "wr_highest_offset":2821110784,
1364
               "wr_bytes":9786368,
1365
               "wr_operations":692,
1366
               "rd_bytes":122739200,
1367
               "rd_operations":36604
1368
               "flush_operations":51,
1369
               "wr_total_times_ns":313253456
1370
               "rd_total_times_ns":3465673657
1371
               "flush_total_times_ns":49653
1372
            }
1373
         },
1374
         {
1375
            "device":"ide1-cd0",
1376
            "stats":{
1377
               "wr_highest_offset":0,
1378
               "wr_bytes":0,
1379
               "wr_operations":0,
1380
               "rd_bytes":0,
1381
               "rd_operations":0
1382
               "flush_operations":0,
1383
               "wr_total_times_ns":0
1384
               "rd_total_times_ns":0
1385
               "flush_total_times_ns":0
1386
            }
1387
         },
1388
         {
1389
            "device":"floppy0",
1390
            "stats":{
1391
               "wr_highest_offset":0,
1392
               "wr_bytes":0,
1393
               "wr_operations":0,
1394
               "rd_bytes":0,
1395
               "rd_operations":0
1396
               "flush_operations":0,
1397
               "wr_total_times_ns":0
1398
               "rd_total_times_ns":0
1399
               "flush_total_times_ns":0
1400
            }
1401
         },
1402
         {
1403
            "device":"sd0",
1404
            "stats":{
1405
               "wr_highest_offset":0,
1406
               "wr_bytes":0,
1407
               "wr_operations":0,
1408
               "rd_bytes":0,
1409
               "rd_operations":0
1410
               "flush_operations":0,
1411
               "wr_total_times_ns":0
1412
               "rd_total_times_ns":0
1413
               "flush_total_times_ns":0
1414
            }
1415
         }
1416
      ]
1417
   }
1418

    
1419
EQMP
1420

    
1421
    {
1422
        .name       = "query-blockstats",
1423
        .args_type  = "",
1424
        .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
1425
    },
1426

    
1427
SQMP
1428
query-cpus
1429
----------
1430

    
1431
Show CPU information.
1432

    
1433
Return a json-array. Each CPU is represented by a json-object, which contains:
1434

    
1435
- "CPU": CPU index (json-int)
1436
- "current": true if this is the current CPU, false otherwise (json-bool)
1437
- "halted": true if the cpu is halted, false otherwise (json-bool)
1438
- Current program counter. The key's name depends on the architecture:
1439
     "pc": i386/x86_64 (json-int)
1440
     "nip": PPC (json-int)
1441
     "pc" and "npc": sparc (json-int)
1442
     "PC": mips (json-int)
1443
- "thread_id": ID of the underlying host thread (json-int)
1444

    
1445
Example:
1446

    
1447
-> { "execute": "query-cpus" }
1448
<- {
1449
      "return":[
1450
         {
1451
            "CPU":0,
1452
            "current":true,
1453
            "halted":false,
1454
            "pc":3227107138
1455
            "thread_id":3134
1456
         },
1457
         {
1458
            "CPU":1,
1459
            "current":false,
1460
            "halted":true,
1461
            "pc":7108165
1462
            "thread_id":3135
1463
         }
1464
      ]
1465
   }
1466

    
1467
EQMP
1468

    
1469
    {
1470
        .name       = "query-cpus",
1471
        .args_type  = "",
1472
        .mhandler.cmd_new = qmp_marshal_input_query_cpus,
1473
    },
1474

    
1475
SQMP
1476
query-pci
1477
---------
1478

    
1479
PCI buses and devices information.
1480

    
1481
The returned value is a json-array of all buses. Each bus is represented by
1482
a json-object, which has a key with a json-array of all PCI devices attached
1483
to it. Each device is represented by a json-object.
1484

    
1485
The bus json-object contains the following:
1486

    
1487
- "bus": bus number (json-int)
1488
- "devices": a json-array of json-objects, each json-object represents a
1489
             PCI device
1490

    
1491
The PCI device json-object contains the following:
1492

    
1493
- "bus": identical to the parent's bus number (json-int)
1494
- "slot": slot number (json-int)
1495
- "function": function number (json-int)
1496
- "class_info": a json-object containing:
1497
     - "desc": device class description (json-string, optional)
1498
     - "class": device class number (json-int)
1499
- "id": a json-object containing:
1500
     - "device": device ID (json-int)
1501
     - "vendor": vendor ID (json-int)
1502
- "irq": device's IRQ if assigned (json-int, optional)
1503
- "qdev_id": qdev id string (json-string)
1504
- "pci_bridge": It's a json-object, only present if this device is a
1505
                PCI bridge, contains:
1506
     - "bus": bus number (json-int)
1507
     - "secondary": secondary bus number (json-int)
1508
     - "subordinate": subordinate bus number (json-int)
1509
     - "io_range": I/O memory range information, a json-object with the
1510
                   following members:
1511
                 - "base": base address, in bytes (json-int)
1512
                 - "limit": limit address, in bytes (json-int)
1513
     - "memory_range": memory range information, a json-object with the
1514
                       following members:
1515
                 - "base": base address, in bytes (json-int)
1516
                 - "limit": limit address, in bytes (json-int)
1517
     - "prefetchable_range": Prefetchable memory range information, a
1518
                             json-object with the following members:
1519
                 - "base": base address, in bytes (json-int)
1520
                 - "limit": limit address, in bytes (json-int)
1521
     - "devices": a json-array of PCI devices if there's any attached, each
1522
                  each element is represented by a json-object, which contains
1523
                  the same members of the 'PCI device json-object' described
1524
                  above (optional)
1525
- "regions": a json-array of json-objects, each json-object represents a
1526
             memory region of this device
1527

    
1528
The memory range json-object contains the following:
1529

    
1530
- "base": base memory address (json-int)
1531
- "limit": limit value (json-int)
1532

    
1533
The region json-object can be an I/O region or a memory region, an I/O region
1534
json-object contains the following:
1535

    
1536
- "type": "io" (json-string, fixed)
1537
- "bar": BAR number (json-int)
1538
- "address": memory address (json-int)
1539
- "size": memory size (json-int)
1540

    
1541
A memory region json-object contains the following:
1542

    
1543
- "type": "memory" (json-string, fixed)
1544
- "bar": BAR number (json-int)
1545
- "address": memory address (json-int)
1546
- "size": memory size (json-int)
1547
- "mem_type_64": true or false (json-bool)
1548
- "prefetch": true or false (json-bool)
1549

    
1550
Example:
1551

    
1552
-> { "execute": "query-pci" }
1553
<- {
1554
      "return":[
1555
         {
1556
            "bus":0,
1557
            "devices":[
1558
               {
1559
                  "bus":0,
1560
                  "qdev_id":"",
1561
                  "slot":0,
1562
                  "class_info":{
1563
                     "class":1536,
1564
                     "desc":"Host bridge"
1565
                  },
1566
                  "id":{
1567
                     "device":32902,
1568
                     "vendor":4663
1569
                  },
1570
                  "function":0,
1571
                  "regions":[
1572
   
1573
                  ]
1574
               },
1575
               {
1576
                  "bus":0,
1577
                  "qdev_id":"",
1578
                  "slot":1,
1579
                  "class_info":{
1580
                     "class":1537,
1581
                     "desc":"ISA bridge"
1582
                  },
1583
                  "id":{
1584
                     "device":32902,
1585
                     "vendor":28672
1586
                  },
1587
                  "function":0,
1588
                  "regions":[
1589
   
1590
                  ]
1591
               },
1592
               {
1593
                  "bus":0,
1594
                  "qdev_id":"",
1595
                  "slot":1,
1596
                  "class_info":{
1597
                     "class":257,
1598
                     "desc":"IDE controller"
1599
                  },
1600
                  "id":{
1601
                     "device":32902,
1602
                     "vendor":28688
1603
                  },
1604
                  "function":1,
1605
                  "regions":[
1606
                     {
1607
                        "bar":4,
1608
                        "size":16,
1609
                        "address":49152,
1610
                        "type":"io"
1611
                     }
1612
                  ]
1613
               },
1614
               {
1615
                  "bus":0,
1616
                  "qdev_id":"",
1617
                  "slot":2,
1618
                  "class_info":{
1619
                     "class":768,
1620
                     "desc":"VGA controller"
1621
                  },
1622
                  "id":{
1623
                     "device":4115,
1624
                     "vendor":184
1625
                  },
1626
                  "function":0,
1627
                  "regions":[
1628
                     {
1629
                        "prefetch":true,
1630
                        "mem_type_64":false,
1631
                        "bar":0,
1632
                        "size":33554432,
1633
                        "address":4026531840,
1634
                        "type":"memory"
1635
                     },
1636
                     {
1637
                        "prefetch":false,
1638
                        "mem_type_64":false,
1639
                        "bar":1,
1640
                        "size":4096,
1641
                        "address":4060086272,
1642
                        "type":"memory"
1643
                     },
1644
                     {
1645
                        "prefetch":false,
1646
                        "mem_type_64":false,
1647
                        "bar":6,
1648
                        "size":65536,
1649
                        "address":-1,
1650
                        "type":"memory"
1651
                     }
1652
                  ]
1653
               },
1654
               {
1655
                  "bus":0,
1656
                  "qdev_id":"",
1657
                  "irq":11,
1658
                  "slot":4,
1659
                  "class_info":{
1660
                     "class":1280,
1661
                     "desc":"RAM controller"
1662
                  },
1663
                  "id":{
1664
                     "device":6900,
1665
                     "vendor":4098
1666
                  },
1667
                  "function":0,
1668
                  "regions":[
1669
                     {
1670
                        "bar":0,
1671
                        "size":32,
1672
                        "address":49280,
1673
                        "type":"io"
1674
                     }
1675
                  ]
1676
               }
1677
            ]
1678
         }
1679
      ]
1680
   }
1681

    
1682
Note: This example has been shortened as the real response is too long.
1683

    
1684
EQMP
1685

    
1686
    {
1687
        .name       = "query-pci",
1688
        .args_type  = "",
1689
        .mhandler.cmd_new = qmp_marshal_input_query_pci,
1690
    },
1691

    
1692
SQMP
1693
query-kvm
1694
---------
1695

    
1696
Show KVM information.
1697

    
1698
Return a json-object with the following information:
1699

    
1700
- "enabled": true if KVM support is enabled, false otherwise (json-bool)
1701
- "present": true if QEMU has KVM support, false otherwise (json-bool)
1702

    
1703
Example:
1704

    
1705
-> { "execute": "query-kvm" }
1706
<- { "return": { "enabled": true, "present": true } }
1707

    
1708
EQMP
1709

    
1710
    {
1711
        .name       = "query-kvm",
1712
        .args_type  = "",
1713
        .mhandler.cmd_new = qmp_marshal_input_query_kvm,
1714
    },
1715

    
1716
SQMP
1717
query-status
1718
------------
1719

    
1720
Return a json-object with the following information:
1721

    
1722
- "running": true if the VM is running, or false if it is paused (json-bool)
1723
- "singlestep": true if the VM is in single step mode,
1724
                false otherwise (json-bool)
1725
- "status": one of the following values (json-string)
1726
    "debug" - QEMU is running on a debugger
1727
    "inmigrate" - guest is paused waiting for an incoming migration
1728
    "internal-error" - An internal error that prevents further guest
1729
    execution has occurred
1730
    "io-error" - the last IOP has failed and the device is configured
1731
    to pause on I/O errors
1732
    "paused" - guest has been paused via the 'stop' command
1733
    "postmigrate" - guest is paused following a successful 'migrate'
1734
    "prelaunch" - QEMU was started with -S and guest has not started
1735
    "finish-migrate" - guest is paused to finish the migration process
1736
    "restore-vm" - guest is paused to restore VM state
1737
    "running" - guest is actively running
1738
    "save-vm" - guest is paused to save the VM state
1739
    "shutdown" - guest is shut down (and -no-shutdown is in use)
1740
    "watchdog" - the watchdog action is configured to pause and
1741
     has been triggered
1742

    
1743
Example:
1744

    
1745
-> { "execute": "query-status" }
1746
<- { "return": { "running": true, "singlestep": false, "status": "running" } }
1747

    
1748
EQMP
1749
    
1750
    {
1751
        .name       = "query-status",
1752
        .args_type  = "",
1753
        .mhandler.cmd_new = qmp_marshal_input_query_status,
1754
    },
1755

    
1756
SQMP
1757
query-mice
1758
----------
1759

    
1760
Show VM mice information.
1761

    
1762
Each mouse is represented by a json-object, the returned value is a json-array
1763
of all mice.
1764

    
1765
The mouse json-object contains the following:
1766

    
1767
- "name": mouse's name (json-string)
1768
- "index": mouse's index (json-int)
1769
- "current": true if this mouse is receiving events, false otherwise (json-bool)
1770
- "absolute": true if the mouse generates absolute input events (json-bool)
1771

    
1772
Example:
1773

    
1774
-> { "execute": "query-mice" }
1775
<- {
1776
      "return":[
1777
         {
1778
            "name":"QEMU Microsoft Mouse",
1779
            "index":0,
1780
            "current":false,
1781
            "absolute":false
1782
         },
1783
         {
1784
            "name":"QEMU PS/2 Mouse",
1785
            "index":1,
1786
            "current":true,
1787
            "absolute":true
1788
         }
1789
      ]
1790
   }
1791

    
1792
EQMP
1793

    
1794
    {
1795
        .name       = "query-mice",
1796
        .args_type  = "",
1797
        .mhandler.cmd_new = qmp_marshal_input_query_mice,
1798
    },
1799

    
1800
SQMP
1801
query-vnc
1802
---------
1803

    
1804
Show VNC server information.
1805

    
1806
Return a json-object with server information. Connected clients are returned
1807
as a json-array of json-objects.
1808

    
1809
The main json-object contains the following:
1810

    
1811
- "enabled": true or false (json-bool)
1812
- "host": server's IP address (json-string)
1813
- "family": address family (json-string)
1814
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
1815
- "service": server's port number (json-string)
1816
- "auth": authentication method (json-string)
1817
         - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1818
                            "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1819
                            "vencrypt+plain", "vencrypt+tls+none",
1820
                            "vencrypt+tls+plain", "vencrypt+tls+sasl",
1821
                            "vencrypt+tls+vnc", "vencrypt+x509+none",
1822
                            "vencrypt+x509+plain", "vencrypt+x509+sasl",
1823
                            "vencrypt+x509+vnc", "vnc"
1824
- "clients": a json-array of all connected clients
1825

    
1826
Clients are described by a json-object, each one contain the following:
1827

    
1828
- "host": client's IP address (json-string)
1829
- "family": address family (json-string)
1830
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
1831
- "service": client's port number (json-string)
1832
- "x509_dname": TLS dname (json-string, optional)
1833
- "sasl_username": SASL username (json-string, optional)
1834

    
1835
Example:
1836

    
1837
-> { "execute": "query-vnc" }
1838
<- {
1839
      "return":{
1840
         "enabled":true,
1841
         "host":"0.0.0.0",
1842
         "service":"50402",
1843
         "auth":"vnc",
1844
         "family":"ipv4",
1845
         "clients":[
1846
            {
1847
               "host":"127.0.0.1",
1848
               "service":"50401",
1849
               "family":"ipv4"
1850
            }
1851
         ]
1852
      }
1853
   }
1854

    
1855
EQMP
1856

    
1857
    {
1858
        .name       = "query-vnc",
1859
        .args_type  = "",
1860
        .mhandler.cmd_new = qmp_marshal_input_query_vnc,
1861
    },
1862

    
1863
SQMP
1864
query-spice
1865
-----------
1866

    
1867
Show SPICE server information.
1868

    
1869
Return a json-object with server information. Connected clients are returned
1870
as a json-array of json-objects.
1871

    
1872
The main json-object contains the following:
1873

    
1874
- "enabled": true or false (json-bool)
1875
- "host": server's IP address (json-string)
1876
- "port": server's port number (json-int, optional)
1877
- "tls-port": server's port number (json-int, optional)
1878
- "auth": authentication method (json-string)
1879
         - Possible values: "none", "spice"
1880
- "channels": a json-array of all active channels clients
1881

    
1882
Channels are described by a json-object, each one contain the following:
1883

    
1884
- "host": client's IP address (json-string)
1885
- "family": address family (json-string)
1886
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
1887
- "port": client's port number (json-string)
1888
- "connection-id": spice connection id.  All channels with the same id
1889
                   belong to the same spice session (json-int)
1890
- "channel-type": channel type.  "1" is the main control channel, filter for
1891
                  this one if you want track spice sessions only (json-int)
1892
- "channel-id": channel id.  Usually "0", might be different needed when
1893
                multiple channels of the same type exist, such as multiple
1894
                display channels in a multihead setup (json-int)
1895
- "tls": whevener the channel is encrypted (json-bool)
1896

    
1897
Example:
1898

    
1899
-> { "execute": "query-spice" }
1900
<- {
1901
      "return": {
1902
         "enabled": true,
1903
         "auth": "spice",
1904
         "port": 5920,
1905
         "tls-port": 5921,
1906
         "host": "0.0.0.0",
1907
         "channels": [
1908
            {
1909
               "port": "54924",
1910
               "family": "ipv4",
1911
               "channel-type": 1,
1912
               "connection-id": 1804289383,
1913
               "host": "127.0.0.1",
1914
               "channel-id": 0,
1915
               "tls": true
1916
            },
1917
            {
1918
               "port": "36710",
1919
               "family": "ipv4",
1920
               "channel-type": 4,
1921
               "connection-id": 1804289383,
1922
               "host": "127.0.0.1",
1923
               "channel-id": 0,
1924
               "tls": false
1925
            },
1926
            [ ... more channels follow ... ]
1927
         ]
1928
      }
1929
   }
1930

    
1931
EQMP
1932

    
1933
#if defined(CONFIG_SPICE)
1934
    {
1935
        .name       = "query-spice",
1936
        .args_type  = "",
1937
        .mhandler.cmd_new = qmp_marshal_input_query_spice,
1938
    },
1939
#endif
1940

    
1941
SQMP
1942
query-name
1943
----------
1944

    
1945
Show VM name.
1946

    
1947
Return a json-object with the following information:
1948

    
1949
- "name": VM's name (json-string, optional)
1950

    
1951
Example:
1952

    
1953
-> { "execute": "query-name" }
1954
<- { "return": { "name": "qemu-name" } }
1955

    
1956
EQMP
1957

    
1958
    {
1959
        .name       = "query-name",
1960
        .args_type  = "",
1961
        .mhandler.cmd_new = qmp_marshal_input_query_name,
1962
    },
1963

    
1964
SQMP
1965
query-uuid
1966
----------
1967

    
1968
Show VM UUID.
1969

    
1970
Return a json-object with the following information:
1971

    
1972
- "UUID": Universally Unique Identifier (json-string)
1973

    
1974
Example:
1975

    
1976
-> { "execute": "query-uuid" }
1977
<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1978

    
1979
EQMP
1980

    
1981
    {
1982
        .name       = "query-uuid",
1983
        .args_type  = "",
1984
        .mhandler.cmd_new = qmp_marshal_input_query_uuid,
1985
    },
1986

    
1987
SQMP
1988
query-migrate
1989
-------------
1990

    
1991
Migration status.
1992

    
1993
Return a json-object. If migration is active there will be another json-object
1994
with RAM migration status and if block migration is active another one with
1995
block migration status.
1996

    
1997
The main json-object contains the following:
1998

    
1999
- "status": migration status (json-string)
2000
     - Possible values: "active", "completed", "failed", "cancelled"
2001
- "ram": only present if "status" is "active", it is a json-object with the
2002
  following RAM information (in bytes):
2003
         - "transferred": amount transferred (json-int)
2004
         - "remaining": amount remaining (json-int)
2005
         - "total": total (json-int)
2006
- "disk": only present if "status" is "active" and it is a block migration,
2007
  it is a json-object with the following disk information (in bytes):
2008
         - "transferred": amount transferred (json-int)
2009
         - "remaining": amount remaining (json-int)
2010
         - "total": total (json-int)
2011

    
2012
Examples:
2013

    
2014
1. Before the first migration
2015

    
2016
-> { "execute": "query-migrate" }
2017
<- { "return": {} }
2018

    
2019
2. Migration is done and has succeeded
2020

    
2021
-> { "execute": "query-migrate" }
2022
<- { "return": { "status": "completed" } }
2023

    
2024
3. Migration is done and has failed
2025

    
2026
-> { "execute": "query-migrate" }
2027
<- { "return": { "status": "failed" } }
2028

    
2029
4. Migration is being performed and is not a block migration:
2030

    
2031
-> { "execute": "query-migrate" }
2032
<- {
2033
      "return":{
2034
         "status":"active",
2035
         "ram":{
2036
            "transferred":123,
2037
            "remaining":123,
2038
            "total":246
2039
         }
2040
      }
2041
   }
2042

    
2043
5. Migration is being performed and is a block migration:
2044

    
2045
-> { "execute": "query-migrate" }
2046
<- {
2047
      "return":{
2048
         "status":"active",
2049
         "ram":{
2050
            "total":1057024,
2051
            "remaining":1053304,
2052
            "transferred":3720
2053
         },
2054
         "disk":{
2055
            "total":20971520,
2056
            "remaining":20880384,
2057
            "transferred":91136
2058
         }
2059
      }
2060
   }
2061

    
2062
EQMP
2063

    
2064
    {
2065
        .name       = "query-migrate",
2066
        .args_type  = "",
2067
        .mhandler.cmd_new = qmp_marshal_input_query_migrate,
2068
    },
2069

    
2070
SQMP
2071
query-balloon
2072
-------------
2073

    
2074
Show balloon information.
2075

    
2076
Make an asynchronous request for balloon info. When the request completes a
2077
json-object will be returned containing the following data:
2078

    
2079
- "actual": current balloon value in bytes (json-int)
2080
- "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
2081
- "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
2082
- "major_page_faults": Number of major faults (json-int, optional)
2083
- "minor_page_faults": Number of minor faults (json-int, optional)
2084
- "free_mem": Total amount of free and unused memory in
2085
              bytes (json-int, optional)
2086
- "total_mem": Total amount of available memory in bytes (json-int, optional)
2087

    
2088
Example:
2089

    
2090
-> { "execute": "query-balloon" }
2091
<- {
2092
      "return":{
2093
         "actual":1073741824,
2094
         "mem_swapped_in":0,
2095
         "mem_swapped_out":0,
2096
         "major_page_faults":142,
2097
         "minor_page_faults":239245,
2098
         "free_mem":1014185984,
2099
         "total_mem":1044668416
2100
      }
2101
   }
2102

    
2103
EQMP
2104

    
2105
    {
2106
        .name       = "query-balloon",
2107
        .args_type  = "",
2108
        .mhandler.cmd_new = qmp_marshal_input_query_balloon,
2109
    },
2110

    
2111
    {
2112
        .name       = "query-block-jobs",
2113
        .args_type  = "",
2114
        .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
2115
    },
2116

    
2117
    {
2118
        .name       = "qom-list",
2119
        .args_type  = "path:s",
2120
        .mhandler.cmd_new = qmp_marshal_input_qom_list,
2121
    },
2122

    
2123
    {
2124
        .name       = "qom-set",
2125
	.args_type  = "path:s,property:s,value:q",
2126
	.mhandler.cmd_new = qmp_qom_set,
2127
    },
2128

    
2129
    {
2130
        .name       = "qom-get",
2131
	.args_type  = "path:s,property:s",
2132
	.mhandler.cmd_new = qmp_qom_get,
2133
    },
2134

    
2135
    {
2136
        .name       = "change-vnc-password",
2137
        .args_type  = "password:s",
2138
        .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
2139
    },
2140
    {
2141
        .name       = "qom-list-types",
2142
        .args_type  = "implements:s?,abstract:b?",
2143
        .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
2144
    },