[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 17/20] QMP: Introduce specification
From: |
Luiz Capitulino |
Subject: |
[Qemu-devel] [PATCH 17/20] QMP: Introduce specification |
Date: |
Thu, 26 Nov 2009 22:59:07 -0200 |
Signed-off-by: Luiz Capitulino <address@hidden>
---
QMP/qmp-spec.txt | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 192 insertions(+), 0 deletions(-)
create mode 100644 QMP/qmp-spec.txt
diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
new file mode 100644
index 0000000..8429789
--- /dev/null
+++ b/QMP/qmp-spec.txt
@@ -0,0 +1,192 @@
+ QEMU Monitor Protocol Draft Specification - Version 0.1
+
+1. Introduction
+===============
+
+This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
+which is available for applications to control QEMU at the machine-level.
+
+To enable QMP support, QEMU has to be run in "control mode". This is done by
+starting QEMU with the appropriate command-line options. Please, refer to the
+QEMU manual page for more information.
+
+2. Protocol Specification
+=========================
+
+This section details the protocol format. For the purpose of this document
+"Client" is any application which is communicating with QEMU in control mode,
+and "Server" is QEMU itself.
+
+JSON data structures, when mentioned in this document, are always in the
+following format:
+
+ json-DATA-STRUCTURE-NAME
+
+Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
+the JSON standard:
+
+http://www.ietf.org/rfc/rfc4627.txt
+
+For convenience, json-objects mentioned in this document will have its members
+in a certain order. However, in real protocol usage json-objects members can
+be in ANY order, thus no particular order should be assumed.
+
+2.1 General Definitions
+-----------------------
+
+2.1.1 All interactions transmitted by the Server are json-objects, always
+ terminating with CRLF
+
+2.1.2 All json-objects members are mandatory when not specified otherwise
+
+2.2 Server Greeting
+-------------------
+
+Right when connected the Server will issue a greeting message, which signals
+that the connection has been successfully established and that the Server is
+waiting for commands.
+
+The format is:
+
+{ "QMP": { "capabilities": json-array } }
+
+ Where,
+
+- The "capabilities" member specify the availability of features beyond the
+ baseline specification
+
+2.3 Issuing Commands
+--------------------
+
+The format for command execution is:
+
+{ "execute": json-string, "arguments": json-object, "id": json-value }
+
+ Where,
+
+- The "execute" member identifies the command to be executed by the Server
+- The "arguments" member is used to pass any arguments required for the
+ execution of the command, it is optional when no arguments are required
+- The "id" member is a transaction identification associated with the
+ command execution, it is optional and will be part of the response if
+ provided
+
+2.4 Commands Responses
+----------------------
+
+There are two possible responses which the Server will issue as the result
+of a command execution: success or error.
+
+2.4.1 success
+-------------
+
+The success response is issued when the command execution has finished
+without errors.
+
+The format is:
+
+{ "return": json-value, "id": json-value }
+
+ Where,
+
+- The "return" member contains the command returned data, which is defined
+ in a per-command basis or "OK" if the command does not return data
+- The "id" member contains the transaction identification associated
+ with the command execution (if issued by the Client)
+
+2.4.2 error
+-----------
+
+The error response is issued when the command execution could not be
+completed because of an error condition.
+
+The format is:
+
+{ "error": { "class": json-string, "data": json-value }, "id": json-value }
+
+ Where,
+
+- The "class" member contains the error class name (eg. "ServiceUnavailable")
+- The "data" member contains specific error data and is defined in a
+ per-command basis, it will be an empty json-object if the error has no data
+- The "id" member contains the transaction identification associated with
+ the command execution (if issued by the Client)
+
+NOTE: Some errors can occur before the Server is able to read the "id" member,
+in these cases the "id" member will not be part of the error response, even
+if provided by the client.
+
+2.5 Asynchronous events
+-----------------------
+
+As a result of state changes, the Server may send messages unilaterally
+to the Client at any time. They are called 'asynchronous events'.
+
+The format is:
+
+{ "event": json-string, "data": json-value,
+ "timestamp": { "seconds": json-number, "microseconds": json-number } }
+
+ Where,
+
+- The "event" member contains the event's name
+- The "data" member contains event specific data, which is defined in a
+ per-event basis, it is optional
+- The "timestamp" member contains the exact time of when the event ocurred
+ in the Server. It is a fixed json-object with time in seconds and
+ microseconds
+
+For a listing of supported asynchronous events, please, refer to the
+qmp-events.txt file.
+
+3. QMP Examples
+===============
+
+This section provides some examples of real QMP usage, in all of them
+'C' stands for 'Client' and 'S' stands for 'Server'.
+
+3.1 Server greeting
+-------------------
+
+S: {"QMP": {"capabilities": []}}
+
+3.2 Simple 'stop' execution
+---------------------------
+
+C: { "execute": "stop" }
+S: {"return": "OK"}
+
+3.3 KVM information
+-------------------
+
+C: {"execute": "query-kvm", "id": "example"}
+S: {"return": "enabled", "id": "example"}
+
+3.4 Parsing error
+------------------
+
+C: { "execute": }
+S: {"error": {"class": "JSONParsing", "data": {}}}
+
+3.5 Powerdown event
+-------------------
+
+S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
+"POWERDOWN"}
+
+4. Notes to Client implementors
+-------------------------------
+
+4.1 It is recommended to always start the Server in pause mode, thus the
+ Client is able to perform any setup procedure without the risk of
+ race conditions and related problems
+
+4.2 It is recommended to always check the capabilities json-array, issued
+ with the greeting message, at connection time
+
+4.3 Json-objects or json-arrays mentioned in this document are not fixed
+ and no particular size or number of members/elements should be assumed.
+ New members/elements can be added at any time.
+
+4.4 No particular order of json-objects members should be assumed, they
+ can change at any time
--
1.6.6.rc0.50.gaf06e
- [Qemu-devel] [PATCH 07/20] QError: Add errors needed by QMP, (continued)
- [Qemu-devel] [PATCH 07/20] QError: Add errors needed by QMP, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 08/20] QMP: Initial support, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 09/20] QMP: Output support, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 10/20] QMP: do_info() checks, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 11/20] QMP: Input support, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 12/20] QMP: Allow 'query-' commands, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 13/20] QMP: Asynchronous events infrastructure, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 14/20] QMP: Introduce basic asynchronous events, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 15/20] QMP: Disable monitor print functions, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 16/20] QMP: Introduce README file, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 17/20] QMP: Introduce specification,
Luiz Capitulino <=
- [Qemu-devel] [PATCH 18/20] QMP: Introduce qmp-events.txt, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 19/20] QMP: Introduce qmp-shell, Luiz Capitulino, 2009/11/26
- [Qemu-devel] [PATCH 20/20] QMP: Introduce vm-info, Luiz Capitulino, 2009/11/26