[Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Luiz Capitulino]

Simplify the text, fix some of the examples.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
 1 file changed, 28 insertions(+), 37 deletions(-)

diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
index a277896..22568c6 100644
--- a/docs/qmp/qmp-spec.txt
+++ b/docs/qmp/qmp-spec.txt
@@ -1,21 +1,17 @@
-           QEMU Monitor Protocol Specification - Version 0.1
+                      QEMU Machine Protocol Specification
 
 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 document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol
+which is available for applications to operate QEMU at the machine-level.
 
 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.
+"Client" is any application which is using QMP to communicate with QEMU and
+"Server" is QEMU itself.
 
 JSON data structures, when mentioned in this document, are always in the
 following format:
@@ -47,14 +43,14 @@ that the connection has been successfully established and that the Server is
 ready for capabilities negotiation (for more information refer to section
 '4. Capabilities Negotiation').
 
-The format is:
+The greeting message format is:
 
 { "QMP": { "version": json-object, "capabilities": json-array } }
 
  Where,
 
 - The "version" member contains the Server's version information (the format
-  is the same of the 'query-version' command)
+  is the same of the query-version command)
 - The "capabilities" member specify the availability of features beyond the
   baseline specification
 
@@ -83,10 +79,7 @@ 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:
+The format of a success response is:
 
 { "return": json-object, "id": json-value }
 
@@ -96,15 +89,12 @@ The format is:
   in a per-command basis or an empty json-object if the command does not
   return data
 - The "id" member contains the transaction identification associated
-  with the command execution (if issued by the Client)
+  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:
+The format of an error response is:
 
 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
 
@@ -114,7 +104,7 @@ The format is:
 - The "desc" member is a human-readable error message. Clients should
   not attempt to parse this message.
 - The "id" member contains the transaction identification associated with
-  the command execution (if issued by the Client)
+  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
@@ -124,9 +114,9 @@ if provided by the client.
 -----------------------
 
 As a result of state changes, the Server may send messages unilaterally
-to the Client at any time. They are called 'asynchronous events'.
+to the Client at any time. They are called "asynchronous events".
 
-The format is:
+The format of asynchronous events is:
 
 { "event": json-string, "data": json-object,
   "timestamp": { "seconds": json-number, "microseconds": json-number } }
@@ -147,36 +137,37 @@ qmp-events.txt file.
 ===============
 
 This section provides some examples of real QMP usage, in all of them
-'C' stands for 'Client' and 'S' stands for 'Server'.
+"C" stands for "Client" and "S" stands for "Server".
 
 3.1 Server greeting
 -------------------
 
-S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
+S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
+     "package": ""}, "capabilities": []}}
 
 3.2 Simple 'stop' execution
 ---------------------------
 
 C: { "execute": "stop" }
-S: {"return": {}}
+S: { "return": {} }
 
 3.3 KVM information
 -------------------
 
 C: { "execute": "query-kvm", "id": "example" }
-S: {"return": {"enabled": true, "present": true}, "id": "example"}
+S: { "return": { "enabled": true, "present": true }, "id": "example"}
 
 3.4 Parsing error
 ------------------
 
 C: { "execute": }
-S: {"error": {"class": "GenericError", "desc": "Invalid JSON syntax" } }
+S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
 
 3.5 Powerdown event
 -------------------
 
-S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
-"POWERDOWN"}
+S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
+    "event": "POWERDOWN" }
 
 4. Capabilities Negotiation
 ----------------------------
@@ -184,17 +175,17 @@ S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 When a Client successfully establishes a connection, the Server is in
 Capabilities Negotiation mode.
 
-In this mode only the 'qmp_capabilities' command is allowed to run, all
-other commands will return the CommandNotFound error. Asynchronous messages
-are not delivered either.
+In this mode only the qmp_capabilities command is allowed to run, all
+other commands will return the CommandNotFound error. Asynchronous
+messages are not delivered either.
 
