MonitorProtocol: Difference between revisions

From KVM
No edit summary
No edit summary
Line 591: Line 591:
== Testing ==
== Testing ==


Unfortunately, there is no automated tool to test QMP correctness yet. Probably, the right thing to do is to integrate it with kvm-autotest but we still have to think how this should be done.
Unfortunately, there is no automated tool to test QMP correctness yet. Probably, the right thing to do is to integrate it 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 some 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.
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:
This section describes two ways of testing QMP:


* By hand (difficult, only worth it you're chasing a specific bug)
* By hand (difficult, only worth it if you're chasing a specific bug)
* By using qmp-shell script (automates part of the job)
* By using qmp-shell script (automates part of the job)


'''TODO''': describe how to run libvirt on top of QMP.
'''TODO''': libvirt should be far easier, describe it!


=== By hand ===
=== By hand ===
Line 612: Line 612:
  telnet localhost 4444
  telnet localhost 4444


3. You should see QMP's greeting message, this means that it's read to accept commands
3. You should see the following prompt


4. Now you can try commands. To get a list of QMP supported commands, run query-commands
{"QMP": {"capabilities": []}}
 
4. Now you can issue commands. To get a list of QMP supported commands, run '''query-commands'''


  { "execute": "query-commands" }
  { "execute": "query-commands" }
'''NOTE:''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".


The output 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 you'll have to check the documentation of the function that implements the command to find out what arguments it accepts.
The output 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 you'll have to check the documentation of the function that implements the command to find out what arguments it accepts.
Line 634: Line 638:
  qmp-shell ./qmp-sock
  qmp-shell ./qmp-sock


3. You should get a prompt
3. You should get the following prompt
 
(QEMU)


4. Now you can run commands. For example, let's change the VNC password:
4. Now you can run commands. For example, let's change the VNC password:


  (qemu) change device=vnc target=password arg='1234'
  (QEMU) change device=vnc target=password arg='1234'


So, it's needed to name the arguments and the script is not that smart. Again, to find out what arguments a command accepts, you have to either check qemu-monitor.hx file or the function which implements the command.
So, it's needed to name the arguments and the script is not that smart. Again, to find out what arguments a command accepts, you have to either check qemu-monitor.hx file or the function which implements the command.

Revision as of 15:05, 13 January 2010

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

The README file explains how to use it and its full specification can be found 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 Luiz Capitulino, but all QMP-related discussions happen on the 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 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

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 Libvirt are marked with yellow.

Command handlers

Handler name Status Version Comments
do_acl_add()
do_acl_policy()
do_acl_remove()
do_acl_reset()
do_acl_show()
do_balloon() merged 0.12
do_boot_set()
do_change() merged 0.12
do_closefd() merged 0.12
do_commit()
do_cont() merged 0.12
do_cpu_set()
do_delvm()
do_device_add()
do_device_del()
do_eject() merged 0.12
do_gdbserver()
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()
do_memory_save() partial 0.12
do_migrate() partial 0.12
do_migrate_cancel() merged 0.12
do_migrate_set_downtime()
do_migrate_set_speed() merged 0.12
do_mouse_button()
do_mouse_move()
do_mouse_set()
do_pci_device_hot_remove() partial 0.12
do_physical_memory_dump()
do_physical_memory_save() partial 0.12
do_print()
do_quit() merged 0.12
do_savevm()
do_screen_dump()
do_sendkey()
do_set_link()
do_singlestep()
do_stop() merged 0.12
do_stop_capture()
do_sum()
do_system_powerdown() merged 0.12
do_system_reset() merged 0.12
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() partial 0.12

Info handlers

Handler name Status Version Comments
bdrv_info() merged 0.12
bdrv_info_stats() merged 0.12
do_info_balloon() merged 0.12
do_info_capture()
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
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()
pci_info()
pcmcia_info()
pic_info()
qemu_chr_info() merged 0.12
tlb_info()
usb_host_info()
usb_info()

Testing

Unfortunately, there is no automated tool to test QMP correctness yet. Probably, the right thing to do is to integrate it with 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 README and spec files.

This section describes two ways of testing QMP:

  • By hand (difficult, only worth it if you're chasing a specific bug)
  • By using qmp-shell script (automates part of the job)

TODO: libvirt should be far easier, describe it!

By hand

1. Start QMP in 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 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 you'll have to check the documentation of the function that implements the command to find out what arguments it accepts.

Yes, it's that low-level.

qmp-shell script

This script is available under the QMP directory in QEMU's source-tree. It automates a bit the testing work, as it can construct commands.

1. Start QMP with 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 that smart. Again, to find out what arguments a command accepts, you have to either check qemu-monitor.hx file 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:

Retrieved from "https://linux-kvm.org/index.php?title=MonitorProtocol&oldid=2779"