LXR qemu/docs/qmp-intro.txt

   1                          QEMU Machine Protocol
   2                          =====================
   3
   4Introduction
   5------------
   6
   7The QEMU Machine Protocol (QMP) allows applications to operate a
   8QEMU instance.
   9
  10QMP is JSON[1] based and features the following:
  11
  12- Lightweight, text-based, easy to parse data format
  13- Asynchronous messages support (ie. events)
  14- Capabilities Negotiation
  15
  16For detailed information on QMP's usage, please, refer to the following files:
  17
  18o qmp-spec.txt      QEMU Machine Protocol current specification
  19o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
  20o qmp-events.txt    List of available asynchronous events
  21
  22[1] http://www.json.org
  23
  24Usage
  25-----
  26
  27You can use the -qmp option to enable QMP. For example, the following
  28makes QMP available on localhost port 4444:
  29
  30$ qemu [...] -qmp tcp:localhost:4444,server,nowait
  31
  32However, for more flexibility and to make use of more options, the -mon
  33command-line option should be used. For instance, the following example
  34creates one HMP instance (human monitor) on stdio and one QMP instance
  35on localhost port 4444:
  36
  37$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
  38             -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
  39             -mon chardev=mon1,mode=control,pretty=on
  40
  41Please, refer to QEMU's manpage for more information.
  42
  43Simple Testing
  44--------------
  45
  46To manually test QMP one can connect with telnet and issue commands by hand:
  47
  48$ telnet localhost 4444
  49Trying 127.0.0.1...
  50Connected to localhost.
  51Escape character is '^]'.
  52{
  53    "QMP": {
  54        "version": {
  55            "qemu": {
  56                "micro": 50, 
  57                "minor": 6, 
  58                "major": 1
  59            }, 
  60            "package": ""
  61        }, 
  62        "capabilities": [
  63        ]
  64    }
  65}
  66
  67{ "execute": "qmp_capabilities" }
  68{
  69    "return": {
  70    }
  71}
  72
  73{ "execute": "query-status" }
  74{
  75    "return": {
  76        "status": "prelaunch", 
  77        "singlestep": false, 
  78        "running": false
  79    }
  80}
  81
  82Please, refer to the qapi-schema.json file for a complete command reference.
  83
  84QMP wiki page
  85-------------
  86
  87http://wiki.qemu-project.org/QMP
  88