-Clients should use the 'qmp_capabilities' command to enable capabilities
+Clients should use the qmp_capabilities command to enable capabilities
 advertised in the Server's greeting (section '2.2 Server Greeting') they
 support.
 
-When the 'qmp_capabilities' command is issued, and if it does not return an
+When the qmp_capabilities command is issued, and if it does not return an
 error, the Server enters in Command mode where capabilities changes take
-effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
+effect, all commands (except qmp_capabilities) are allowed and asynchronous
 messages are delivered.
 
 5 Compatibility Considerations
@@ -245,7 +236,7 @@ arguments, errors, asynchronous events, and so forth.
 
 Any new names downstream wishes to add must begin with '__'.  To
 ensure compatibility with other downstreams, it is strongly
-recommended that you prefix your downstram names with '__RFQDN_' where
+recommended that you prefix your downstream names with '__RFQDN_' where
 RFQDN is a valid, reverse fully qualified domain name which you
 control.  For example, a qemu-kvm specific monitor command would be:
 
-- 
1.8.1.4

Re: [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 880 bytes --]

On 09/11/2013 02:52 PM, Luiz Capitulino wrote:
> Simplify the text, fix some of the examples.
> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
>  1 file changed, 28 insertions(+), 37 deletions(-)

> 
> diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
> index a277896..22568c6 100644
> --- a/docs/qmp/qmp-spec.txt
> +++ b/docs/qmp/qmp-spec.txt
> @@ -1,21 +1,17 @@
> -           QEMU Monitor Protocol Specification - Version 0.1
> +                      QEMU Machine Protocol Specification

Do we want a protocol version number?  I guess if we ever add
capabilities, we can worry about it then.

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]

Re: [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Luiz Capitulino]

On Wed, 11 Sep 2013 17:27:58 -0600
Eric Blake <eblake@redhat.com> wrote:

> On 09/11/2013 02:52 PM, Luiz Capitulino wrote:
> > Simplify the text, fix some of the examples.
> > 
> > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> > ---
> >  docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
> >  1 file changed, 28 insertions(+), 37 deletions(-)
> 
> > 
> > diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
> > index a277896..22568c6 100644
> > --- a/docs/qmp/qmp-spec.txt
> > +++ b/docs/qmp/qmp-spec.txt
> > @@ -1,21 +1,17 @@
> > -           QEMU Monitor Protocol Specification - Version 0.1
> > +                      QEMU Machine Protocol Specification
> 
> Do we want a protocol version number?  I guess if we ever add
> capabilities, we can worry about it then.

Yes, but I don't think we want it. This is the sole place where
a version number appears and it's quite meaningless.

> 
> Reviewed-by: Eric Blake <eblake@redhat.com>
> 

Re: [Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1054 bytes --]

On 09/13/2013 11:54 AM, Luiz Capitulino wrote:
> On Wed, 11 Sep 2013 17:27:58 -0600
> Eric Blake <eblake@redhat.com> wrote:
> 
>> On 09/11/2013 02:52 PM, Luiz Capitulino wrote:
>>> Simplify the text, fix some of the examples.
>>>

>>> -           QEMU Monitor Protocol Specification - Version 0.1
>>> +                      QEMU Machine Protocol Specification
>>
>> Do we want a protocol version number?  I guess if we ever add
>> capabilities, we can worry about it then.
> 
> Yes, but I don't think we want it. This is the sole place where
> a version number appears and it's quite meaningless.

Indeed, capabilities are more powerful than version numbers, and since
the initial version already included capabilities, we already have as
much as we need to support any arbitrary future capabilities without
needing to add a version.

> 
>>
>> Reviewed-by: Eric Blake <eblake@redhat.com>

Hence this still stands :)

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]

[Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation

[Luiz Capitulino]

The QMP dir is storing QMP docs and scripts. This series moves the scripts to
scripts/qmp/ and the docs to docs/qmp/. Also, the docs are updated.

v2

 - Set git diff.renames to true
 - Fix trailing whitespaces
 - Other minor fixes

Luiz Capitulino (6):
  QMP: add scripts/qmp
  QMP: fix qmp-commands.txt generation path
  QMP: QMP/ -> docs/qmp/
  QMP: Update README file
  QMP: Update qmp-spec.txt
  QMP: qmp-events.txt: alphabetical order fix and other minor changes

 Makefile                            |  6 +--
 QMP/README                          | 88 -------------------------------------
 docs/qmp/README                     | 87 ++++++++++++++++++++++++++++++++++++
 {QMP => docs/qmp}/qmp-events.txt    | 34 +++++++-------
 {QMP => docs/qmp}/qmp-spec.txt      | 65 ++++++++++++---------------
 {QMP => scripts/qmp}/qemu-ga-client |  0
 {QMP => scripts/qmp}/qmp            |  0
 {QMP => scripts/qmp}/qmp-shell      |  2 +-
 {QMP => scripts/qmp}/qmp.py         |  2 +-
 {QMP => scripts/qmp}/qom-fuse       |  0
 {QMP => scripts/qmp}/qom-get        |  0
 {QMP => scripts/qmp}/qom-list       |  0
 {QMP => scripts/qmp}/qom-set        |  0
 13 files changed, 137 insertions(+), 147 deletions(-)
 delete mode 100644 QMP/README
 create mode 100644 docs/qmp/README
 rename {QMP => docs/qmp}/qmp-events.txt (99%)
 rename {QMP => docs/qmp}/qmp-spec.txt (82%)
 rename {QMP => scripts/qmp}/qemu-ga-client (100%)
 rename {QMP => scripts/qmp}/qmp (100%)
 rename {QMP => scripts/qmp}/qmp-shell (99%)
 rename {QMP => scripts/qmp}/qmp.py (99%)
 rename {QMP => scripts/qmp}/qom-fuse (100%)
 rename {QMP => scripts/qmp}/qom-get (100%)
 rename {QMP => scripts/qmp}/qom-list (100%)
 rename {QMP => scripts/qmp}/qom-set (100%)

-- 
1.8.1.4

[Qemu-devel] [PATCH 1/6] QMP: add scripts/qmp

[Luiz Capitulino]

Populate it with all scripts stored in QMP/. Also fixes trailing
whitespaces in qmp-shell and qmp.py.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 {QMP => scripts/qmp}/qemu-ga-client | 0
 {QMP => scripts/qmp}/qmp            | 0
 {QMP => scripts/qmp}/qmp-shell      | 2 +-
 {QMP => scripts/qmp}/qmp.py         | 2 +-
 {QMP => scripts/qmp}/qom-fuse       | 0
 {QMP => scripts/qmp}/qom-get        | 0
 {QMP => scripts/qmp}/qom-list       | 0
 {QMP => scripts/qmp}/qom-set        | 0
 8 files changed, 2 insertions(+), 2 deletions(-)
 rename {QMP => scripts/qmp}/qemu-ga-client (100%)
 rename {QMP => scripts/qmp}/qmp (100%)
 rename {QMP => scripts/qmp}/qmp-shell (99%)
 rename {QMP => scripts/qmp}/qmp.py (99%)
 rename {QMP => scripts/qmp}/qom-fuse (100%)
 rename {QMP => scripts/qmp}/qom-get (100%)
 rename {QMP => scripts/qmp}/qom-list (100%)
 rename {QMP => scripts/qmp}/qom-set (100%)

diff --git a/QMP/qemu-ga-client b/scripts/qmp/qemu-ga-client
similarity index 100%
rename from QMP/qemu-ga-client
rename to scripts/qmp/qemu-ga-client
diff --git a/QMP/qmp b/scripts/qmp/qmp
similarity index 100%
rename from QMP/qmp
rename to scripts/qmp/qmp
diff --git a/QMP/qmp-shell b/scripts/qmp/qmp-shell
similarity index 99%
rename from QMP/qmp-shell
rename to scripts/qmp/qmp-shell
index 73cb3b6..d6b420f 100755
--- a/QMP/qmp-shell
+++ b/scripts/qmp/qmp-shell
@@ -91,7 +91,7 @@ class QMPShell(qmp.QEMUMonitorProtocol):
         """
         Build a QMP input object from a user provided command-line in the
         following format:
-    
+
             < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
         """
         cmdargs = cmdline.split()
diff --git a/QMP/qmp.py b/scripts/qmp/qmp.py
similarity index 99%
rename from QMP/qmp.py
rename to scripts/qmp/qmp.py
index c551df1..21804f4 100644
--- a/QMP/qmp.py
+++ b/scripts/qmp/qmp.py
@@ -1,5 +1,5 @@
 # QEMU Monitor Protocol Python class
-# 
+#
 # Copyright (C) 2009, 2010 Red Hat Inc.
 #
 # Authors:
diff --git a/QMP/qom-fuse b/scripts/qmp/qom-fuse
similarity index 100%
rename from QMP/qom-fuse
rename to scripts/qmp/qom-fuse
diff --git a/QMP/qom-get b/scripts/qmp/qom-get
similarity index 100%
rename from QMP/qom-get
rename to scripts/qmp/qom-get
diff --git a/QMP/qom-list b/scripts/qmp/qom-list
similarity index 100%
rename from QMP/qom-list
rename to scripts/qmp/qom-list
diff --git a/QMP/qom-set b/scripts/qmp/qom-set
similarity index 100%
rename from QMP/qom-set
rename to scripts/qmp/qom-set
-- 
1.8.1.4

[Qemu-devel] [PATCH 2/6] QMP: fix qmp-commands.txt generation path

[Luiz Capitulino]

This file should be generated in the BUILD_DIR, as all other docs.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 Makefile | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 362fe3e..aca548d 100644
--- a/Makefile
+++ b/Makefile
@@ -65,7 +65,7 @@ LIBS+=-lz $(LIBS_TOOLS)
 HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
 
 ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt
+DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
 ifdef CONFIG_VIRTFS
 DOCS+=fsdev/virtfs-proxy-helper.1
 endif
@@ -304,7 +304,7 @@ endif
 install-doc: $(DOCS)
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html  qemu-tech.html "$(DESTDIR)$(qemu_docdir)"
-	$(INSTALL_DATA) QMP/qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
+	$(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
 ifdef CONFIG_POSIX
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
@@ -398,7 +398,7 @@ qemu-options.texi: $(SRC_PATH)/qemu-options.hx
 qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
 
-QMP/qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
+qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@,"  GEN   $@")
 
 qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
-- 
1.8.1.4

[Qemu-devel] [PATCH 3/6] QMP: QMP/ -> docs/qmp/

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 {QMP => docs/qmp}/README         | 0
 {QMP => docs/qmp}/qmp-events.txt | 0
 {QMP => docs/qmp}/qmp-spec.txt   | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename {QMP => docs/qmp}/README (100%)
 rename {QMP => docs/qmp}/qmp-events.txt (100%)
 rename {QMP => docs/qmp}/qmp-spec.txt (100%)

diff --git a/QMP/README b/docs/qmp/README
similarity index 100%
rename from QMP/README
rename to docs/qmp/README
diff --git a/QMP/qmp-events.txt b/docs/qmp/qmp-events.txt
similarity index 100%
rename from QMP/qmp-events.txt
rename to docs/qmp/qmp-events.txt
diff --git a/QMP/qmp-spec.txt b/docs/qmp/qmp-spec.txt
similarity index 100%
rename from QMP/qmp-spec.txt
rename to docs/qmp/qmp-spec.txt
-- 
1.8.1.4

[Qemu-devel] [PATCH 4/6] QMP: Update README file

[Luiz Capitulino]

Drop unneeded info, fix some of the examples and rename QEMU Monitor
Protocol to QEMU Machine Protocol.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/README | 99 ++++++++++++++++++++++++++++-----------------------------
 1 file changed, 49 insertions(+), 50 deletions(-)

diff --git a/docs/qmp/README b/docs/qmp/README
index c95a08c..85c4bc1 100644
--- a/docs/qmp/README
+++ b/docs/qmp/README
@@ -1,13 +1,13 @@
-                          QEMU Monitor Protocol
+                          QEMU Machine Protocol
                           =====================
 
 Introduction
--------------
+------------
 
-The QEMU Monitor Protocol (QMP) allows applications to communicate with
-QEMU's Monitor.
+The QEMU Machine Protocol (QMP) allows applications to operate a
+QEMU instance.
 
-QMP is JSON[1] based and currently has the following features:
+QMP is JSON[1] based and features the following:
 
 - Lightweight, text-based, easy to parse data format
 - Asynchronous messages support (ie. events)
@@ -15,37 +15,28 @@ QMP is JSON[1] based and currently has the following features:
 
 For detailed information on QMP's usage, please, refer to the following files:
 
-o qmp-spec.txt      QEMU Monitor Protocol current specification
+o qmp-spec.txt      QEMU Machine Protocol current specification
 o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
 o qmp-events.txt    List of available asynchronous events
 
-There is also a simple Python script called 'qmp-shell' available.
-
-IMPORTANT: It's strongly recommended to read the 'Stability Considerations'
-section in the qmp-commands.txt file before making any serious use of QMP.
-
-
 [1] http://www.json.org
 
 Usage
 -----
 
-To enable QMP, you need a QEMU monitor instance in "control mode". There are
-two ways of doing this.
+You can use the -qmp option to enable QMP. For example, the following
+makes QMP available on localhost port 4444:
 
-The simplest one is using the '-qmp' command-line option. The following
-example makes QMP available on localhost port 4444:
+$ qemu [...] -qmp tcp:localhost:4444,server,nowait
 
-  $ qemu [...] -qmp tcp:localhost:4444,server
+However, for more flexibility and to make use of more options, the -mon
+command-line option should be used. For instance, the following example
+creates one HMP instance (human monitor) on stdio and one QMP instance
+on localhost port 4444:
 
-However, in order to have more complex combinations, like multiple monitors,
-the '-mon' command-line option should be used along with the '-chardev' one.
-For instance, the following example creates one user monitor on stdio and one
-QMP monitor on localhost port 4444.
-
-   $ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
-                -chardev socket,id=mon1,host=localhost,port=4444,server \
-                -mon chardev=mon1,mode=control
+$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
+             -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
+             -mon chardev=mon1,mode=control,pretty=on
 
 Please, refer to QEMU's manpage for more information.
 
@@ -58,31 +49,39 @@ $ telnet localhost 4444
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
-{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
-{ "execute": "qmp_capabilities" }
-{"return": {}}
-{ "execute": "query-version" }
-{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
-
-Development Process
--------------------
+{
+    "QMP": {
+        "version": {
+            "qemu": {
+                "micro": 50, 
+                "minor": 6, 
+                "major": 1
+            }, 
+            "package": ""
+        }, 
+        "capabilities": [
+        ]
+    }
+}
 
-When changing QMP's interface (by adding new commands, events or modifying
-existing ones) it's mandatory to update the relevant documentation, which is
-one (or more) of the files listed in the 'Introduction' section*.
-
-Also, it's strongly recommended to send the documentation patch first, before
-doing any code change. This is so because:
-
-  1. Avoids the code dictating the interface
-
-  2. Review can improve your interface.  Letting that happen before
-     you implement it can save you work.
-
-* The qmp-commands.txt file is generated from the qmp-commands.hx one, which
-  is the file that should be edited.
-
-Homepage
---------
+{ "execute": "qmp_capabilities" }
+{
+    "return": {
+    }
+}
+
+{ "execute": "query-status" }
+{
+    "return": {
+        "status": "prelaunch", 
+        "singlestep": false, 
+        "running": false
+    }
+}
+
+Please, refer to the qapi-schema.json file for a complete command reference.
+
+QMP wiki page
+-------------
 
 http://wiki.qemu.org/QMP
-- 
1.8.1.4

[Qemu-devel] [PATCH 5/6] QMP: Update qmp-spec.txt

[Luiz Capitulino]

Simplify the text, fix some of the examples.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-spec.txt | 65 ++++++++++++++++++++++-----------------------------
 1 file changed, 28 insertions(+), 37 deletions(-)

diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
index a277896..22568c6 100644
--- a/docs/qmp/qmp-spec.txt
+++ b/docs/qmp/qmp-spec.txt
@@ -1,21 +1,17 @@
-           QEMU Monitor Protocol Specification - Version 0.1
+                      QEMU Machine Protocol Specification
 
 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 document specifies the QEMU Machine Protocol (QMP), a JSON-based protocol
+which is available for applications to operate QEMU at the machine-level.
 
 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.
+"Client" is any application which is using QMP to communicate with QEMU and
+"Server" is QEMU itself.
 
 JSON data structures, when mentioned in this document, are always in the
 following format:
@@ -47,14 +43,14 @@ that the connection has been successfully established and that the Server is
 ready for capabilities negotiation (for more information refer to section
 '4. Capabilities Negotiation').
 
-The format is:
+The greeting message format is:
 
 { "QMP": { "version": json-object, "capabilities": json-array } }
 
  Where,
 
 - The "version" member contains the Server's version information (the format
-  is the same of the 'query-version' command)
+  is the same of the query-version command)
 - The "capabilities" member specify the availability of features beyond the
   baseline specification
 
