|
|
| (25 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| = QEMU Monitor Protocol = | | = PAGE MOVED!! = |
|
| |
|
| The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor.
| | This page has moved to: http://wiki.qemu.org/QMP |
| | |
| 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
| |