qemu-e2k/docs/qmp
Eric Blake e790e66651 qapi: Document type-safety considerations
Go into more details about the various types of valid expressions
in a qapi schema, including tweaks to document fixes being done
later in the current patch series.  Also fix some stale and missing
documentation in the QMP specification.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2015-05-05 18:38:59 +02:00
..
README Use qemu-project.org domain name 2013-10-11 09:34:56 -07:00
qmp-events.txt block: add 'node-name' field to BLOCK_IMAGE_CORRUPTED 2015-04-28 15:36:09 +02:00
qmp-spec.txt qapi: Document type-safety considerations 2015-05-05 18:38:59 +02:00

README

                          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