From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MpuQx-0000Da-AV for qemu-devel@nongnu.org; Mon, 21 Sep 2009 21:44:47 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MpuQr-0000DL-MM for qemu-devel@nongnu.org; Mon, 21 Sep 2009 21:44:46 -0400 Received: from [199.232.76.173] (port=51560 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MpuQr-0000DH-HG for qemu-devel@nongnu.org; Mon, 21 Sep 2009 21:44:41 -0400 Received: from mx1.redhat.com ([209.132.183.28]:16512) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MpuQq-0005dI-Rk for qemu-devel@nongnu.org; Mon, 21 Sep 2009 21:44:41 -0400 Date: Mon, 21 Sep 2009 22:44:30 -0300 From: Luiz Capitulino Message-ID: <20090921224430.610da97b@doriath> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Subject: [Qemu-devel] ANN: QEMU Monitor Protocol git tree List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: aliguori@us.ibm.com, avi@redhat.com Hi there, While I was converting command handlers to the QObject style I realized that it would be very interesting to have the protocol working up front, so that converted handlers could be tested to assure that their data types have been chosen correctly. More importantly, some protocol design decisions can affect handlers signatures, so having at least an idea of how the protocol will look like will help us to stay on the right track during mass conversion. So, I have implemented a rudimentary version of the QEMU Monitor Protocol (QMP) it has a command-line switch to enable the protocol. You will find it at: http://repo.or.cz/w/qemu/qmp-unstable.git The QMP directory of that tree has some documents plus a Python script which communicates with QEMU by using the protocol and emulates a shell, although only few commands are working.. Now the controversial part: it's json based. ;) I have chosen json because of the reasons already explained by others in the original QMP thread. Basically, json is so simple that if we design a small protocol from scratch, chances are it will look like json. What follows is the protocol draft spec. I will not post the patches because the current implementation is buggy and limited, but it will improve in the next weeks, as I'm going to work on it in parallel with the conversions. Thanks. """ 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. This specification is a work in progress and part of it may NOT be available in QEMU, the 'Current Implementation' section has details regarding what has already been implemented and known problems. 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 ----------------------- All interactions transmitted by Client and Server are json-objects that end with CRLF. 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: { "QEMU": json-string, "QMP": json-string, "capabilities": json-array } Where, - The "QEMU" member contains the QEMU version - The "QMP" member contains the QMP version - 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, "id": json-value, "arguments": json-object } Where, - The "execute" member identifies the command to be executed by the Server - The "id" member is a transaction identification associated with the command execution, it is optional - The "arguments" member is used to pass any arguments required for the execution of the command, it is optional when no arguments are required For a listing of supported commands and theirs arguments, please, refer to the qmp-command-set.txt file. 2.4 Commands Execution ---------------------- TODO: explain parallel execution and the "id" member. 2.5 Commands Responses ---------------------- There are two possible responses which the Server will issue as the result of a command completion: success or error. 2.5.1 success ------------- The success response is issued when the command execution has finished without errors. The format is: { "return": json-value, "id": json-value, "timestamp": json-string } Where, - The "return" member contains the command returned data, which is defined in a per-command basis or json-null if the command does not return data - The "id" member contains the transaction identification associated with the command execution (if issued by the Client) - The "timestamp" member contains the exact time of when the response was generated by the Server (FIXME: format) 2.5.2 error ----------- The error response is issued when the command execution could not be completed because of an error condition. The format is: { "error": { "code": json-number, "desc": json-string, "data": json-value } "id": json-value, "timestamp": json-string } Where, - The "code" member contains the error code. Its first digit indicates the error type, as show below: 1 Server 2 Protocol 3 Command Specific - The "desc" member contains the error description - The "data" member contains specific error data, it is optional - The "id" member contains the transaction identification associated with the command execution (if issued by the Client) - The "timestamp" member contains the exact time of when the response was generated by the Server (FIXME: format) Section '2.7 Server and Protocol errors' contains additional information about error handling. 2.6 Asynchronous events ----------------------- As a result of state changes, the Server may send messages unilaterally to the Client at any time. This is called 'asynchronous events'. The format is: { "event": json-string, "timestamp": json-string, "data": json-value } Where, - The "event" member contains the event's name - The "timestamp" member contains the exact time of when the event happend in the Server (FIXME: format) - The "data" member contains event specific data, which is defined in a per-event basis, it is optional For a listing of supported asynchronous events, please, refer to the qmp-command-set.txt file. 2.7 Server and Protocol errors ------------------------------ TODO: describe all possible server and protocol errors. 3. 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 Simple 'stop' execution --------------------------- S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] } C: { "execute": "stop" } S: { "return": null, "timestamp": "" } 3.2 KVM information ------------------- S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] } C: { "execute": "info", "id": 1, "arguments": { "item": "kvm" } } S: { "return": "enabled", "id": 1, "timestamp": "" } 3.3 Error on 'info balloon' execution ------------------------------------- S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] } C: { "execute": "info", "id": "abc", "arguments": { "item": "balloon" } } S: { "error": { "code": 354, "Ballooning not activated in VM" }, "id": "abc", "timestamp": "" } 3.4 Powerdown event ------------------- S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] } ... S: { "event": "POWERDOWN", "timestamp": "" } ... 4. Current Implementation ========================= The current QMP implementation lacks some of the protocol capabilities specified in this document. The most important one is the execution of commands as discussed in the section '2.3 Issuing Commands'. Currently the Server does not support it. Protocol input is done by issuing regular ASCII strings, as it is done when using the humam Monitor protocol. For example, to query the current balloon information the Client should issue: "info balloon\r\n" Additionally, the following limitations are present: - The transaction "id" is not supported - json-strings issued by the Server are not in Unicode format - All "timestamp" members are always an empty json-string "" - Error handling is basically not implemented """