Documentation/QMP: Difference between revisions

From QEMU
(Use wait=off instead of the obsolete nowait parameter)
 
(11 intermediate revisions by 7 users not shown)
Line 10: Line 10:
* API/ABI stability guarantees
* API/ABI stability guarantees


Please, also check the [http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/qmp/README;hb=HEAD README] file for more information.
Please, also check the [http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qmp-intro.txt;hb=HEAD QMP intro] file for more information.


== Examples ==
== Examples ==
Line 67: Line 67:
== Development ==
== Development ==


Main developer in charge is [mailto:lcapitulino@redhat.com Luiz Capitulino]. All QMP-related discussions happen on the [http://lists.nongnu.org/mailman/listinfo/qemu-devel qemu-devel] mailing list.
QMP being a core part of QEMU, all discussions happen on the [http://lists.nongnu.org/mailman/listinfo/qemu-devel qemu-devel] mailing list.
 
Luiz's QMP queue (queue/qmp branch) can be found at:
 
http://repo.or.cz/w/qemu/qmp-unstable.git
 
'''IMPORTANT''': This branch is constantly rebased!
 
=== TODO ===
 
In order of importance.
 
==== Drop the qmp-commands.hx file ====
 
The qmp-commands.hx file is basically a command table. Today, with the advent of the QAPI, the qapi-schema.json file serves the same purpose. We should drop qmp-commands.hx in favor of qapi-schema.json.
 
This is more or less what it takes to do that:
 
# Convert do_device_add() and do_qmp_capabilities() to propagate errors (ie, fill an Error ** object instead of doing qerror_report() calls)
# Do something about qmp_netdev_add(), qmp_qom_get() and qmp_qom_set() (drop them or add QAPI wrappers?)
# Change QMP code in monitor.c to use the QAPI to do command parameter validation and command dispatching (just like qemu-ga does)
# Move QMP examples from qmp-commands.hx to qapi-schema.json
# Drop qmp-commands.hx
 
==== redo/fix query-command-line-options ====
 
Redhat Bug 1058567 - query-command-line-options command lost some options
 
Developer: Amos Kong <akong AT redhat.com>
 
Upstream discussion:
* http://marc.info/?l=qemu-devel&m=139081830416684&w=2
 
QemuOpt is a new interface, not all the options have arguments converted to this interface. Some legacy options were lost (Upstream can accept this legacy issue).
But currently some new options without arguments was lost in the return output,
this should be fixed.
 
Problem exists in current query-command-line-options:
* some new options haven't arguments can't be queried. (eg: -enable-fips)
* some legcy options have arguments can't be queried. (eg: -vnc display)
 
Patches:
* V1: http://lists.nongnu.org/archive/html/qemu-devel/2014-01/msg03660.html
* V6: http://lists.nongnu.org/archive/html/qemu-devel/2014-03/msg05222.html
 
==== Add full introspection support ====
 
This is about adding a command which returns all QMP types, commands (input and output parameters) and events.
 
Redhat Bug 557939 - QMP: Full introspection support
 
target: 1.6 (failed)
target: 1.8 (....)
 
Amos Kong is working on this:
 
# V1: http://marc.info/?l=qemu-devel&m=137059998004419&w=2
# V2: https://lists.gnu.org/archive/html/qemu-devel/2013-07/msg02494.html
# V4: http://marc.info/?l=qemu-devel&m=139048842504757&w=2
 
V5: reduce the output size, improve the speed
 
more:
# convert events to qapi-schema.json, support query of events
 
==== Add events support to the QAPI ====
 
Today events are exclusively part of the text protocol. This means that they are open coded, QEMU subsystems can't make use of them and they are not listed in qapi-schema.json.
 
We would solve all those problems by adding event support to the QAPI.
 
==== Generate doc from qapi-schema.json ====
 
The qapi-schema.json file contains full QMP documentation, but it's in JSON format. We should be able to generate a human friendlier doc from it (eg. a manpage).
 
==== Import qemu-ga command-set into QMP namespace ====
 
Basically, this would allow QMP clients to talk to qemu-ga transparently through a QMP session.
 
==== Convert all qerror_report() users to error_setg() ====
 
The end goal here is to drop qerror.[ch], although this also requires converting users of QERR_ macros to use plain strings.
 
==== QMP testing ====
 
There should be a QMP test-suite. Either in QEMU itself or externally, like in kvm-autotest (which seems to be the best option).
 
* security
* stable
* performance
 
==== HMP command conversion to the QAPI ====
 
Our long term plan is to make HMP, the human monitor, independent of QEMU. This means that HMP code shouldn't call QEMU code other than the monitor.
 
To achieve this we have to split existing HMP-only commands (eg. do_wav_capture() or do_ioport_read()) into a QMP part and an HMP part, just like new QMP commands are split.
 
'''NOTE:''' It's not totally clear if we should add good replacements instead of just do a "dumb" conversion.


== Trying it ==
== Trying it ==
Line 172: Line 75:
1. Start QMP on a TCP socket, so that telnet can be used
1. Start QMP on a TCP socket, so that telnet can be used


  # qemu [...] -qmp tcp:localhost:4444,server,nowait
  # qemu [...] -qmp tcp:localhost:4444,server,wait=off


2. Run telnet
2. Run telnet
Line 224: Line 127:
1. Start QMP on a unix socket
1. Start QMP on a unix socket


  # qemu [...] -qmp unix:./qmp-sock,server,nowait
  # qemu [...] -qmp unix:./qmp-sock,server,wait=off


2. Run the script
2. Run the script
Line 240: Line 143:
== Historic information ==
== Historic information ==


* Luiz's QMP talk on KVM Forum 2010 can be found [http://www.linux-kvm.org/wiki/images/1/17/2010-forum-qmp-status-talk.pp.pdf here]
* Luiz's QMP talk on KVM Forum 2010 can be found [http://www.linux-kvm.org/images/1/17/2010-forum-qmp-status-talk.pp.pdf here]
* Old QMP page can be accessed [http://www.linux-kvm.org/wiki/index.php?title=MonitorProtocol&direction=prev&oldid=3232 here]
* Old QMP page can be accessed [http://www.linux-kvm.org/index.php?title=MonitorProtocol&oldid=3100 here]
 
[[Category:User documentation]]

Latest revision as of 12:35, 22 March 2022

QEMU Machine Protocol

The QEMU Machine Protocol (QMP) is a JSON-based protocol which allows applications to control a QEMU instance.

Features:

  • Lightweight, text-based, easy to parse data format
  • Asynchronous messages support (events)
  • Capabilities negotiation
  • API/ABI stability guarantees

Please, also check the QMP intro file for more information.

Examples

The first example explains some important details about QMP. The others are simpler and run on top of the first one.

In all examples "C" stands for "Client" and "S" stands for "Server".

Capabilities Negotiation

When a new QMP connection is established, QMP sends its greeting message and enters capabilities negotiation mode. In this mode, only the qmp_capabilities command works. To exit capabilities negotiation mode and enter command mode, the qmp_capabilities command must be issued:

 S: {
        "QMP": {
            "version": {
                "qemu": {
                    "micro": 0,
                    "minor": 6,
                    "major": 1
                },
                "package": ""
            },
            "capabilities": [
            ]
        }
    }
C: { "execute": "qmp_capabilities" }
S: { "return": {}}

The { "return": {} } response is QMP's success response. An error response will contain the "error" keyword instead of "return".

Eject a medium

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

Query VM status

C: { "execute": "query-status" }
S: {
       "return": {
           "status": "running",
           "singlestep": false,
           "running": true
       }
   }

Asynchronous message

S: { "event": "BLOCK_IO_ERROR",
     "data": { "device": "ide0-hd1",
               "operation": "write",
               "action": "stop" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

Development

QMP being a core part of QEMU, all discussions happen on the qemu-devel mailing list.

Trying it

By hand

1. Start QMP on a TCP socket, so that telnet can be used

# qemu [...] -qmp tcp:localhost:4444,server,wait=off

2. Run telnet

$ telnet localhost 4444

3. You should see QMP's greeting banner

{"QMP": {"version": {"qemu": {"micro": 0, "minor": 6, "major": 1}, "package": ""}, "capabilities": []}}

4. Issue the qmp_capabilities command, so that QMP enters command mode

{ "execute": "qmp_capabilities" }

5. You can now issue commands. For example, to get a list of QMP supported commands, issue query-commands

{ "execute": "query-commands" }

There's an optimization to this procedure in case you plan to use it often:

1. Install programs socat and rlwrap. If you're running Fedora, you can do

# yum install socat rlwrap

2. Add the following sections to your QEMU config file (or create a qemu-qmp.conf one):

[chardev "qmp"]
  backend = "socket"
  path = "path to the QMP unix socket"
  server = "on"
  wait = "off"
[mon "qmp"]
  mode = "control"
  chardev = "qmp"
  pretty = "on"

3. Run QEMU

# qemu [...] -readconfig qemu-qmp.conf

4. Run rlwrap

# rlwrap -C qmp socat STDIO UNIX:path-to-the-QMP-unix-socket

You can now issue commands, rlwrap will give you readline support (including persistent history).

qmp-shell script

This script is available under the scripts/qmp/ directory in QEMU's source-tree. It automates a bit the testing work, as it can construct commands objects for you.

1. Start QMP on a unix socket

# qemu [...] -qmp unix:./qmp-sock,server,wait=off

2. Run the script

# qmp-shell ./qmp-sock

3. You should get the following prompt

(QEMU)

4. You can now issue commands. For example, let's add a new device

(QEMU) device_add driver=e1000 id=net1

Historic information

  • Luiz's QMP talk on KVM Forum 2010 can be found here
  • Old QMP page can be accessed here