@@ -83,10 +79,7 @@ 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:
+The format of a success response is:
 
 { "return": json-object, "id": json-value }
 
@@ -96,15 +89,12 @@ The format is:
   in a per-command basis or an empty json-object if the command does not
   return data
 - The "id" member contains the transaction identification associated
-  with the command execution (if issued by the Client)
+  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:
+The format of an error response is:
 
 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
 
@@ -114,7 +104,7 @@ The format is:
 - The "desc" member is a human-readable error message. Clients should
   not attempt to parse this message.
 - The "id" member contains the transaction identification associated with
-  the command execution (if issued by the Client)
+  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
@@ -124,9 +114,9 @@ if provided by the client.
 -----------------------
 
 As a result of state changes, the Server may send messages unilaterally
-to the Client at any time. They are called 'asynchronous events'.
+to the Client at any time. They are called "asynchronous events".
 
-The format is:
+The format of asynchronous events is:
 
 { "event": json-string, "data": json-object,
   "timestamp": { "seconds": json-number, "microseconds": json-number } }
@@ -147,36 +137,37 @@ qmp-events.txt file.
 ===============
 
 This section provides some examples of real QMP usage, in all of them
-'C' stands for 'Client' and 'S' stands for 'Server'.
+"C" stands for "Client" and "S" stands for "Server".
 
 3.1 Server greeting
 -------------------
 
-S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
+S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
+     "package": ""}, "capabilities": []}}
 
 3.2 Simple 'stop' execution
 ---------------------------
 
 C: { "execute": "stop" }
-S: {"return": {}}
+S: { "return": {} }
 
 3.3 KVM information
 -------------------
 
 C: { "execute": "query-kvm", "id": "example" }
-S: {"return": {"enabled": true, "present": true}, "id": "example"}
+S: { "return": { "enabled": true, "present": true }, "id": "example"}
 
 3.4 Parsing error
 ------------------
 
 C: { "execute": }
-S: {"error": {"class": "GenericError", "desc": "Invalid JSON syntax" } }
+S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
 
 3.5 Powerdown event
 -------------------
 
-S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
-"POWERDOWN"}
+S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
+    "event": "POWERDOWN" }
 
 4. Capabilities Negotiation
 ----------------------------
@@ -184,17 +175,17 @@ S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 When a Client successfully establishes a connection, the Server is in
 Capabilities Negotiation mode.
 
-In this mode only the 'qmp_capabilities' command is allowed to run, all
-other commands will return the CommandNotFound error. Asynchronous messages
-are not delivered either.
+In this mode only the qmp_capabilities command is allowed to run, all
+other commands will return the CommandNotFound error. Asynchronous
+messages are not delivered either.
 
-Clients should use the 'qmp_capabilities' command to enable capabilities
+Clients should use the qmp_capabilities command to enable capabilities
 advertised in the Server's greeting (section '2.2 Server Greeting') they
 support.
 
-When the 'qmp_capabilities' command is issued, and if it does not return an
+When the qmp_capabilities command is issued, and if it does not return an
 error, the Server enters in Command mode where capabilities changes take
-effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
+effect, all commands (except qmp_capabilities) are allowed and asynchronous
 messages are delivered.
 
 5 Compatibility Considerations
@@ -245,7 +236,7 @@ arguments, errors, asynchronous events, and so forth.
 
 Any new names downstream wishes to add must begin with '__'.  To
 ensure compatibility with other downstreams, it is strongly
-recommended that you prefix your downstram names with '__RFQDN_' where
+recommended that you prefix your downstream names with '__RFQDN_' where
 RFQDN is a valid, reverse fully qualified domain name which you
 control.  For example, a qemu-kvm specific monitor command would be:
 
-- 
1.8.1.4

[Qemu-devel] [PATCH 6/6] QMP: qmp-events.txt: alphabetical order fix and other minor changes

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/qmp/qmp-events.txt | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
index 4b24ec9..6b87e97 100644
--- a/docs/qmp/qmp-events.txt
+++ b/docs/qmp/qmp-events.txt
@@ -1,4 +1,4 @@
-                   QEMU Monitor Protocol Events
+                   QEMU Machine Protocol Events
                    ============================
 
 BALLOON_CHANGE
