MonitorProtocol: Difference between revisions

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


The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.
This page has moved to: http://wiki.qemu.org/QMP
 
QMP is [http://www.json.org/ JSON]-based, its main features are:
 
* Lightweight, text-based, easy to parse data format
* Asynchronous events support
 
The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file explains how to use it and its full specification can be found [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt here].
 
== General Status ==
 
A '''preview''' version of QMP is available in QEMU version 0.12.
 
However, QMP is still under development being considered unstable and incomplete. For more information about converted handlers, please check [[#Conversion Status]].
 
== 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": {}}
 
== Development ==
 
Primary contact is [mailto:lcapitulino@redhat.com Luiz Capitulino], but all QMP-related discussions happen on the [http://lists.nongnu.org/mailman/listinfo/qemu-devel qemu-devel] mailing list.
 
Next features, hot fixes and other patches are stored in the QMP unstable repository:
 
http://repo.or.cz/w/qemu/qmp-unstable.git
 
'''NOTE''': all branches in this repository are constantly ''rebased'' (master inclusive).
 
== TODO ==
 
* Convert all remaining commands
* High-level protocol documentation
* High-level internal documentation
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Feature negotiation (?)
* Asynchronous commands support
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp
 
== Conversion Status ==
 
'''UPDATED''': 2009-12-16
 
{| border="1"
|
|Command
|Info
|-
|Handlers
|62
|36
|-
|Converted
|19
|15
|-
|Percentage
|30%
|41%
|-
|}
 
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: merged, but error handling is incomplete
 
'''NOTE:''' Handlers used by [http://libvirt.org Libvirt] are marked with yellow.
 
==== Command handlers ====
 
{| border="1"
|'''Handler name'''
|'''Status'''
|'''Version'''
|'''Comments'''
|-
|do_acl_add()
|
|
|
|-
|do_acl_policy()
|
|
|
|-
|do_acl_remove()
|
|
|
|-
|do_acl_reset()
|
|
|
|-
|do_acl_show()
|
|
|
|- style="background-color:yellow;"
|do_balloon()
|merged
|0.12
|
|-
|do_block_set_passwd()
|merged
|0.12
|
|-
|do_boot_set()
|
|
|
|- style="background-color:yellow;"
|do_change()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_closefd()
|merged
|0.12
|
|-
|do_commit()
|
|
|
|- style="background-color:yellow;"
|do_cont()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_cpu_set()
|converted
|
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|
|
|
|- style="background-color:yellow;"
|do_device_del()
|
|
|
|- style="background-color:yellow;"
|do_eject()
|merged
|0.12
|
|-
|do_gdbserver()
|
|
|
|- style="background-color:yellow;"
|do_getfd()
|merged
|0.12
|
|-
|do_help_cmd()
|
|
|
|-
|do_info()
|merged
|0.12
|as 'query-' commands
|-
|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()
|partial+converted
|0.12
|
|- style="background-color:yellow;"
|do_migrate()
|partial
|0.12
|
|- style="background-color:yellow;"
|do_migrate_cancel()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_migrate_set_downtime()
|converted
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|converted
|
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|partial+converted
|0.12
|
|-
|do_print()
|
|
|
|-
|do_quit()
|merged
|0.12
|
|-
|do_savevm()
|
|
|
|-
|do_screen_dump()
|
|
|
|-
|do_sendkey()
|
|
|
|- style="background-color:yellow;"
|do_set_link()
|
|
|
|-
|do_singlestep()
|
|
|
|- style="background-color:yellow;"
|do_stop()
|merged
|0.12
|
|-
|do_stop_capture()
|
|
|
|-
|do_sum()
|
|
|
|- style="background-color:yellow;"
|do_system_powerdown()
|merged
|0.12
|
|-
|do_system_reset()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_usb_add()
|
|
|
|- style="background-color:yellow;"
|do_usb_del()
|
|
|
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|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()
|partial
|0.12
|
|-
|}
 
==== Info handlers ====
 
{| border="1"
|'''Handler name'''
|'''Status'''
|'''Version'''
|'''Comments'''
|- style="background-color:yellow;"
|bdrv_info()
|merged
|0.12
|
|- style="background-color:yellow;"
|bdrv_info_stats()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_info_balloon()
|merged
|0.12
|
|-
|do_info_capture()
|
|
|
|- style="background-color:yellow;"
|do_info_cpus()
|merged
|0.12
|
|-
|do_info_cpu_stats()
|
|
|
|-
|do_info_history()
|
|
|
|-
|do_info_hpet()
|merged
|0.12
|
|-
|do_info_jit()
|
|
|
|-
|do_info_kvm()
|merged
|0.12
|
|-
|do_info_mice()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_info_migrate()
|merged
|0.12
|
|-
|do_info_name()
|merged
|0.12
|
|-
|do_info_network()
|
|
|
|-
|do_info_numa()
|
|
|
|-
|do_info_profile()
|
|
|
|-
|do_info_qdm()
|
|
|
|-
|do_info_qtree()
|
|
|
|-
|do_info_registers()
|
|
|
|-
|do_info_roms()
|
|
|
|-
|do_info_snapshots()
|
|
|
|-
|do_info_status()
|merged
|0.12
|
|-
|do_info_usernet()
|
|
|
|-
|do_info_uuid()
|merged
|0.12
|
|-
|do_info_version()
|merged
|0.12
|
|-
|do_info_vnc()
|merged
|0.12
|
|-
|irq_info()
|
|
|
|-
|mem_info()
|
|
|
|- style="background-color:yellow;"
|pci_info()
|
|
|
|-
|pcmcia_info()
|
|
|
|-
|pic_info()
|
|
|
|-
|qemu_chr_info()
|merged
|0.12
|
|-
|tlb_info()
|
|
|
|-
|usb_host_info()
|
|
|
|- style="background-color:yellow;"
|usb_info()
|
|
|
|-
|}
 
== Testing ==
 
Unfortunately, there is no automated tool to test QMP correctness yet. Probably, the right thing to do is to integrate with [http://www.linux-kvm.org/page/KVM-Autotest kvm-autotest] but we still have to think how this should be done.
 
Meanwhile, QMP testing is a low-level procedure which requires knowledge about the protocol and its implementation, so the first thing to do is to read the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] and [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt spec] files.
 
This section describes two ways of testing QMP:
 
* By hand (difficult, only worth it if you're chasing a specific bug)
* Using qmp-shell script (automates part of the job)
 
'''TODO''': libvirt should be far easier, describe it!
 
=== By hand ===
 
1. Start QMP on a TCP socket, so that telnet can be used
 
qemu [...] -qmp tcp:localhost:4444,server
 
2. Now, run telnet
 
telnet localhost 4444
 
3. You should see the following prompt
 
{"QMP": {"capabilities": []}}
 
4. Now you can issue commands. To get a list of QMP supported commands, run ''query-commands''
 
{ "execute": "query-commands" }
 
'''NOTE:''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".
 
The output of ''query-commands'' is a JSON array of objects, each with a 'name' key, which has the name of the supported command. QMP doesn't have user documentation yet, this means that, to find out which arguments a command accepts or what's its output, you will have to either check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/qemu-monitor.hx qemu-monitor.hx] file and/or the function which implements the command.
 
Yes, it's that low-level.
 
=== qmp-shell script ===
 
This script is available under the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP QMP] directory in QEMU's source-tree. It automates a bit the testing work, as it can construct commands.
 
1. Start QMP on a unix socket, like:
 
qemu [...] -qmp unix:./qmp-sock,server
 
2. Run the script
 
qmp-shell ./qmp-sock
 
3. You should get the following prompt
 
(QEMU)
 
4. Now you can run commands. For example, let's change the VNC password:
 
(QEMU) change device=vnc target=password arg='1234'
 
So, it's needed to name the arguments and the script is not very smart. Again, to find out what arguments a command accepts, you have to either check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/qemu-monitor.hx qemu-monitor.hx] file and/or the function which implements the command.
 
Have fun!
 
== History ==
 
This was the fourth proposal for a Monitor 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

Latest revision as of 09:51, 9 September 2010

PAGE MOVED!!

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