MonitorProtocol: Difference between revisions

From KVM
No edit summary
No edit summary
 
(87 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= Monitor Protocol =
= PAGE MOVED!! =


The QEMU Monitor Protocol (QMP) project goal is to implement a [http://www.json.org JSON] based protocol for QEMU.
This page has moved to: http://wiki.qemu.org/QMP
 
== Problem ==
 
QEMU does not provide a way for applications to control it at the "machine level", that is, the current existing interface (called Monitor) was designed for human interaction only.
 
This is very problematic for applications, for the following reasons:
 
* It is needed to parse output meant to be read by humans
* It is not reliable, because it is not always possible to know whether a command has been successfully executed or not
* It lacks support for asynchronous events
 
== Solution ==
 
Improve QEMU's Monitor to support a machine protocol with the following features:
 
* Use a lightweight, text-based, easy to parse data format (JSON has been chosen)
* Protocol stability should be guaranteed
* Asynchronous events support
* Parallel execution of commands
* A standard way to query protocol capabilities
 
== Libqmp ==
 
Although this is still under discussion, we are also going to provide a C library with a stable ABI.
 
The short-term plan is to have a simple API to send commands and receive responses, this way C clients do not need to have their own JSON implementation.
 
The long-term plan is to provide a full management API for QEMU.
 
== 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 [http://repo.or.cz/w/qemu/qmp-unstable.git?a=blob;f=QMP/qmp-spec.txt;h=3633b0dddd8205328d33d51f0d35ce1c76c0d593;hb=HEAD here].
* '''conversions-qobject''': output in QObject conversions
* '''conversions-qerror''': error handling conversions
 
== Project status (2009-11-23) ==
 
Most of the infrastructure has been merged, the only fundamental missing part is the error framework (QError), which is still under discussion.
 
Additionally, all command handlers need to be converted to use ''QObjects''. This work is in progress
 
=== Main building blocks ===
 
* QObject Layer ('''merged''')
* QObject Monitor infrastructure ('''merged''')
* JSON encoder/decoder ('''merged''')
* Error framework ('''under discussion''')
 
=== Conversion work ===
 
* Input through QDict ('''merged''')
* Output in QObject style ('''in progress''')
* Error handling ('''not started''')
 
=== Conversion work detailed status ===
 
{| border="1"
|
|Command
|Info
|-
|Handlers
|61
|35
|-
|Fully Converted
|7
|16
|-
|Percentage
|11%
|45.7%
|-
|}
 
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: handler is converted but not submitted yet
* never fails: does not need error handling
 
'''NOTE:''' Handlers used by [http://libvirt.org Libvirt] are marked with yellow.
 
==== Command handlers ====
 
{| border="1"
|'''Handler name'''
|'''Output in QObject'''
|'''Error handling'''
|'''Comments'''
|-
|do_acl_add()
|
|
|
|-
|do_acl_policy()
|
|
|
|-
|do_acl_remove()
|
|
|
|-
|do_acl_reset()
|
|
|
|-
|do_acl_show()
|
|
|
|- style="background-color:yellow;"
|do_balloon()
|merged
|never fails
|
|-
|do_boot_set()
|
|
|
|- style="background-color:yellow;"
|do_change()
|
|
|
|- style="background-color:yellow;"
|do_closefd()
|merged
|
|
|-
|do_commit()
|
|
|
|- style="background-color:yellow;"
|do_cont()
|merged
|never fails
|TODO: encrypted images
|-
|do_cpu_set()
|
|
|
|-
|do_delvm()
|
|
|
|-
|do_device_add()
|
|
|
|-
|do_device_del()
|
|
|
|- style="background-color:yellow;"
|do_eject()
|merged
|
|
|-
|do_gdbserver()
|
|
|
|- style="background-color:yellow;"
|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()
|
|
|
|- style="background-color:yellow;"
|do_memory_save()
|merged
|
|
|- style="background-color:yellow;"
|do_migrate()
|merged
|
|
|-
|do_migrate_cancel()
|merged
|never fails
|
|-
|do_migrate_set_downtime()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|never fails
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|merged
|
|
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|
|
|-
|do_print()
|
|
|
|-
|do_quit()
|merged
|
|
|-
|do_savevm()
|
|
|
|-
|do_screen_dump()
|
|
|
|-
|do_sendkey()
|
|
|
|-
|do_set_link()
|
|
|
|-
|do_singlestep()
|
|
|
|- style="background-color:yellow;"
|do_stop()
|merged
|never fails
|
|-
|do_stop_capture()
|
|
|
|-
|do_sum()
|
|
|
|- style="background-color:yellow;"
|do_system_powerdown()
|merged
|nerver fails
|
|-
|do_system_reset()
|merged
|never fails
|
|- style="background-color:yellow;"
|do_usb_add()
|
|
|
|- style="background-color:yellow;"
|do_usb_del()
|
|
|
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|-
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|converted
|
|
|-
|}
 
==== Info handlers ====
 
{| border="1"
|'''Handler name'''
|'''Status'''
|'''Comments'''
|- style="background-color:yellow;"
|bdrv_info()
|converted
|
|- style="background-color:yellow;"
|bdrv_info_stats()
|converted
|
|- style="background-color:yellow;"
|do_info_balloon()
|merged
|
|-
|do_info_capture()
|
|
|- style="background-color:yellow;"
|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
|
|- style="background-color:yellow;"
|do_info_migrate()
|converted
|
|-
|do_info_name()
|converted
|
|-
|do_info_network()
|converted
|
|-
|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()
|converted
|
|-
|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:
 
http://lists.nongnu.org/mailman/listinfo/qemu-devel

Latest revision as of 09:51, 9 September 2010

PAGE MOVED!!

This page has moved to: http://wiki.qemu.org/QMP