Merge remote-tracking branch 'kwolf/for-anthony' into staging

[mirror_qemu.git] / docs / qmp / 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.org/QMP