Return to README CVS log

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

Annotation of qemu/QMP/README, revision 1.1.1.2

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: 
                     22: There are also two simple Python scripts available:
                     23: 
1.1.1.2 ! root       24: o qmp-shell  A shell
        !            25: o vm-info    Show some information about the Virtual Machine
        !            26: 
        !            27: IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
        !            28: section in the qmp-commands.txt file before making any serious use of QMP.
        !            29: 
1.1       root       30: 
                     31: [1] http://www.json.org
                     32: 
                     33: Usage
                     34: -----
                     35: 
1.1.1.2 ! root       36: To enable QMP, you need a QEMU monitor instance in "control mode". There are
        !            37: two ways of doing this.
        !            38: 
        !            39: The simplest one is using the '-qmp' command-line option. The following
        !            40: example makes QMP available on localhost port 4444:
1.1       root       41: 
1.1.1.2 ! root       42:   $ qemu [...] -qmp tcp:localhost:4444,server
1.1       root       43: 
1.1.1.2 ! root       44: However, in order to have more complex combinations, like multiple monitors,
        !            45: the '-mon' command-line option should be used along with the '-chardev' one.
        !            46: For instance, the following example creates one user monitor on stdio and one
        !            47: QMP monitor on localhost port 4444.
1.1       root       48: 
1.1.1.2 ! root       49:    $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
        !            50:                 -chardev socket,id=mon1,host=localhost,port=4444,server \
        !            51:                 -mon chardev=mon1,mode=control
1.1       root       52: 
1.1.1.2 ! root       53: Please, refer to QEMU's manpage for more information.
1.1       root       54: 
                     55: Simple Testing
                     56: --------------
                     57: 
1.1.1.2 ! root       58: To manually test QMP one can connect with telnet and issue commands by hand:
1.1       root       59: 
                     60: $ telnet localhost 4444
                     61: Trying 127.0.0.1...
                     62: Connected to localhost.
                     63: Escape character is '^]'.
1.1.1.2 ! root       64: {"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
        !            65: { "execute": "qmp_capabilities" }
        !            66: {"return": {}}
1.1       root       67: { "execute": "query-version" }
1.1.1.2 ! root       68: {"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
        !            69: 
        !            70: Development Process
        !            71: -------------------
        !            72: 
        !            73: When changing QMP's interface (by adding new commands, events or modifying
        !            74: existing ones) it's mandatory to update the relevant documentation, which is
        !            75: one (or more) of the files listed in the 'Introduction' section*.
        !            76: 
        !            77: Also, it's strongly recommended to send the documentation patch first, before
        !            78: doing any code change. This is so because:
        !            79: 
        !            80:   1. Avoids the code dictating the interface
        !            81: 
        !            82:   2. Review can improve your interface.  Letting that happen before
        !            83:      you implement it can save you work.
        !            84: 
        !            85: * The qmp-commands.txt file is generated from the qemu-monitor.hx one, which
        !            86:   is the file that should be edited.
1.1       root       87: 
1.1.1.2 ! root       88: Homepage
        !            89: --------
1.1       root       90: 
1.1.1.2 ! root       91: http://wiki.qemu.org/QMP

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