QEMU Monitor Protocol

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

QMP is JSON-based, its main features are:

Lightweight, text-based, easy to parse data format
Asynchronous events support

General Status

QMP is available in QEMU since version 0.13. However, it is still under development and not all Monitor commands are currently available.

QMP's specification can be found here.

Examples

In the following examples, 'C' stands for 'Client' and 'S' stands for 'Server'.

Server Greeting

S:	{"QMP": {"capabilities": []}}

Query version

C:	{ "execute": "query-version" }
S:	{"return": {"qemu": "0.11.50", "package": ""}}

Eject a device

C:	{ "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S:	{"return": "OK"}

TODO

High-level documentation
Convert all commands
Proper error handling support
Asynchronous commands
Libqmp

Development

The development takes place in the QMP unstable tree:

http://repo.or.cz/w/qemu/qmp-unstable.git

NOTE: all branches in this repository are constantly rebased.

Important branches:

master: contains a functional QMP implementation, its draft specification can be found here.
conversions-qobject: output in QObject conversions
conversions-qerror: error handling conversions

Project status (2009-12-07)

All the infrastructure has been merged and the protocol is already functional, but only a few commands will work.

Main building blocks

QObject Layer (merged)
QObject Monitor infrastructure (merged)
JSON encoder/decoder (merged)
Error framework (merged)

Conversion work

Input through QDict (merged)
Output in QObject style (in progress)
Error handling (in progress)

Conversion work detailed status

	Command	Info
Handlers	61	35
Fully Converted	7	14
Percentage	11%	40%

The following tables have a per-function status. There is one table for command handlers and another one for info handlers.

Status can be:

merged: already merged upstream
converted: converted but not merged yet
partial: not fully converted
never fails: does not need error handling

NOTE: Handlers used by Libvirt are marked with yellow.

Command handlers

Handler name	Output in QObject	Error handling	Comments
do_acl_add()
do_acl_policy()
do_acl_remove()
do_acl_reset()
do_acl_show()
do_balloon()	merged	never fails
do_boot_set()
do_change()
do_closefd()	merged
do_commit()
do_cont()	merged	never fails	TODO: encrypted images
do_cpu_set()
do_delvm()
do_device_add()
do_device_del()
do_eject()	merged
do_gdbserver()
do_getfd()	merged
do_help_cmd()
do_info()	merged
do_inject_mce()
do_inject_nmi()
do_ioport_read()
do_ioport_write()
do_loadvm()
do_log()
do_logfile()
do_memory_dump()
do_memory_save()	merged
do_migrate()	merged
do_migrate_cancel()	merged	never fails
do_migrate_set_downtime()
do_migrate_set_speed()	merged	never fails
do_mouse_button()
do_mouse_move()
do_mouse_set()
do_pci_device_hot_remove()	merged
do_physical_memory_dump()
do_physical_memory_save()	merged
do_print()
do_quit()	merged
do_savevm()
do_screen_dump()
do_sendkey()
do_set_link()
do_singlestep()
do_stop()	merged	never fails
do_stop_capture()
do_sum()
do_system_powerdown()	merged	nerver fails
do_system_reset()	merged	never fails
do_usb_add()
do_usb_del()
do_watchdog_action()
do_wav_capture()
drive_hot_add()
net_host_device_add()
net_host_device_remove()
net_slirp_hostfwd_add()
net_slirp_hostfwd_remove()
pci_device_hot_add()	converted

Info handlers

Handler name	Status	Comments
bdrv_info()	converted
bdrv_info_stats()	converted
do_info_balloon()	merged
do_info_capture()
do_info_cpus()	merged
do_info_cpu_stats()
do_info_history()
do_info_hpet()	converted
do_info_jit()
do_info_kvm()	converted
do_info_mice()	converted
do_info_migrate()	converted
do_info_name()	converted
do_info_network()	partial
do_info_numa()
do_info_profile()
do_info_qdm()
do_info_qtree()
do_info_registers()
do_info_roms()
do_info_snapshots()
do_info_status()	converted
do_info_usernet()	partial
do_info_uuid()	converted
do_info_version()	merged
do_info_vnc()	converted
irq_info()
mem_info()
pci_info()
pcmcia_info()
pic_info()
qemu_chr_info()	converted
tlb_info()
usb_host_info()
usb_info()

History

This is the fourth proposal for a machine protocol, past discussions can be found in the following links:

Contact

Primary contact is Luiz Capitulino <lcapitulino at redhat dot com> but most project discussions happen on the QEMU-devel mailing list:

http://lists.nongnu.org/mailman/listinfo/qemu-devel

@@ Line 15: / Line 15: @@
 == Examples ==
+In the following examples, 'C' stands for 'Client' and 'S' stands for 'Server'.
+=== Server Greeting ===
+{|
+| S: || {"QMP": {"capabilities": []}}
+|}
+=== Query version ===
+{|
+| C: || { "execute": "query-version" }
+|-
+| S: || {"return": {"qemu": "0.11.50", "package": ""}}
+|}
+=== Eject a device ===
+{|
+| C: || { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
+|-
+| S: || {"return": "OK"}
+|}
 == TODO ==

MonitorProtocol: Difference between revisions

Revision as of 09:13, 16 December 2009

Contents