MonitorProtocol
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:
- http://www.mail-archive.com/qemu-devel@nongnu.org/msg14593.html
- http://lists.gnu.org/archive/html/qemu-devel/2009-01/msg00655.html
- http://lists.gnu.org/archive/html/qemu-devel/2009-06/msg01584.html
Contact
Primary contact is Luiz Capitulino <lcapitulino at redhat dot com> but most project discussions happen on the QEMU-devel mailing list: