KVM - User contributions [en]

MonitorProtocol

2010-09-09T13:51:58Z

Luizcapitulino:

= PAGE MOVED!! =

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

MonitorProtocol

2010-07-22T16:41:55Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor the right way.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation

However, QMP is still under heavy development and '''is considered an unstable protocol'''. Please, check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file for more information.

== General Status ==

A '''preview''' version of QMP is available in QEMU since version 0.12. It's already functional and contains a number of commands available, however early adopters will have to cope with protocol changes between QEMU releases.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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 ==

=== High Priority ===

* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)

* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support

=== Normal Priority ===

* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp

== 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 three ways of testing QMP:

* By hand (difficult, only worth it if you're chasing a specific bug)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* partial: merged, but error handling is incomplete

'''NOTE:''' Handlers used by [http://libvirt.org Libvirt] are marked with yellow. Handlers it is expected to use are marked khaki

==== 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
|
|- style="background-color:yellow;"
|do_commit()
|
|
|
|- style="background-color:yellow;"
|do_cont()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_cpu_set()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_cpu_set_nr()
|
|
|qemu-kvm only
|- style="background-color:yellow;"
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_device_del()
|merged
|0.12.50
|
|- 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()
|
|
|
|- style="background-color:yellow;"
|do_loadvm()
|
|
|
|-
|do_log()
|
|
|
|-
|do_logfile()
|
|
|
|-
|do_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_memory_save()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|- style="background-color:khaki;"
|do_mouse_button()
|
|
|
|- style="background-color:khaki;"
|do_mouse_move()
|
|
|
|- style="background-color:khaki;"
|do_mouse_set()
|
|
|
|-
|do_netdev_add()
|merged
|0.12.50
|
|-
|do_netdev_del()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|do_print()
|
|
|
|-
|do_quit()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_savevm()
|
|
|
|- style="background-color:khaki;"
|do_screen_dump()
|merged
|0.12.50
|
|- style="background-color:khaki;"
|do_sendkey()
|
|
|
|- style="background-color:khaki;"
|do_set_link()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|legacy, use blockdev_add, device_add instead
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add, blockdev_add instead
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|}

==== Info handlers ====

{| border="1"
|'''Handler name'''
|'''Status'''
|'''Version'''
|'''Comments'''
|-
|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()
|
|
|
|-
|do_info_commands()
|merged
|0.12
|
|-
|do_info_cpu_stats()
|
|
|
|- style="background-color:yellow;"
|do_info_cpus()
|merged
|0.12
|
|-
|do_info_history()
|
|
|
|-
|do_info_hpet()
|merged
|0.12
|
|-
|do_info_jit()
|
|
|
|- style="background-color:khaki;"
|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()
|
|
|legacy, use do_info_netdev()
|- style="background-color:khaki;"
|do_info_netdev()
|
|
|[http://wiki.qemu.org/Google_Summer_of_Code_2010/QMP Being worked on in SoC]
|-
|do_info_numa()
|
|
|
|-
|do_info_profile()
|
|
|
|- style="background-color:khaki;"
|do_info_qdm()
|
|
|
|-
|do_info_qtree()
|
|
|
|-
|do_info_registers()
|
|
|
|-
|do_info_roms()
|
|
|
|- style="background-color:khaki;"
|do_info_snapshots()
|
|
|lacks parent info, libvirt wants it
|- style="background-color:khaki;"
|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
|
|-
|do_pci_info()
|merged
|0.12.50
|libvirt uses this, but only with pre-0.12.x QEMU
|-
|irq_info()
|
|
|
|-
|mem_info()
|
|
|
|-
|pcmcia_info()
|
|
|
|-
|pic_info()
|
|
|
|- style="background-color:yellow;"
|qemu_chr_info()
|merged
|0.12
|
|-
|tlb_info()
|
|
|
|-
|usb_host_info()
|
|
|
|-
|usb_info()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-07-22T16:39:05Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation

However, QMP is still under heavy development and is '''considered an unstable protocol'''. Please, check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file for more information.

== General Status ==

A '''preview''' version of QMP is available in QEMU since version 0.12. It's already functional and contains a number of commands available, however early adopters will have to cope with protocol changes between QEMU releases.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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 ==

=== High Priority ===

* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)

* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support

=== Normal Priority ===

* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp

== 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 three ways of testing QMP:

* By hand (difficult, only worth it if you're chasing a specific bug)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* partial: merged, but error handling is incomplete

'''NOTE:''' Handlers used by [http://libvirt.org Libvirt] are marked with yellow. Handlers it is expected to use are marked khaki

==== 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
|
|- style="background-color:yellow;"
|do_commit()
|
|
|
|- style="background-color:yellow;"
|do_cont()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_cpu_set()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_cpu_set_nr()
|
|
|qemu-kvm only
|- style="background-color:yellow;"
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_device_del()
|merged
|0.12.50
|
|- 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()
|
|
|
|- style="background-color:yellow;"
|do_loadvm()
|
|
|
|-
|do_log()
|
|
|
|-
|do_logfile()
|
|
|
|-
|do_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_memory_save()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|- style="background-color:khaki;"
|do_mouse_button()
|
|
|
|- style="background-color:khaki;"
|do_mouse_move()
|
|
|
|- style="background-color:khaki;"
|do_mouse_set()
|
|
|
|-
|do_netdev_add()
|merged
|0.12.50
|
|-
|do_netdev_del()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|do_print()
|
|
|
|-
|do_quit()
|merged
|0.12
|
|- style="background-color:yellow;"
|do_savevm()
|
|
|
|- style="background-color:khaki;"
|do_screen_dump()
|merged
|0.12.50
|
|- style="background-color:khaki;"
|do_sendkey()
|
|
|
|- style="background-color:khaki;"
|do_set_link()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|legacy, use blockdev_add, device_add instead
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add, blockdev_add instead
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|}

==== Info handlers ====

{| border="1"
|'''Handler name'''
|'''Status'''
|'''Version'''
|'''Comments'''
|-
|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()
|
|
|
|-
|do_info_commands()
|merged
|0.12
|
|-
|do_info_cpu_stats()
|
|
|
|- style="background-color:yellow;"
|do_info_cpus()
|merged
|0.12
|
|-
|do_info_history()
|
|
|
|-
|do_info_hpet()
|merged
|0.12
|
|-
|do_info_jit()
|
|
|
|- style="background-color:khaki;"
|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()
|
|
|legacy, use do_info_netdev()
|- style="background-color:khaki;"
|do_info_netdev()
|
|
|[http://wiki.qemu.org/Google_Summer_of_Code_2010/QMP Being worked on in SoC]
|-
|do_info_numa()
|
|
|
|-
|do_info_profile()
|
|
|
|- style="background-color:khaki;"
|do_info_qdm()
|
|
|
|-
|do_info_qtree()
|
|
|
|-
|do_info_registers()
|
|
|
|-
|do_info_roms()
|
|
|
|- style="background-color:khaki;"
|do_info_snapshots()
|
|
|lacks parent info, libvirt wants it
|- style="background-color:khaki;"
|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
|
|-
|do_pci_info()
|merged
|0.12.50
|libvirt uses this, but only with pre-0.12.x QEMU
|-
|irq_info()
|
|
|
|-
|mem_info()
|
|
|
|-
|pcmcia_info()
|
|
|
|-
|pic_info()
|
|
|
|- style="background-color:yellow;"
|qemu_chr_info()
|merged
|0.12
|
|-
|tlb_info()
|
|
|
|-
|usb_host_info()
|
|
|
|-
|usb_info()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-04-04T22:24:34Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stable API (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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 ==

=== High Priority ===

* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)

* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support

=== Normal Priority ===

* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp

== 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 three ways of testing QMP:

* By hand (difficult, only worth it if you're chasing a specific bug)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-04-04T00:27:36Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stable API (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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 ==

=== High Priority ===

* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)

* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support

=== Normal Priority ===

* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T19:09:02Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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 ==

=== High Priority ===

* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)

* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support

=== Normal Priority ===

* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T19:07:39Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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 ==

=== High ===

* do_device_add()/do_device_del() conversions (markus)
* do_netdev_add()/do_netdev_del() conversions (markus)
* do_blockdev_add()/do_blockdev_del() conversions (markus)
* Events Grouping (luiz)
* Make qmp-shell work again (luiz)

* Self-description & High-level protocol documentation
* High-level internal documentation
* Better QObjects and QMP debug support

=== Normal ===

* Convert all remaining commands to the QObject API
* Improve internal API, currently it's too [http://lists.gnu.org/archive/html/qemu-devel/2009-12/msg02537.html low-level]
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:54:08Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary libvirt master branch] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:52:26Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with libvirt)

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.

1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 (or above) just do 'yum install yajl-devel')

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE (1):''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

'''NOTE (2):''' Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:44:23Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:43:40Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== 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'

'''NOTE''': 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.

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:41:15Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp

== 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)
* qmp-shell script (automates part of the job)
* Libvirt integration

=== 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": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''

{ "execute": "query-commands" }

'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

'''NOTE (2):''' 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.

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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!

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:35:58Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* Better QObjects and QMP debug support
* Array-based Monitor's command table
* Libqmp

== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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!

== 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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()
|
|
|
|-
|}

== 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

MonitorProtocol

2010-03-29T18:27:43Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting with QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.50", "package": ""} }

=== Eject a device ===

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: {"return": {}}

== Development ==

Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], 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]
* 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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

MonitorProtocol

2010-03-29T18:25:50Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== General Status ==

A '''preview''' version of QMP is available in QEMU version 0.12. This means that QMP is still under development and there '''will''' be incompatible changes between QEMU 0.12 and QEMU 0.13.

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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.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]
* 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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

MonitorProtocol

2010-03-29T18:21:37Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Capabilities Negotiation
* Stability (starting QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== 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": { "version": { "qemu": "0.12.50", "package": "" }, "capabilities": [] } }

=== Query version ===

C: { "execute": "query-version" }
S: { "return": { "qemu": "0.12.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]
* 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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

MonitorProtocol

2010-03-29T18:16:33Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Stability (starting QEMU version 0.13)

The [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file has a simple introduction and the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt full specification] is recommended for application writers.

== 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]
* 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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

MonitorProtocol

2010-03-29T18:14:35Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)
* Stability (from QEMU version 0.13)

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]
* 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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

