Revision b40292e7 qemu-monitor.hx

b/qemu-monitor.hx
1 1
HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 2
HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 3
HXCOMM discarded from C version
4
HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
5
HXCOMM does not show up in the other formats.
4 6
HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
5 7
HXCOMM monitor commands
6 8
HXCOMM HXCOMM can be used for comments, discarded from both texi and C
7 9

  
10
SQMP
11
                        QMP Supported Commands
12
                        ----------------------
13

  
14
This document describes all commands currently supported by QMP.
15

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

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

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

  
28
Also, the following notation is used to denote data flow:
29

  
30
-> data issued by the Client
31
<- Server data response
32

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

  
36
NOTE: This document is temporary and will be replaced soon.
37

  
38
1. Regular Commands
39
===================
40

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

  
44
EQMP
45

  
8 46
STEXI
9 47
@table @option
10 48
ETEXI
......
51 89
@findex quit
52 90
Quit the emulator.
53 91
ETEXI
92
SQMP
93
quit
94
----
95

  
96
Quit the emulator.
97

  
98
Arguments: None.
99

  
100
Example:
101

  
102
-> { "execute": "quit" }
103
<- { "return": {} }
104

  
105
EQMP
54 106

  
55 107
    {
56 108
        .name       = "eject",
......
66 118
@findex eject
67 119
Eject a removable medium (use -f to force it).
68 120
ETEXI
121
SQMP
122
eject
123
-----
124

  
125
Eject a removable medium.
126

  
127
Arguments: 
128

  
129
- force: force ejection (json-bool, optional)
130
- device: device name (json-string)
131

  
132
Example:
133

  
134
-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
135
<- { "return": {} }
136

  
137
Note: The "force" argument defaults to false.
138

  
139
EQMP
69 140

  
70 141
    {
71 142
        .name       = "change",
......
113 184

  
114 185
@end table
115 186
ETEXI
187
SQMP
188
change
189
------
190

  
191
Change a removable medium or VNC configuration.
192

  
193
Arguments:
194

  
195
- "device": device name (json-string)
196
- "target": filename or item (json-string)
197
- "arg": additional argument (json-string, optional)
198

  
199
Examples:
200

  
201
1. Change a removable medium
202

  
203
-> { "execute": "change",
204
             "arguments": { "device": "ide1-cd0",
205
                            "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
206
<- { "return": {} }
207

  
208
2. Change VNC password
209

  
210
-> { "execute": "change",
211
             "arguments": { "device": "vnc", "target": "password",
212
                            "arg": "foobar1" } }
213
<- { "return": {} }
214

  
215
EQMP
116 216

  
117 217
    {
118 218
        .name       = "screendump",
......
128 228
@findex screendump
129 229
Save screen into PPM image @var{filename}.
130 230
ETEXI
231
SQMP
232
screendump
233
----------
234

  
235
Save screen into PPM image.
236

  
237
Arguments:
238

  
239
- "filename": file path (json-string)
240

  
241
Example:
242

  
243
-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
244
<- { "return": {} }
245

  
246
EQMP
131 247

  
132 248
    {
133 249
        .name       = "logfile",
......
232 348
@findex stop
233 349
Stop emulation.
234 350
ETEXI
351
SQMP
352
stop
353
----
354

  
355
Stop the emulator.
356

  
357
Arguments: None.
358

  
359
Example:
360

  
361
-> { "execute": "stop" }
362
<- { "return": {} }
363

  
364
EQMP
235 365

  
236 366
    {
237 367
        .name       = "c|cont",
......
247 377
@findex cont
248 378
Resume emulation.
249 379
ETEXI
380
SQMP
381
cont
382
----
383

  
384
Resume emulation.
385

  
386
Arguments: None.
387

  
388
Example:
389

  
390
-> { "execute": "cont" }
391
<- { "return": {} }
392

  
393
EQMP
250 394

  
251 395
    {
252 396
        .name       = "gdbserver",
......
421 565

  
422 566
Reset the system.
423 567
ETEXI
568
SQMP
569
system_reset
570
------------
571

  
572
Reset the system.
573

  
574
Arguments: None.
575

  
576
Example:
577

  
578
-> { "execute": "system_reset" }
579
<- { "return": {} }
580

  
581
EQMP
424 582

  
425 583
    {
426 584
        .name       = "system_powerdown",
......
437 595

  
438 596
Power down the system (if supported).
439 597
ETEXI
598
SQMP
599
system_powerdown
600
----------------
601

  
602
Send system power down event.
603

  
604
Arguments: None.
605

  
606
Example:
607

  
608
-> { "execute": "system_powerdown" }
609
<- { "return": {} }
610

  
611
EQMP
440 612

  
441 613
    {
442 614
        .name       = "sum",
......
501 673

  
502 674
Add device.
503 675
ETEXI
676
SQMP
677
device_add
678
----------
679

  
680
Add a device.
681

  
682
Arguments:
683

  
684
- "driver": the name of the new device's driver (json-string)
685
- "bus": the device's parent bus (device tree path, json-string, optional)
686
- "id": the device's ID, must be unique (json-string)
687
- device properties
688

  
689
Example:
690

  
691
-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
692
<- { "return": {} }
693

  
694
Notes:
695

  
696
(1) For detailed information about this command, please refer to the
697
    'docs/qdev-device-use.txt' file.
698

  
699
(2) It's possible to list device properties by running QEMU with the
700
    "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
701

  
702
EQMP
504 703

  
505 704
    {
506 705
        .name       = "device_del",
......
517 716

  
518 717
Remove device @var{id}.
519 718
ETEXI
719
SQMP
720
device_del
721
----------
722

  
723
Remove a device.
724

  
725
Arguments:
726

  
727
- "id": the device's ID (json-string)
728

  
729
Example:
730

  
731
-> { "execute": "device_del", "arguments": { "id": "net1" } }
732
<- { "return": {} }
733

  
734
EQMP
520 735

  
521 736
    {
522 737
        .name       = "cpu",
......
532 747
@findex cpu
533 748
Set the default CPU.
534 749
ETEXI
750
SQMP
751
cpu
752
---
753

  
754
Set the default CPU.
755

  
756
Arguments:
757

  
758
- "index": the CPU's index (json-int)
759

  
760
Example:
761

  
762
-> { "execute": "cpu", "arguments": { "index": 0 } }
763
<- { "return": {} }
764

  
765
Note: CPUs' indexes are obtained with the 'query-cpus' command.
766

  
767
EQMP
535 768

  
536 769
    {
537 770
        .name       = "mouse_move",
......
635 868
@findex memsave
636 869
save to disk virtual memory dump starting at @var{addr} of size @var{size}.
637 870
ETEXI
871
SQMP
872
memsave
873
-------
874

  
875
Save to disk virtual memory dump starting at 'val' of size 'size'.
876

  
877
Arguments:
878

  
879
- "val": the starting address (json-int)
880
- "size": the memory size, in bytes (json-int)
881
- "filename": file path (json-string)
882

  
883
Example:
884

  
885
-> { "execute": "memsave",
886
             "arguments": { "val": 10,
887
                            "size": 100,
888
                            "filename": "/tmp/virtual-mem-dump" } }
889
<- { "return": {} }
890

  
891
Note: Depends on the current CPU.
892

  
893
EQMP
638 894

  
639 895
    {
640 896
        .name       = "pmemsave",
......
650 906
@findex pmemsave
651 907
save to disk physical memory dump starting at @var{addr} of size @var{size}.
652 908
ETEXI
909
SQMP
910
pmemsave
911
--------
912

  
913
Save to disk physical memory dump starting at 'val' of size 'size'.
914

  
915
Arguments:
916

  
917
- "val": the starting address (json-int)
918
- "size": the memory size, in bytes (json-int)
919
- "filename": file path (json-string)
920

  
921
Example:
922

  
923
-> { "execute": "pmemsave",
924
             "arguments": { "val": 10,
925
                            "size": 100,
926
                            "filename": "/tmp/physical-mem-dump" } }
927
<- { "return": {} }
928

  
929
EQMP
653 930

  
654 931
    {
655 932
        .name       = "boot_set",
......
706 983
	-b for migration with full copy of disk
707 984
	-i for migration with incremental copy of disk (base image is shared)
708 985
ETEXI
986
SQMP
987
migrate
988
-------
989

  
990
Migrate to URI.
991

  
992
Arguments:
993

  
994
- "blk": block migration, full disk copy (json-bool, optional)
995
- "inc": incremental disk copy (json-bool, optional)
996
- "uri": Destination URI (json-string)
997

  
998
Example:
999

  
1000
-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
1001
<- { "return": {} }
1002

  
1003
Notes:
1004

  
1005
(1) The 'query-migrate' command should be used to check migration's progress
1006
    and final result (this information is provided by the 'status' member)
1007
(2) All boolean arguments default to false
1008
(3) The user Monitor's "detach" argument is invalid in QMP and should not
1009
    be used
1010

  
1011
EQMP
709 1012

  
710 1013
    {
711 1014
        .name       = "migrate_cancel",
......
721 1024
@findex migrate_cancel
722 1025
Cancel the current VM migration.
723 1026
ETEXI
1027
SQMP
1028
migrate_cancel
1029
--------------
1030

  
1031
Cancel the current migration.
1032

  
1033
Arguments: None.
1034

  
1035
Example:
1036

  
1037
-> { "execute": "migrate_cancel" }
1038
<- { "return": {} }
1039

  
1040
EQMP
724 1041

  
725 1042
    {
726 1043
        .name       = "migrate_set_speed",
......
736 1053
@findex migrate_set_speed
737 1054
Set maximum speed to @var{value} (in bytes) for migrations.
738 1055
ETEXI
1056
SQMP
1057
migrate_set_speed
1058
-----------------
1059

  
1060
Set maximum speed for migrations.
1061

  
1062
Arguments:
1063

  
1064
- "value": maximum speed, in bytes per second (json-number)
1065

  
1066
Example:
1067

  
1068
-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
1069
<- { "return": {} }
1070

  
1071
EQMP
739 1072

  
740 1073
    {
741 1074
        .name       = "migrate_set_downtime",
......
751 1084
@findex migrate_set_downtime
752 1085
Set maximum tolerated downtime (in seconds) for migration.
753 1086
ETEXI
1087
SQMP
1088
migrate_set_downtime
1089
--------------------
1090

  
1091
Set maximum tolerated downtime (in seconds) for migrations.
1092

  
1093
Arguments:
1094

  
1095
- "value": maximum downtime (json-number)
1096

  
1097
Example:
1098

  
1099
-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
1100
<- { "return": {} }
1101

  
1102
EQMP
754 1103

  
755 1104
#if defined(TARGET_I386)
756 1105
    {
......
846 1195
@findex netdev_add
847 1196
Add host network device.
848 1197
ETEXI
1198
SQMP
1199
netdev_add
1200
----------
1201

  
1202
Add host network device.
1203

  
1204
Arguments:
1205

  
1206
- "type": the device type, "tap", "user", ... (json-string)
1207
- "id": the device's ID, must be unique (json-string)
1208
- device options
1209

  
1210
Example:
1211

  
1212
-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
1213
<- { "return": {} }
1214

  
1215
Note: The supported device options are the same ones supported by the '-net'
1216
      command-line argument, which are listed in the '-help' output or QEMU's
1217
      manual
1218

  
1219
EQMP
849 1220

  
850 1221
    {
851 1222
        .name       = "netdev_del",
......
861 1232
@findex netdev_del
862 1233
Remove host network device.
863 1234
ETEXI
1235
SQMP
1236
netdev_del
1237
----------
1238

  
1239
Remove host network device.
1240

  
1241
Arguments:
1242

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

  
1245
Example:
1246

  
1247
-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
1248
<- { "return": {} }
1249

  
1250
EQMP
864 1251

  
865 1252
#ifdef CONFIG_SLIRP
866 1253
    {
......
908 1295
@findex balloon
909 1296
Request VM to change its memory allocation to @var{value} (in MB).
910 1297
ETEXI
1298
SQMP
1299
balloon
1300
-------
1301

  
1302
Request VM to change its memory allocation (in bytes).
1303

  
1304
Arguments:
1305

  
1306
- "value": New memory allocation (json-int)
1307

  
1308
Example:
1309

  
1310
-> { "execute": "balloon", "arguments": { "value": 536870912 } }
1311
<- { "return": {} }
1312

  
1313
EQMP
911 1314

  
912 1315
    {
913 1316
        .name       = "set_link",
......
923 1326
@findex set_link
924 1327
Switch link @var{name} on (i.e. up) or off (i.e. down).
925 1328
ETEXI
1329
SQMP
1330
set_link
1331
--------
1332

  
1333
Change the link status of a network adapter.
1334

  
1335
Arguments:
1336

  
1337
- "name": network device name (json-string)
1338
- "up": status is up (json-bool)
1339

  
1340
Example:
1341

  
1342
-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1343
<- { "return": {} }
1344

  
1345
EQMP
926 1346

  
927 1347
    {
928 1348
        .name       = "watchdog_action",
......
1052 1472
mechanism on unix sockets, it is stored using the name @var{fdname} for
1053 1473
later use by other monitor commands.
1054 1474
ETEXI
1475
SQMP
1476
getfd
1477
-----
1478

  
1479
Receive a file descriptor via SCM rights and assign it a name.
1480

  
1481
Arguments:
1482

  
1483
- "fdname": file descriptor name (json-string)
1484

  
1485
Example:
1486

  
1487
-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1488
<- { "return": {} }
1489

  
1490
EQMP
1055 1491

  
1056 1492
    {
1057 1493
        .name       = "closefd",
......
1069 1505
@code{getfd} command. This is only needed if the file descriptor was never
1070 1506
used by another monitor command.
1071 1507
ETEXI
1508
SQMP
1509
closefd
1510
-------
1511

  
1512
Close a file descriptor previously passed via SCM rights.
1513

  
1514
Arguments:
1515

  
1516
- "fdname": file descriptor name (json-string)
1517

  
1518
Example:
1519

  
1520
-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1521
<- { "return": {} }
1522

  
1523
EQMP
1072 1524

  
1073 1525
    {
1074 1526
        .name       = "block_passwd",
......
1084 1536
@findex block_passwd
1085 1537
Set the encrypted device @var{device} password to @var{password}
1086 1538
ETEXI
1539
SQMP
1540
block_passwd
1541
------------
1542

  
1543
Set the password of encrypted block devices.
1544

  
1545
Arguments:
1546

  
1547
- "device": device name (json-string)
1548
- "password": password (json-string)
1549

  
1550
Example:
1551

  
1552
-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1553
                                               "password": "12345" } }
1554
<- { "return": {} }
1555

  
1556
EQMP
1087 1557

  
1088 1558
    {
1089 1559
        .name       = "qmp_capabilities",
......
1099 1569
@findex qmp_capabilities
1100 1570
Enable the specified QMP capabilities
1101 1571
ETEXI
1572
SQMP
1573
qmp_capabilities
1574
----------------
1575

  
1576
Enable QMP capabilities.
1577

  
1578
Arguments: None.
1579

  
1580
Example:
1581

  
1582
-> { "execute": "qmp_capabilities" }
1583
<- { "return": {} }
1584

  
1585
Note: This command must be issued before issuing any other command.
1586

  
1587
EQMP
1102 1588

  
1103 1589

  
1104 1590
HXCOMM Keep the 'info' command at the end!
1105 1591
HXCOMM This is required for the QMP documentation layout.
1106 1592

  
1593
SQMP
1594

  
1595
2. Query Commands
1596
=================
1597

  
1598
EQMP
1599

  
1107 1600
    {
1108 1601
        .name       = "info",
1109 1602
        .args_type  = "item:s?",
......
1121 1614
@table @option
1122 1615
@item info version
1123 1616
show the version of QEMU
1617
ETEXI
1618
SQMP
1619
query-version
1620
-------------
1621

  
1622
Show QEMU version.
1623

  
1624
Return a json-object with the following information:
1625

  
1626
- "qemu": QEMU's version (json-string)
1627
- "package": package's version (json-string)
1628

  
1629
Example:
1630

  
1631
-> { "execute": "query-version" }
1632
<- { "return": { "qemu": "0.11.50", "package": "" } }
1633

  
1634
EQMP
1635

  
1636
STEXI
1124 1637
@item info commands
1125 1638
list QMP available commands
1639
ETEXI
1640
SQMP
1641
query-commands
1642
--------------
1643

  
1644
List QMP available commands.
1645

  
1646
Each command is represented by a json-object, the returned value is a json-array
1647
of all commands.
1648

  
1649
Each json-object contain:
1650

  
1651
- "name": command's name (json-string)
1652

  
1653
Example:
1654

  
1655
-> { "execute": "query-commands" }
1656
<- {
1657
      "return":[
1658
         {
1659
            "name":"query-balloon"
1660
         },
1661
         {
1662
            "name":"system_powerdown"
1663
         }
1664
      ]
1665
   }
1666

  
1667
Note: This example has been shortened as the real response is too long.
1668

  
1669
EQMP
1670

  
1671
STEXI
1126 1672
@item info network
1127 1673
show the various VLANs and the associated devices
1674
ETEXI
1675

  
1676
STEXI
1128 1677
@item info chardev
1129 1678
show the character devices
1679
ETEXI
1680
SQMP
1681
query-chardev
1682
-------------
1683

  
1684
Each device is represented by a json-object. The returned value is a json-array
1685
of all devices.
1686

  
1687
Each json-object contain the following:
1688

  
1689
- "label": device's label (json-string)
1690
- "filename": device's file (json-string)
1691

  
1692
Example:
1693

  
1694
-> { "execute": "query-chardev" }
1695
<- {
1696
      "return":[
1697
         {
1698
            "label":"monitor",
1699
            "filename":"stdio"
1700
         },
1701
         {
1702
            "label":"serial0",
1703
            "filename":"vc"
1704
         }
1705
      ]
1706
   }
1707

  
1708
EQMP
1709

  
1710
STEXI
1130 1711
@item info block
1131 1712
show the block devices
1713
ETEXI
1714
SQMP
1715
query-block
1716
-----------
1717

  
1718
Show the block devices.
1719

  
1720
Each block device information is stored in a json-object and the returned value
1721
is a json-array of all devices.
1722

  
1723
Each json-object contain the following:
1724

  
1725
- "device": device name (json-string)
1726
- "type": device type (json-string)
1727
         - Possible values: "hd", "cdrom", "floppy", "unknown"
1728
- "removable": true if the device is removable, false otherwise (json-bool)
1729
- "locked": true if the device is locked, false otherwise (json-bool)
1730
- "inserted": only present if the device is inserted, it is a json-object
1731
   containing the following:
1732
         - "file": device file name (json-string)
1733
         - "ro": true if read-only, false otherwise (json-bool)
1734
         - "drv": driver format name (json-string)
1735
             - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1736
                                "file", "file", "ftp", "ftps", "host_cdrom",
1737
                                "host_device", "host_floppy", "http", "https",
1738
                                "nbd", "parallels", "qcow", "qcow2", "raw",
1739
                                "tftp", "vdi", "vmdk", "vpc", "vvfat"
1740
         - "backing_file": backing file name (json-string, optional)
1741
         - "encrypted": true if encrypted, false otherwise (json-bool)
1742

  
1743
Example:
1744

  
1745
-> { "execute": "query-block" }
1746
<- {
1747
      "return":[
1748
         {
1749
            "device":"ide0-hd0",
1750
            "locked":false,
1751
            "removable":false,
1752
            "inserted":{
1753
               "ro":false,
1754
               "drv":"qcow2",
1755
               "encrypted":false,
1756
               "file":"disks/test.img"
1757
            },
1758
            "type":"hd"
1759
         },
1760
         {
1761
            "device":"ide1-cd0",
1762
            "locked":false,
1763
            "removable":true,
1764
            "type":"cdrom"
1765
         },
1766
         {
1767
            "device":"floppy0",
1768
            "locked":false,
1769
            "removable":true,
1770
            "type": "floppy"
1771
         },
1772
         {
1773
            "device":"sd0",
1774
            "locked":false,
1775
            "removable":true,
1776
            "type":"floppy"
1777
         }
1778
      ]
1779
   }
1780

  
1781
EQMP
1782

  
1783
STEXI
1132 1784
@item info blockstats
1133 1785
show block device statistics
1786
ETEXI
1787
SQMP
1788
query-blockstats
1789
----------------
1790

  
1791
Show block device statistics.
1792

  
1793
Each device statistic information is stored in a json-object and the returned
1794
value is a json-array of all devices.
1795

  
1796
Each json-object contain the following:
1797

  
1798
- "device": device name (json-string)
1799
- "stats": A json-object with the statistics information, it contains:
1800
    - "rd_bytes": bytes read (json-int)
1801
    - "wr_bytes": bytes written (json-int)
1802
    - "rd_operations": read operations (json-int)
1803
    - "wr_operations": write operations (json-int)
1804
    - "wr_highest_offset": Highest offset of a sector written since the
1805
                           BlockDriverState has been opened (json-int)
1806
- "parent": Contains recursively the statistics of the underlying
1807
            protocol (e.g. the host file for a qcow2 image). If there is
1808
            no underlying protocol, this field is omitted
1809
            (json-object, optional)
1810

  
1811
Example:
1812

  
1813
-> { "execute": "query-blockstats" }
1814
<- {
1815
      "return":[
1816
         {
1817
            "device":"ide0-hd0",
1818
            "parent":{
1819
               "stats":{
1820
                  "wr_highest_offset":3686448128,
1821
                  "wr_bytes":9786368,
1822
                  "wr_operations":751,
1823
                  "rd_bytes":122567168,
1824
                  "rd_operations":36772
1825
               }
1826
            },
1827
            "stats":{
1828
               "wr_highest_offset":2821110784,
1829
               "wr_bytes":9786368,
1830
               "wr_operations":692,
1831
               "rd_bytes":122739200,
1832
               "rd_operations":36604
1833
            }
1834
         },
1835
         {
1836
            "device":"ide1-cd0",
1837
            "stats":{
1838
               "wr_highest_offset":0,
1839
               "wr_bytes":0,
1840
               "wr_operations":0,
1841
               "rd_bytes":0,
1842
               "rd_operations":0
1843
            }
1844
         },
1845
         {
1846
            "device":"floppy0",
1847
            "stats":{
1848
               "wr_highest_offset":0,
1849
               "wr_bytes":0,
1850
               "wr_operations":0,
1851
               "rd_bytes":0,
1852
               "rd_operations":0
1853
            }
1854
         },
1855
         {
1856
            "device":"sd0",
1857
            "stats":{
1858
               "wr_highest_offset":0,
1859
               "wr_bytes":0,
1860
               "wr_operations":0,
1861
               "rd_bytes":0,
1862
               "rd_operations":0
1863
            }
1864
         }
1865
      ]
1866
   }
1867

  
1868
EQMP
1869

  
1870
STEXI
1134 1871
@item info registers
1135 1872
show the cpu registers
1136 1873
@item info cpus
1137 1874
show infos for each CPU
1875
ETEXI
1876
SQMP
1877
query-cpus
1878
----------
1879

  
1880
Show CPU information.
1881

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

  
1884
- "CPU": CPU index (json-int)
1885
- "current": true if this is the current CPU, false otherwise (json-bool)
1886
- "halted": true if the cpu is halted, false otherwise (json-bool)
1887
- Current program counter. The key's name depends on the architecture:
1888
     "pc": i386/x86_64 (json-int)
1889
     "nip": PPC (json-int)
1890
     "pc" and "npc": sparc (json-int)
1891
     "PC": mips (json-int)
1892

  
1893
Example:
1894

  
1895
-> { "execute": "query-cpus" }
1896
<- {
1897
      "return":[
1898
         {
1899
            "CPU":0,
1900
            "current":true,
1901
            "halted":false,
1902
            "pc":3227107138
1903
         },
1904
         {
1905
            "CPU":1,
1906
            "current":false,
1907
            "halted":true,
1908
            "pc":7108165
1909
         }
1910
      ]
1911
   }
1912

  
1913
EQMP
1914

  
1915
STEXI
1138 1916
@item info history
1139 1917
show the command line history
1140 1918
@item info irq
1141 1919
show the interrupts statistics (if available)
1142 1920
@item info pic
1143 1921
show i8259 (PIC) state
1922
ETEXI
1923

  
1924
STEXI
1144 1925
@item info pci
1145 1926
show emulated PCI device info
1927
ETEXI
1928
SQMP
1929
query-pci
1930
---------
1931

  
1932
PCI buses and devices information.
1933

  
1934
The returned value is a json-array of all buses. Each bus is represented by
1935
a json-object, which has a key with a json-array of all PCI devices attached
1936
to it. Each device is represented by a json-object.
1937

  
1938
The bus json-object contains the following:
1939

  
1940
- "bus": bus number (json-int)
1941
- "devices": a json-array of json-objects, each json-object represents a
1942
             PCI device
1943

  
1944
The PCI device json-object contains the following:
1945

  
1946
- "bus": identical to the parent's bus number (json-int)
1947
- "slot": slot number (json-int)
1948
- "function": function number (json-int)
1949
- "class_info": a json-object containing:
1950
     - "desc": device class description (json-string, optional)
1951
     - "class": device class number (json-int)
1952
- "id": a json-object containing:
1953
     - "device": device ID (json-int)
1954
     - "vendor": vendor ID (json-int)
1955
- "irq": device's IRQ if assigned (json-int, optional)
1956
- "qdev_id": qdev id string (json-string)
1957
- "pci_bridge": It's a json-object, only present if this device is a
1958
                PCI bridge, contains:
1959
     - "bus": bus number (json-int)
1960
     - "secondary": secondary bus number (json-int)
1961
     - "subordinate": subordinate bus number (json-int)
1962
     - "io_range": I/O memory range information, a json-object with the
1963
                   following members:
1964
                 - "base": base address, in bytes (json-int)
1965
                 - "limit": limit address, in bytes (json-int)
1966
     - "memory_range": memory range information, a json-object with the
1967
                       following members:
1968
                 - "base": base address, in bytes (json-int)
1969
                 - "limit": limit address, in bytes (json-int)
1970
     - "prefetchable_range": Prefetchable memory range information, a
1971
                             json-object with the following members:
1972
                 - "base": base address, in bytes (json-int)
1973
                 - "limit": limit address, in bytes (json-int)
1974
     - "devices": a json-array of PCI devices if there's any attached, each
1975
                  each element is represented by a json-object, which contains
1976
                  the same members of the 'PCI device json-object' described
1977
                  above (optional)
1978
- "regions": a json-array of json-objects, each json-object represents a
1979
             memory region of this device
1980

  
1981
The memory range json-object contains the following:
1982

  
1983
- "base": base memory address (json-int)
1984
- "limit": limit value (json-int)
1985

  
1986
The region json-object can be an I/O region or a memory region, an I/O region
1987
json-object contains the following:
1988

  
1989
- "type": "io" (json-string, fixed)
1990
- "bar": BAR number (json-int)
1991
- "address": memory address (json-int)
1992
- "size": memory size (json-int)
1993

  
1994
A memory region json-object contains the following:
1995

  
1996
- "type": "memory" (json-string, fixed)
1997
- "bar": BAR number (json-int)
1998
- "address": memory address (json-int)
1999
- "size": memory size (json-int)
2000
- "mem_type_64": true or false (json-bool)
2001
- "prefetch": true or false (json-bool)
2002

  
2003
Example:
2004

  
2005
-> { "execute": "query-pci" }
2006
<- {
2007
      "return":[
2008
         {
2009
            "bus":0,
2010
            "devices":[
2011
               {
2012
                  "bus":0,
2013
                  "qdev_id":"",
2014
                  "slot":0,
2015
                  "class_info":{
2016
                     "class":1536,
2017
                     "desc":"Host bridge"
2018
                  },
2019
                  "id":{
2020
                     "device":32902,
2021
                     "vendor":4663
2022
                  },
2023
                  "function":0,
2024
                  "regions":[
2025
   
2026
                  ]
2027
               },
2028
               {
2029
                  "bus":0,
2030
                  "qdev_id":"",
2031
                  "slot":1,
2032
                  "class_info":{
2033
                     "class":1537,
2034
                     "desc":"ISA bridge"
2035
                  },
2036
                  "id":{
2037
                     "device":32902,
2038
                     "vendor":28672
2039
                  },
2040
                  "function":0,
2041
                  "regions":[
2042
   
2043
                  ]
2044
               },
2045
               {
2046
                  "bus":0,
2047
                  "qdev_id":"",
2048
                  "slot":1,
2049
                  "class_info":{
2050
                     "class":257,
2051
                     "desc":"IDE controller"
2052
                  },
2053
                  "id":{
2054
                     "device":32902,
2055
                     "vendor":28688
2056
                  },
2057
                  "function":1,
2058
                  "regions":[
2059
                     {
2060
                        "bar":4,
2061
                        "size":16,
2062
                        "address":49152,
2063
                        "type":"io"
2064
                     }
2065
                  ]
2066
               },
2067
               {
2068
                  "bus":0,
2069
                  "qdev_id":"",
2070
                  "slot":2,
2071
                  "class_info":{
2072
                     "class":768,
2073
                     "desc":"VGA controller"
2074
                  },
2075
                  "id":{
2076
                     "device":4115,
2077
                     "vendor":184
2078
                  },
2079
                  "function":0,
2080
                  "regions":[
2081
                     {
2082
                        "prefetch":true,
2083
                        "mem_type_64":false,
2084
                        "bar":0,
2085
                        "size":33554432,
2086
                        "address":4026531840,
2087
                        "type":"memory"
2088
                     },
2089
                     {
2090
                        "prefetch":false,
2091
                        "mem_type_64":false,
2092
                        "bar":1,
2093
                        "size":4096,
2094
                        "address":4060086272,
2095
                        "type":"memory"
2096
                     },
2097
                     {
2098
                        "prefetch":false,
2099
                        "mem_type_64":false,
2100
                        "bar":6,
2101
                        "size":65536,
2102
                        "address":-1,
2103
                        "type":"memory"
2104
                     }
2105
                  ]
2106
               },
2107
               {
2108
                  "bus":0,
2109
                  "qdev_id":"",
2110
                  "irq":11,
2111
                  "slot":4,
2112
                  "class_info":{
2113
                     "class":1280,
2114
                     "desc":"RAM controller"
2115
                  },
2116
                  "id":{
2117
                     "device":6900,
2118
                     "vendor":4098
2119
                  },
2120
                  "function":0,
2121
                  "regions":[
2122
                     {
2123
                        "bar":0,
2124
                        "size":32,
2125
                        "address":49280,
2126
                        "type":"io"
2127
                     }
2128
                  ]
2129
               }
2130
            ]
2131
         }
2132
      ]
2133
   }
2134

  
2135
Note: This example has been shortened as the real response is too long.
2136

  
2137
EQMP
2138

  
2139
STEXI
1146 2140
@item info tlb
1147 2141
show virtual to physical memory mappings (i386 only)
1148 2142
@item info mem
1149 2143
show the active virtual memory mappings (i386 only)
2144
ETEXI
2145

  
2146
STEXI
1150 2147
@item info hpet
1151 2148
show state of HPET (i386 only)
2149
ETEXI
2150
SQMP
2151
query-hpet
2152
----------
2153

  
2154
Show HPET state.
2155

  
2156
Return a json-object with the following information:
2157

  
2158
- "enabled": true if hpet if enabled, false otherwise (json-bool)
2159

  
2160
Example:
2161

  
2162
-> { "execute": "query-hpet" }
2163
<- { "return": { "enabled": true } }
2164

  
2165
EQMP
2166

  
2167
STEXI
1152 2168
@item info jit
1153 2169
show dynamic compiler info
1154 2170
@item info kvm
1155 2171
show KVM information
1156 2172
@item info numa
1157 2173
show NUMA information
2174
ETEXI
2175

  
2176
STEXI
2177
@item info kvm
2178
show KVM information
2179
ETEXI
2180
SQMP
2181
query-kvm
2182
---------
2183

  
2184
Show KVM information.
2185

  
2186
Return a json-object with the following information:
2187

  
2188
- "enabled": true if KVM support is enabled, false otherwise (json-bool)
2189
- "present": true if QEMU has KVM support, false otherwise (json-bool)
2190

  
2191
Example:
2192

  
2193
-> { "execute": "query-kvm" }
2194
<- { "return": { "enabled": true, "present": true } }
2195

  
2196
EQMP
2197

  
2198
STEXI
1158 2199
@item info usb
1159 2200
show USB devices plugged on the virtual USB hub
1160 2201
@item info usbhost
......
1165 2206
show information about active capturing
1166 2207
@item info snapshots
1167 2208
show list of VM snapshots
2209
ETEXI
2210

  
2211
STEXI
1168 2212
@item info status
1169 2213
show the current VM status (running|paused)
2214
ETEXI
2215
SQMP
2216
query-status
2217
------------
2218

  
2219
Return a json-object with the following information:
2220

  
2221
- "running": true if the VM is running, or false if it is paused (json-bool)
2222
- "singlestep": true if the VM is in single step mode,
2223
                false otherwise (json-bool)
2224

  
2225
Example:
2226

  
2227
-> { "execute": "query-status" }
2228
<- { "return": { "running": true, "singlestep": false } }
2229

  
2230
EQMP
2231

  
2232
STEXI
1170 2233
@item info pcmcia
1171 2234
show guest PCMCIA status
2235
ETEXI
2236

  
2237
STEXI
1172 2238
@item info mice
1173 2239
show which guest mouse is receiving events
2240
ETEXI
2241
SQMP
2242
query-mice
2243
----------
2244

  
2245
Show VM mice information.
2246

  
2247
Each mouse is represented by a json-object, the returned value is a json-array
2248
of all mice.
2249

  
2250
The mouse json-object contains the following:
2251

  
2252
- "name": mouse's name (json-string)
2253
- "index": mouse's index (json-int)
2254
- "current": true if this mouse is receiving events, false otherwise (json-bool)
2255
- "absolute": true if the mouse generates absolute input events (json-bool)
2256

  
2257
Example:
2258

  
2259
-> { "execute": "query-mice" }
2260
<- {
2261
      "return":[
2262
         {
2263
            "name":"QEMU Microsoft Mouse",
2264
            "index":0,
2265
            "current":false,
2266
            "absolute":false
2267
         },
2268
         {
2269
            "name":"QEMU PS/2 Mouse",
2270
            "index":1,
2271
            "current":true,
2272
            "absolute":true
2273
         }
2274
      ]
2275
   }
2276

  
2277
EQMP
2278

  
2279
STEXI
1174 2280
@item info vnc
1175 2281
show the vnc server status
2282
ETEXI
2283
SQMP
2284
query-vnc
2285
---------
2286

  
2287
Show VNC server information.
2288

  
2289
Return a json-object with server information. Connected clients are returned
2290
as a json-array of json-objects.
2291

  
2292
The main json-object contains the following:
2293

  
2294
- "enabled": true or false (json-bool)
2295
- "host": server's IP address (json-string)
2296
- "family": address family (json-string)
2297
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
2298
- "service": server's port number (json-string)
2299
- "auth": authentication method (json-string)
2300
         - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2301
                            "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2302
                            "vencrypt+plain", "vencrypt+tls+none",
2303
                            "vencrypt+tls+plain", "vencrypt+tls+sasl",
2304
                            "vencrypt+tls+vnc", "vencrypt+x509+none",
2305
                            "vencrypt+x509+plain", "vencrypt+x509+sasl",
2306
                            "vencrypt+x509+vnc", "vnc"
2307
- "clients": a json-array of all connected clients
2308

  
2309
Clients are described by a json-object, each one contain the following:
2310

  
2311
- "host": client's IP address (json-string)
2312
- "family": address family (json-string)
2313
         - Possible values: "ipv4", "ipv6", "unix", "unknown"
2314
- "service": client's port number (json-string)
2315
- "x509_dname": TLS dname (json-string, optional)
2316
- "sasl_username": SASL username (json-string, optional)
2317

  
2318
Example:
2319

  
2320
-> { "execute": "query-vnc" }
2321
<- {
2322
      "return":{
2323
         "enabled":true,
2324
         "host":"0.0.0.0",
2325
         "service":"50402",
2326
         "auth":"vnc",
2327
         "family":"ipv4",
2328
         "clients":[
2329
            {
2330
               "host":"127.0.0.1",
2331
               "service":"50401",
2332
               "family":"ipv4"
2333
            }
2334
         ]
2335
      }
2336
   }
2337

  
2338
EQMP
2339

  
2340
STEXI
1176 2341
@item info name
1177 2342
show the current VM name
2343
ETEXI
2344
SQMP
2345
query-name
2346
----------
2347

  
2348
Show VM name.
2349

  
2350
Return a json-object with the following information:
2351

  
2352
- "name": VM's name (json-string, optional)
2353

  
2354
Example:
2355

  
2356
-> { "execute": "query-name" }
2357
<- { "return": { "name": "qemu-name" } }
2358

  
2359
EQMP
2360

  
2361
STEXI
1178 2362
@item info uuid
1179 2363
show the current VM UUID
2364
ETEXI
2365
SQMP
2366
query-uuid
2367
----------
2368

  
2369
Show VM UUID.
2370

  
2371
Return a json-object with the following information:
2372

  
2373
- "UUID": Universally Unique Identifier (json-string)
2374

  
2375
Example:
2376

  
2377
-> { "execute": "query-uuid" }
2378
<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2379

  
2380
EQMP
2381

  
2382
STEXI
1180 2383
@item info cpustats
1181 2384
show CPU statistics
1182 2385
@item info usernet
1183 2386
show user network stack connection states
2387
ETEXI
2388

  
2389
STEXI
1184 2390
@item info migrate
1185 2391
show migration status
2392
ETEXI
2393
SQMP
2394
query-migrate
2395
-------------
2396

  
2397
Migration status.
2398

  
2399
Return a json-object. If migration is active there will be another json-object
2400
with RAM migration status and if block migration is active another one with
2401
block migration status.
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff