QMP/README

   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
  10 QMP is JSON[1] based and currently has the following features:
  11
  12 - Lightweight, text-based, easy to parse data format
  13 - Asynchronous messages support (ie. events)
  14 - Capabilities Negotiation
  15
  16 For detailed information on QMP's usage, please, refer to the following files:
  17
  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
  21
  22 There are also two simple Python scripts available:
  23
  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
  30
  31 [1] http://www.json.org
  32
  33 Usage
  34 -----
  35
  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:
  41
  42   $ qemu [...] -qmp tcp:localhost:4444,server
  43
  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.
  48
  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
  52
  53 Please, refer to QEMU's manpage for more information.
  54
  55 Simple Testing
  56 --------------
  57
  58 To manually test QMP one can connect with telnet and issue commands by hand:
  59
  60 $ telnet localhost 4444
  61 Trying 127.0.0.1...
  62 Connected to localhost.
  63 Escape character is '^]'.
  64 {"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
  65 { "execute": "qmp_capabilities" }
  66 {"return": {}}
  67 { "execute": "query-version" }
  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 qmp-commands.hx one, which
  86   is the file that should be edited.
  87
  88 Homepage
  89 --------
  90
  91 http://wiki.qemu.org/QMP