MonitorProtocol

2010-03-29T18:12:40Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.

QMP's main features are:

* Lightweight, text-based, easy to parse data format
* Asynchronous messages support (ie. events)

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]
* 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
* 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()
|merged
|0.12.50
|
|-
|do_delvm()
|
|
|
|- style="background-color:yellow;"
|do_device_add()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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)

=== Libvirt ===

1. Install [http://lloyd.github.com/yajl yajl-devel] before running 'autogen.sh'. Make sure the final summary of autogen.sh tells you that it found the yajl library. If you`re running Fedora 12(or above) just yum install yajl-devel.

2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary GIT master] run the following:

./autogen.sh --system --enable-compile-warnings=error

'''NOTE:''' The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

3. Run 'make' to build. There is no need to 'make install' anything
especially since that would overwrite your RPM based install

4. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

5. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

6. To enable QMP support, before you build edit '''src/qemu/qemu_conf.c''' and find:

#if 0
if (version >= 13000)
flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

'''NOTE:''' If enabled libvirt will use QMP as default monitor.

7. Change that to an '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

=== 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

MonitorProtocol

2010-02-09T12:26:52Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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]
* 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()
|merged
|0.12.50
|
|-
|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()
|merged
|0.12.50
|
|- 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()
|merged
|0.12.50
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12.50
|
|-
|do_mouse_button()
|
|
|
|-
|do_mouse_move()
|
|
|
|-
|do_mouse_set()
|
|
|
|- style="background-color:yellow;"
|do_pci_device_hot_remove()
|partial
|0.12
|legacy, use device_del instead
|-
|do_physical_memory_dump()
|
|
|
|- style="background-color:yellow;"
|do_physical_memory_save()
|merged
|0.12.50
|
|-
|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()
|
|
|legacy, use device_add instead
|- style="background-color:yellow;"
|do_usb_del()
|
|
|legacy, use device_del instead
|-
|do_watchdog_action()
|
|
|
|-
|do_wav_capture()
|
|
|
|- style="background-color:yellow;"
|drive_hot_add()
|
|
|
|- style="background-color:yellow;"
|net_host_device_add()
|
|
|consider do_netdev_add() instead
|- style="background-color:yellow;"
|net_host_device_remove()
|
|
|consider do_netdev_del() instead
|-
|net_slirp_hostfwd_add()
|
|
|
|-
|net_slirp_hostfwd_remove()
|
|
|
|- style="background-color:yellow;"
|pci_device_hot_add()
|partial
|0.12
|legacy, use device_add instead
|-
|do_chardev_add()
|
|
|to be created
|-
|do_chardev_del()
|
|
|to be created
|-
|do_blockdev_add()
|
|
|to be created
|-
|do_blockdev_del()
|
|
|to be created
|-
|do_netdev_add()
|
|
|to be created
|-
|do_netdev_del()
|
|
|to be created
|-
|}

