QMP/qmp-spec.txt

   1            QEMU Monitor Protocol Draft Specification - Version 0.1
   2
   3 1. Introduction
   4 ===============
   5
   6 This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
   7 which is available for applications to control QEMU at the machine-level.
   8
   9 To enable QMP support, QEMU has to be run in "control mode". This is done by
  10 starting QEMU with the appropriate command-line options. Please, refer to the
  11 QEMU manual page for more information.
  12
  13 2. Protocol Specification
  14 =========================
  15
  16 This section details the protocol format. For the purpose of this document
  17 "Client" is any application which is communicating with QEMU in control mode,
  18 and "Server" is QEMU itself.
  19
  20 JSON data structures, when mentioned in this document, are always in the
  21 following format:
  22
  23     json-DATA-STRUCTURE-NAME
  24
  25 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
  26 the JSON standard:
  27
  28 http://www.ietf.org/rfc/rfc4627.txt
  29
  30 For convenience, json-objects mentioned in this document will have its members
  31 in a certain order. However, in real protocol usage json-objects members can
  32 be in ANY order, thus no particular order should be assumed.
  33
  34 2.1 General Definitions
  35 -----------------------
  36
  37 2.1.1 All interactions transmitted by the Server are json-objects, always
  38       terminating with CRLF
  39
  40 2.1.2 All json-objects members are mandatory when not specified otherwise
  41
  42 2.2 Server Greeting
  43 -------------------
  44
  45 Right when connected the Server will issue a greeting message, which signals
  46 that the connection has been successfully established and that the Server is
  47 waiting for commands.
  48
  49 The format is:
  50
  51 { "QMP": { "capabilities": json-array } }
  52
  53  Where,
  54
  55 - The "capabilities" member specify the availability of features beyond the
  56   baseline specification
  57
  58 2.3 Issuing Commands
  59 --------------------
  60
  61 The format for command execution is:
  62
  63 { "execute": json-string, "arguments": json-object, "id": json-value }
  64
  65  Where,
  66
  67 - The "execute" member identifies the command to be executed by the Server
  68 - The "arguments" member is used to pass any arguments required for the
  69   execution of the command, it is optional when no arguments are required
  70 - The "id" member is a transaction identification associated with the
  71   command execution, it is optional and will be part of the response if
  72   provided
  73
  74 2.4 Commands Responses
  75 ----------------------
  76
  77 There are two possible responses which the Server will issue as the result
  78 of a command execution: success or error.
  79
  80 2.4.1 success
  81 -------------
  82
  83 The success response is issued when the command execution has finished
  84 without errors.
  85
  86 The format is:
  87
  88 { "return": json-value, "id": json-value }
  89
  90  Where,
  91
  92 - The "return" member contains the command returned data, which is defined
  93   in a per-command basis or "OK" if the command does not return data
  94 - The "id" member contains the transaction identification associated
  95   with the command execution (if issued by the Client)
  96
  97 2.4.2 error
  98 -----------
  99
 100 The error response is issued when the command execution could not be
 101 completed because of an error condition.
 102
 103 The format is:
 104
 105 { "error": { "class": json-string, "data": json-value, "desc": json-string },
 106   "id": json-value }
 107
 108  Where,
 109
 110 - The "class" member contains the error class name (eg. "ServiceUnavailable")
 111 - The "data" member contains specific error data and is defined in a
 112   per-command basis, it will be an empty json-object if the error has no data
 113 - The "desc" member is a human-readable error message.  Clients should
 114   not attempt to parse this message.
 115 - The "id" member contains the transaction identification associated with
 116   the command execution (if issued by the Client)
 117
 118 NOTE: Some errors can occur before the Server is able to read the "id" member,
 119 in these cases the "id" member will not be part of the error response, even
 120 if provided by the client.
 121
 122 2.5 Asynchronous events
 123 -----------------------
 124
 125 As a result of state changes, the Server may send messages unilaterally
 126 to the Client at any time. They are called 'asynchronous events'.
 127
 128 The format is:
 129
 130 { "event": json-string, "data": json-value,
 131   "timestamp": { "seconds": json-number, "microseconds": json-number } }
 132
 133  Where,
 134
 135 - The "event" member contains the event's name
 136 - The "data" member contains event specific data, which is defined in a
 137   per-event basis, it is optional
 138 - The "timestamp" member contains the exact time of when the event ocurred
 139   in the Server. It is a fixed json-object with time in seconds and
 140   microseconds
 141
 142 For a listing of supported asynchronous events, please, refer to the
 143 qmp-events.txt file.
 144
 145 3. QMP Examples
 146 ===============
 147
 148 This section provides some examples of real QMP usage, in all of them
 149 'C' stands for 'Client' and 'S' stands for 'Server'.
 150
 151 3.1 Server greeting
 152 -------------------
 153
 154 S: {"QMP": {"capabilities": []}}
 155
 156 3.2 Simple 'stop' execution
 157 ---------------------------
 158
 159 C: { "execute": "stop" }
 160 S: {"return": "OK"}
 161
 162 3.3 KVM information
 163 -------------------
 164
 165 C: {"execute": "query-kvm", "id": "example"}
 166 S: {"return": "enabled", "id": "example"}
 167
 168 3.4 Parsing error
 169 ------------------
 170
 171 C: { "execute": }
 172 S: {"error": {"class": "JSONParsing", "data": {}}}
 173
 174 3.5 Powerdown event
 175 -------------------
 176
 177 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 178 "POWERDOWN"}
 179
 180 4. Notes to Client implementors
 181 -------------------------------
 182
 183 4.1 It is recommended to always start the Server in pause mode, thus the
 184     Client is able to perform any setup procedure without the risk of
 185     race conditions and related problems
 186
 187 4.2 It is recommended to always check the capabilities json-array, issued
 188     with the greeting message, at connection time
 189
 190 4.3 Json-objects or json-arrays mentioned in this document are not fixed
 191     and no particular size or number of members/elements should be assumed.
 192     New members/elements can be added at any time.
 193
 194 4.4 No particular order of json-objects members should be assumed, they
 195     can change at any time