qemu/docs/qmp
Eric Blake 032baddea3 docs: document missing VSERPORT_CHANGE event
The VSERPORT_CHANGE event was added in e2ae6159.  The patch for
this event was prepared at a time when this file was gone, even
though it got applied immediately after dfab4892 restored this
file.  Duplicate the documentation into this file, so that
anyone using this file instead of qapi will not miss out on this
new event.

* docs/qmp/qmp-events.txt (VSERPORT_CHANGE): Add.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Wenchao Xia <wenchaoqemu@gmail.com>
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
2014-07-24 10:00:33 -04:00
..
qmp-events.txt docs: document missing VSERPORT_CHANGE event 2014-07-24 10:00:33 -04:00
qmp-spec.txt QMP: Update qmp-spec.txt 2013-09-18 08:57:02 -04:00
README Use qemu-project.org domain name 2013-10-11 09:34:56 -07:00

                          QEMU Machine Protocol
                          =====================

Introduction
------------

The QEMU Machine Protocol (QMP) allows applications to operate a
QEMU instance.

QMP is JSON[1] based and features the following:

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

For detailed information on QMP's usage, please, refer to the following files:

o qmp-spec.txt      QEMU Machine Protocol current specification
o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
o qmp-events.txt    List of available asynchronous events

[1] http://www.json.org

Usage
-----

You can use the -qmp option to enable QMP. For example, the following
makes QMP available on localhost port 4444:

$ qemu [...] -qmp tcp:localhost:4444,server,nowait

However, for more flexibility and to make use of more options, the -mon
command-line option should be used. For instance, the following example
creates one HMP instance (human monitor) on stdio and one QMP instance
on localhost port 4444:

$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
             -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
             -mon chardev=mon1,mode=control,pretty=on

Please, refer to QEMU's manpage for more information.

Simple Testing
--------------

To manually test QMP one can connect with telnet and issue commands by hand:

$ telnet localhost 4444
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
{
    "QMP": {
        "version": {
            "qemu": {
                "micro": 50, 
                "minor": 6, 
                "major": 1
            }, 
            "package": ""
        }, 
        "capabilities": [
        ]
    }
}

{ "execute": "qmp_capabilities" }
{
    "return": {
    }
}

{ "execute": "query-status" }
{
    "return": {
        "status": "prelaunch", 
        "singlestep": false, 
        "running": false
    }
}

Please, refer to the qapi-schema.json file for a complete command reference.

QMP wiki page
-------------

http://wiki.qemu-project.org/QMP