QEMU Monitor Protocol ===================== Introduction ------------- The QEMU Monitor Protocol (QMP) allows applications to communicate with QEMU's Monitor. QMP is JSON[1] based and currently has the following features: - 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 Monitor Protocol current specification o qmp-commands.txt QMP supported commands (auto-generated at build-time) o qmp-events.txt List of available asynchronous events There is also a simple Python script called 'qmp-shell' available. IMPORTANT: It's strongly recommended to read the 'Stability Considerations' section in the qmp-commands.txt file before making any serious use of QMP. [1] http://www.json.org Usage ----- To enable QMP, you need a QEMU monitor instance in "control mode". There are two ways of doing this. The simplest one is using the '-qmp' command-line option. The following example makes QMP available on localhost port 4444: $ qemu [...] -qmp tcp:localhost:4444,server However, in order to have more complex combinations, like multiple monitors, the '-mon' command-line option should be used along with the '-chardev' one. For instance, the following example creates one user monitor on stdio and one QMP monitor on localhost port 4444. $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \ -chardev socket,id=mon1,host=localhost,port=4444,server \ -mon chardev=mon1,mode=control 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": 13, "major": 0}, "package": ""}, "capabilities": []}} { "execute": "qmp_capabilities" } {"return": {}} { "execute": "query-version" } {"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}} Development Process ------------------- When changing QMP's interface (by adding new commands, events or modifying existing ones) it's mandatory to update the relevant documentation, which is one (or more) of the files listed in the 'Introduction' section*. Also, it's strongly recommended to send the documentation patch first, before doing any code change. This is so because: 1. Avoids the code dictating the interface 2. Review can improve your interface. Letting that happen before you implement it can save you work. * The qmp-commands.txt file is generated from the qmp-commands.hx one, which is the file that should be edited. Homepage -------- http://wiki.qemu.org/QMP