From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MIxcN-0007X3-SV for qemu-devel@nongnu.org; Tue, 23 Jun 2009 00:28:23 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MIxcJ-0007RO-5x for qemu-devel@nongnu.org; Tue, 23 Jun 2009 00:28:23 -0400 Received: from [199.232.76.173] (port=35667 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MIxcI-0007R9-Qy for qemu-devel@nongnu.org; Tue, 23 Jun 2009 00:28:18 -0400 Received: from mx2.redhat.com ([66.187.237.31]:32782) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MIxcI-00033q-7M for qemu-devel@nongnu.org; Tue, 23 Jun 2009 00:28:18 -0400 Date: Tue, 23 Jun 2009 01:28:11 -0300 From: Luiz Capitulino Message-ID: <20090623012811.53a62493@doriath> In-Reply-To: References: Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Subject: [Qemu-devel] [PATCH 01/11] QMP: Introduce specification file 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, ehabkost@redhat.com, jan.kiszka@siemens.com, dlaor@redhat.com, avi@redhat.com This file contains detailed QMP description and definitions. Signed-off-by: Luiz Capitulino --- monitor-protocol-spec.txt | 180 +++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 180 insertions(+), 0 deletions(-) create mode 100644 monitor-protocol-spec.txt diff --git a/monitor-protocol-spec.txt b/monitor-protocol-spec.txt new file mode 100644 index 0000000..d20e3f9 --- /dev/null +++ b/monitor-protocol-spec.txt @@ -0,0 +1,180 @@ + QEMU Monitor Protocol Specification - Version 0.1 + + Luiz Capitulino + + +1. Introduction +=============== + +This document specifies the QEMU Monitor Protocol (QMP), a text-based protocol +which is available for applications to control QEMU at the machine-level. + +For a detailed list of supported commands, please, refer to file +monitor-protocol-commands.txt. + +2. Control Mode +=============== + +In order to enable QMP support, QEMU must start its Monitor subsystem in +"control mode" rather than the default "user mode". + +Currently, this is done by passing the following command-line option to +QEMU: + +-monitor control, + +Please, refer to QEMU manpage or user-manual for more details. + +3. Protocol Specification +========================= + +This section details the protocol format. For the purpose of this document +"client" is any application that is communication with QEMU in control mode, +and "server" is QEMU itself. + +3.1 General definition +---------------------- + + o Only ASCII is permitted + o Case-insensitive + o All lines are terminated with CRLF + +3.2 Client Issued Commands +-------------------------- + + o Arguments are separated by single space + o Arguments, responses and errors are defined separately by each command + +3.3 Server responses +-------------------- + + There are four types of responses the server may send to the client: +greeting, command completion, command data and asynchronous messages. + +3.3.1 Server Greeting +--------------------- + +Sent when a new connection is opened. + +Format: + OK QEMU QMP +Example: + OK QEMU 0.10.50 QMP 0.1 + +3.3.2 Server Command Completion +------------------------------- + +Indicates that the execution of the last command has finished, there are +three possible responses, as outlined below. + + o Command completion was successful + + Format: + OK completed + Example: + OK stop completed + + o Command completion failed + + Format: - ERR + Example: - ERR could not find network device 'foo' + + o Protocol error + + Format: - BAD + Example: - BAD unknown command + +3.3.3 Server Command Data +------------------------- + +Output issued by commands will always be prefixed by '='. If it is a +multiline response, then each line is prefixed by '='. + +For example, the output of 'info network' would be: + += VLAN 0 devices: += user.0: += ne2k_pci.0: model=ne2k_pci,macaddr=52:54:00:12:34:56 + +3.3.4 Asynchronous Messages +--------------------------- + +Messages that can be sent unilaterally by the server, at any time. They are +always prefixed by '*'. + +Currently there is only one type of asynchronous messages supported, +known as 'events'. + +Format: * EVENT +Example: * EVENT reboot + +4. Examples +=========== + +This section provides some examples of the protocol in action, in all of +them 'C' stands for 'Client' and 'S' stands for 'Server'. + +4.1 Simple 'cont' Execution +--------------------------- + +Client started QEMU with the "-S" option, which makes QEMU do not start +the CPU at start up. Then Client issues the "cont" command. + +S: + OK QEMU 0.10.50 QMP 0.1 +C: cont +S: + OK cont completed + +4.2 Multiline Response +---------------------- + +Client queries the Server about the network. + +S: + OK QEMU 0.10.50 QMP 0.1 +C: info network +S: = VLAN 0 devices: +S: = user.0: +S: = ne2k_pci.0: model=ne2k_pci,macaddr=52:54:00:12:34:56 +S: + OK info network completed + +4.3 Events +---------- + +Client queries the Server about memory, but QEMU reboots. + +S: + OK QEMU 0.10.50 QMP 0.1 +C: info balloon +S: * EVENT reboot + +4.4 Protocol Error +------------------ + +Client issues an invalid command. + +S: + OK QEMU 0.10.50 QMP 0.1 +C: foo +S: - BAD unknown command + +4.5 Command Error +----------------- + +Client tries to change link status for a non existing device. + +S: + OK QEMU 0.10.50 QMP 0.1 +C: set_link foo down +S: - ERR could not find network device 'foo' + +5. Client Considerations +======================== + +This section contains some considerations for Client implementation. + + o If events are not supported, then lines starting with '*' should be + ignored and not considered errors + + o If events are supported, the Client must be prepared to deal with + events added in future protocol versions. The best way to do this is + to handle known events and ignore the others + +6. Protocol History +=================== + +v0.1 - 2009-06-19 +----------------- + + o Initial version -- 1.6.3.GIT