@@ -159,7 +159,7 @@ Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
 event.
 
 DEVICE_DELETED
------------------
+--------------
 
 Emitted whenever the device removal completion is acknowledged
 by the guest.
@@ -194,8 +194,22 @@ Data:
   },
   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 
+GUEST_PANICKED
+--------------
+
+Emitted when guest OS panic is detected.
+
+Data:
+
+- "action": Action that has been taken (json-string, currently always "pause").
+
+Example:
+
+{ "event": "GUEST_PANICKED",
+     "data": { "action": "pause" } }
+
 NIC_RX_FILTER_CHANGED
------------------
+---------------------
 
 The event is emitted once until the query command is executed,
 the first event will always be emitted.
@@ -486,17 +500,3 @@ Example:
 
 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
 followed respectively by the RESET, SHUTDOWN, or STOP events.
-
-GUEST_PANICKED
---------------
-
-Emitted when guest OS panic is detected.
-
-Data:
-
-- "action": Action that has been taken (json-string, currently always "pause").
-
-Example:
-
-{ "event": "GUEST_PANICKED",
-     "data": { "action": "pause" } }
-- 
1.8.1.4

Re: [Qemu-devel] [PATCH v2 0/6] QMP: re-organize documentation

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 731 bytes --]

On 09/13/2013 12:11 PM, Luiz Capitulino wrote:
> The QMP dir is storing QMP docs and scripts. This series moves the scripts to
> scripts/qmp/ and the docs to docs/qmp/. Also, the docs are updated.
> 
> v2
> 
>  - Set git diff.renames to true
>  - Fix trailing whitespaces
>  - Other minor fixes
> 
> Luiz Capitulino (6):
>   QMP: add scripts/qmp
>   QMP: fix qmp-commands.txt generation path
>   QMP: QMP/ -> docs/qmp/
>   QMP: Update README file
>   QMP: Update qmp-spec.txt
>   QMP: qmp-events.txt: alphabetical order fix and other minor changes

Series: Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 621 bytes --]