==== 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

MonitorProtocol

2010-01-14T12:02:24Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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_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()
|
|
|
|-
|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
|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()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12
|
|-
|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
|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

MonitorProtocol

2010-01-14T11:58:07Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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_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()
|
|
|
|-
|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
|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()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12
|
|-
|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
|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 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.

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

MonitorProtocol

2010-01-13T20:06:33Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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_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()
|
|
|
|-
|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
|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()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12
|
|-
|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
|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 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 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)
* By 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 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 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 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:

* 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

MonitorProtocol

2010-01-13T20:05:30Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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_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()
|
|
|
|-
|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
|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()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12
|
|-
|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
|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 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 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)
* 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:

* 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

MonitorProtocol

2010-01-13T19:53:31Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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_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()
|
|
|
|-
|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
|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()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12
|
|-
|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
|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 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 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.

This section describes two ways of testing QMP:

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

'''TODO''': describe how to run libvirt on top of QMP.

=== 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 QMP's greeting message, this means that it's read to accept commands

4. Now you can try commands. To get a list of QMP supported commands, run query-commands

{ "execute": "query-commands" }

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 a prompt

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:

* 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

MonitorProtocol

2010-01-13T19:09:22Z

Luizcapitulino:

= QEMU Monitor Protocol =

The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor.

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_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()
|
|
|
|-
|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
|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()
|
|
|
|- style="background-color:yellow;"
|do_migrate_set_speed()
|merged
|0.12
|
|-
|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
|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 ==

== 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

MonitorProtocol

2010-01-13T19:08:11Z

Luizcapitulino:

MonitorProtocol

2009-12-30T13:57:06Z

Luizcapitulino:

MonitorProtocol

2009-12-29T15:43:43Z

Luizcapitulino:

MonitorProtocol

2009-12-29T12:30:03Z

Luizcapitulino:

MonitorProtocol

2009-12-28T20:06:49Z

Luizcapitulino:

MonitorProtocol

2009-12-28T12:40:48Z

Luizcapitulino:

MonitorProtocol

2009-12-18T19:33:37Z

Luizcapitulino:

MonitorProtocol

2009-12-18T19:31:33Z

Luizcapitulino:

MonitorProtocol

2009-12-18T19:28:00Z

Luizcapitulino:

MonitorProtocol

2009-12-18T19:25:55Z

Luizcapitulino:

MonitorProtocol

2009-12-17T20:40:03Z

Luizcapitulino:

MonitorProtocol

2009-12-17T12:17:23Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:31:47Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:25:35Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:19:37Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:17:43Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:14:59Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:13:32Z

Luizcapitulino:

MonitorProtocol

2009-12-16T17:08:42Z

Luizcapitulino:

MonitorProtocol

2009-12-16T16:45:08Z

Luizcapitulino:

MonitorProtocol

2009-12-16T16:43:19Z

Luizcapitulino:

MonitorProtocol

2009-12-16T16:35:54Z

Luizcapitulino:

MonitorProtocol

2009-12-16T16:28:44Z

Luizcapitulino:

MonitorProtocol

2009-12-16T16:24:49Z

Luizcapitulino: