[Qemu-devel] [PATCH 01/11] QMP: Introduce specification file

[Luiz Capitulino <lcapitulino@redhat.com>]

This file contains detailed QMP description and definitions.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 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
+                            <lcapitulino@redhat.com>
+
+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,<device>
+
+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 <version> QMP <version>
+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 <command> completed
+    Example: + OK stop completed
+
+ o Command completion failed
+
+    Format: - ERR <reason>
+    Example: - ERR could not find network device 'foo'
+
+ o Protocol error
+
+    Format: - BAD <reason>
+    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 <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