MonitorProtocol

From KVM
Revision as of 10:18, 16 December 2009 by Luizcapitulino (talk | contribs)

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"}

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

TODO

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

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