|
|
| (90 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
| |
| | |
| A draft specification already exists and can be found [http://repo.or.cz/w/qemu/qmp-unstable.git?a=blob;f=QMP/qmp-spec.txt;h=3633b0dddd8205328d33d51f0d35ce1c76c0d593;hb=HEAD here].
| |
| | |
| == 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 for emission only (includes asynchronous messages). Protocol documentation can be found in the [http://repo.or.cz/w/qemu/qmp-unstable.git?a=tree;f=QMP;h=290262119cc6c9e07a6ef7a078384ef12c491e51;hb=HEAD QMP directory ]
| |
| * '''conversions-simple''': simple handler conversions that do not depend on the JSON decoder
| |
| * '''conversions-qjson''': handler conversions which depend on the JSON decoder, therefore the latest version of Anthony's QJSon series is included
| |
| | |
| == Project status (2009-11-10) ==
| |
| | |
| Most of the infrastructure has been merged, the fundamental missing parts are a JSON encoder/decoder and an error framework.
| |
| | |
| Patches exist for a JSON decoder (QJSON) and an error framework (QError), but they have not been merged yet.
| |
| | |
| Additionally, all command handlers need to be converted to use ''QObjects''. This work is in progress, but most handlers depend on the JSON decoder to be merged.
| |
| | |
| === Main building blocks ===
| |
| | |
| * QObject Layer ('''merged''')
| |
| * QObject Monitor infrastructure ('''merged''')
| |
| * JSON decoder ('''in progress''')
| |
| * JSON encoder ('''not started''')
| |
| * Error framework ('''under review''')
| |
| | |
| === 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 (in either branch [http://repo.or.cz/w/qemu/qmp-unstable.git?a=shortlog;h=refs/heads/conversions-simple conversions-simple] or [http://repo.or.cz/w/qemu/qmp-unstable.git?a=shortlog;h=refs/heads/conversions-qjson conversions-qjson]) 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
| |