Return to README CVS log

Up to [Qemu by Fabrice Bellard] / qemu / QMP

Annotation of qemu/QMP/README, revision 1.1.1.3

1.1       root        1:                           QEMU Monitor Protocol
                      2:                           =====================
                      3: 
                      4: Introduction
                      5: -------------
                      6: 
                      7: The QEMU Monitor Protocol (QMP) allows applications to communicate with
                      8: QEMU's Monitor.
                      9: 
1.1.1.2   root       10: QMP is JSON[1] based and currently has the following features:
1.1       root       11: 
                     12: - Lightweight, text-based, easy to parse data format
1.1.1.2   root       13: - Asynchronous messages support (ie. events)
                     14: - Capabilities Negotiation
1.1       root       15: 
1.1.1.2   root       16: For detailed information on QMP's usage, please, refer to the following files:
1.1       root       17: 
1.1.1.2   root       18: o qmp-spec.txt      QEMU Monitor Protocol current specification
                     19: o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
                     20: o qmp-events.txt    List of available asynchronous events
1.1       root       21: 
1.1.1.3 ! root       22: There is also a simple Python script called 'qmp-shell' available.
1.1.1.2   root       23: 
                     24: IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
                     25: section in the qmp-commands.txt file before making any serious use of QMP.
                     26: 
1.1       root       27: 
                     28: [1] http://www.json.org
                     29: 
                     30: Usage
                     31: -----
                     32: 
1.1.1.2   root       33: To enable QMP, you need a QEMU monitor instance in "control mode". There are
                     34: two ways of doing this.
                     35: 
                     36: The simplest one is using the '-qmp' command-line option. The following
                     37: example makes QMP available on localhost port 4444:
1.1       root       38: 
1.1.1.2   root       39:   $ qemu [...] -qmp tcp:localhost:4444,server
1.1       root       40: 
1.1.1.2   root       41: However, in order to have more complex combinations, like multiple monitors,
                     42: the '-mon' command-line option should be used along with the '-chardev' one.
                     43: For instance, the following example creates one user monitor on stdio and one
                     44: QMP monitor on localhost port 4444.
1.1       root       45: 
1.1.1.2   root       46:    $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
                     47:                 -chardev socket,id=mon1,host=localhost,port=4444,server \
                     48:                 -mon chardev=mon1,mode=control
1.1       root       49: 
1.1.1.2   root       50: Please, refer to QEMU's manpage for more information.
1.1       root       51: 
                     52: Simple Testing
                     53: --------------
                     54: 
1.1.1.2   root       55: To manually test QMP one can connect with telnet and issue commands by hand:
1.1       root       56: 
                     57: $ telnet localhost 4444
                     58: Trying 127.0.0.1...
                     59: Connected to localhost.
                     60: Escape character is '^]'.
1.1.1.2   root       61: {"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
                     62: { "execute": "qmp_capabilities" }
                     63: {"return": {}}
1.1       root       64: { "execute": "query-version" }
1.1.1.2   root       65: {"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
                     66: 
                     67: Development Process
                     68: -------------------
                     69: 
                     70: When changing QMP's interface (by adding new commands, events or modifying
                     71: existing ones) it's mandatory to update the relevant documentation, which is
                     72: one (or more) of the files listed in the 'Introduction' section*.
                     73: 
                     74: Also, it's strongly recommended to send the documentation patch first, before
                     75: doing any code change. This is so because:
                     76: 
                     77:   1. Avoids the code dictating the interface
                     78: 
                     79:   2. Review can improve your interface.  Letting that happen before
                     80:      you implement it can save you work.
                     81: 
1.1.1.3 ! root       82: * The qmp-commands.txt file is generated from the qmp-commands.hx one, which
1.1.1.2   root       83:   is the file that should be edited.
1.1       root       84: 
1.1.1.2   root       85: Homepage
                     86: --------
1.1       root       87: 
1.1.1.2   root       88: http://wiki.qemu.org/QMP

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.