[Qemu-devel] [master/0.13 v2 0/4]: QMP: Stability related fixes

[Qemu-devel] [master/0.13 v2 0/4]: QMP: Stability related fixes

[Luiz Capitulino]

In the KVM Forum we talked about making the current QMP's interface stable
and deprecating it as soon as the right one is available.

This series updates some QMP docs to reflect that and also has a small fix
for the greeting message which would harder to change later.

changelog
---------

v1 -> v2: Improve wording in README file

Thanks.

[Qemu-devel] [PATCH 1/4] QMP: update 'query-version' documentation

[Luiz Capitulino]

From: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>

Update the documentation of 'query-version' to output the string version broken
down.

Signed-off-by: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 qemu-monitor.hx |   16 ++++++++++++++--
 1 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/qemu-monitor.hx b/qemu-monitor.hx
index 2af3de6..9c27b31 100644
--- a/qemu-monitor.hx
+++ b/qemu-monitor.hx
@@ -1623,13 +1623,25 @@ Show QEMU version.
 
 Return a json-object with the following information:
 
-- "qemu": QEMU's version (json-string)
+- "qemu": A json-object containing three integer values:
+    - "major": QEMU's major version (json-int)
+    - "minor": QEMU's minor version (json-int)
+    - "micro": QEMU's micro version (json-int)
 - "package": package's version (json-string)
 
 Example:
 
 -> { "execute": "query-version" }
-<- { "return": { "qemu": "0.11.50", "package": "" } }
+<- {
+      "return":{
+         "qemu":{
+            "major":0,
+            "minor":11,
+            "micro":5
+         },
+         "package":""
+      }
+   }
 
 EQMP
 
-- 
1.7.2.1.97.g3235b

[Qemu-devel] [PATCH 2/4] QMP/monitor: update do_info_version() to output broken down version string

[Luiz Capitulino]

From: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>

This code was originally developed by Daniel P. Berrange <berrange@redhat.com>

Signed-off-by: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 monitor.c |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/monitor.c b/monitor.c
index c313d5a..e27f8d8 100644
--- a/monitor.c
+++ b/monitor.c
@@ -669,17 +669,32 @@ help:
 static void do_info_version_print(Monitor *mon, const QObject *data)
 {
     QDict *qdict;
+    QDict *qemu;
 
     qdict = qobject_to_qdict(data);
+    qemu = qdict_get_qdict(qdict, "qemu");
 
-    monitor_printf(mon, "%s%s\n", qdict_get_str(qdict, "qemu"),
-                                  qdict_get_str(qdict, "package"));
+    monitor_printf(mon, "%" PRId64 ".%" PRId64 ".%" PRId64 "%s\n",
+                  qdict_get_int(qemu, "major"),
+                  qdict_get_int(qemu, "minor"),
+                  qdict_get_int(qemu, "micro"),
+                  qdict_get_str(qdict, "package"));
 }
 
 static void do_info_version(Monitor *mon, QObject **ret_data)
 {
-    *ret_data = qobject_from_jsonf("{ 'qemu': %s, 'package': %s }",
-                                   QEMU_VERSION, QEMU_PKGVERSION);
+    const char *version = QEMU_VERSION;
+    int major = 0, minor = 0, micro = 0;
+    char *tmp;
+
+    major = strtol(version, &tmp, 10);
+    tmp++;
+    minor = strtol(tmp, &tmp, 10);
+    tmp++;
+    micro = strtol(tmp, &tmp, 10);
+
+    *ret_data = qobject_from_jsonf("{ 'qemu': { 'major': %d, 'minor': %d, \
+        'micro': %d }, 'package': %s }", major, minor, micro, QEMU_PKGVERSION);
 }
 
 static void do_info_name_print(Monitor *mon, const QObject *data)
-- 
1.7.2.1.97.g3235b

[Qemu-devel] [PATCH 3/4] QMP doc: Add 'Stability Considerations' section

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 qemu-monitor.hx |   26 ++++++++++++++++++++++++--
 1 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/qemu-monitor.hx b/qemu-monitor.hx
index 9c27b31..5c1da33 100644
--- a/qemu-monitor.hx
+++ b/qemu-monitor.hx
@@ -35,7 +35,29 @@ information on the Server command and response formats.
 
 NOTE: This document is temporary and will be replaced soon.
 
-1. Regular Commands
+1. Stability Considerations
+===========================
+
+The current QMP command set (described in this file) may be useful for a
+number of use cases, however it's limited and several commands have bad
+defined semantics, specially with regard to command completion.
+
+These problems are going to be solved incrementally in the next QEMU releases
+and we're going to establish a deprecation policy for badly defined commands.
+
+If you're planning to adopt QMP, please observe the following:
+
+    1. The deprecation policy will take efect and be documented soon, please
+       check the documentation of each used command as soon as a new release of
+       QEMU is available
+
+    2. DO NOT rely on anything which is not explicit documented
+
+    3. Errors, in special, are not documented. Applications should NOT check
+       for specific errors classes or data (it's strongly recommended to only
+       check for the "error" key)
+
+2. Regular Commands
 ===================
 
 Server's responses in the examples below are always a success response, please
@@ -1592,7 +1614,7 @@ HXCOMM This is required for the QMP documentation layout.
 
 SQMP
 
-2. Query Commands
+3. Query Commands
 =================
 
 EQMP
-- 
1.7.2.1.97.g3235b

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

[Luiz Capitulino]

A number of changes I prefer to do in one shot:

- Fix example
- Small clarifications
- Add multiple monitors example
- Add 'Development Process' section

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 QMP/README |   71 ++++++++++++++++++++++++++++++++++++++++-------------------
 1 files changed, 48 insertions(+), 23 deletions(-)

diff --git a/QMP/README b/QMP/README
index 35a80c7..948d445 100644
--- a/QMP/README
+++ b/QMP/README
@@ -7,60 +7,85 @@ Introduction
 The QEMU Monitor Protocol (QMP) allows applications to communicate with
 QEMU's Monitor.
 
-QMP is JSON[1] based and has the following features:
+QMP is JSON[1] based and currently has the following features:
 
 - Lightweight, text-based, easy to parse data format
-- Asynchronous events support 
-- Stability
+- Asynchronous messages support (ie. events)
+- Capabilities Negotiation
 
-For more information, please, refer to the following files:
+For detailed information on QMP's usage, please, refer to the following files:
 
 o qmp-spec.txt      QEMU Monitor Protocol current specification
-o qmp-commands.txt  QMP supported commands
+o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
 o qmp-events.txt    List of available asynchronous events
 
 There are also two simple Python scripts available:
 
-o qmp-shell       A shell
-o vm-info         Show some information about the Virtual Machine
+o qmp-shell  A shell
+o vm-info    Show some information about the Virtual Machine
+
+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, QEMU has to be started in "control mode". There are
-two ways of doing this, the simplest one is using the the '-qmp'
-command-line option.
+To enable QMP, you need a QEMU monitor instance in "control mode". There are
+two ways of doing this.
+
+The simplest one is using the '-qmp' command-line option. The following
+example makes QMP available on localhost port 4444:
 
-For example:
+  $ qemu [...] -qmp tcp:localhost:4444,server
 
-$ qemu [...] -qmp tcp:localhost:4444,server
+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.
 
-Will start QEMU in control mode, waiting for a client TCP connection
-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
 
-It is also possible to use the '-mon' command-line option to have
-more complex combinations. Please, refer to the QEMU's manpage for
-more information.
+Please, refer to QEMU's manpage for more information.
 
 Simple Testing
 --------------
 
-To manually test QMP one can connect with telnet and issue commands:
+To manually test QMP one can connect with telnet and issue commands by hand:
 
 $ telnet localhost 4444
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
-{"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
+{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}
 { "execute": "qmp_capabilities" }
 {"return": {}}
 { "execute": "query-version" }
-{"return": {"qemu": "0.12.50", "package": ""}}
+{"return": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}}
+
+Development Process
+-------------------
+
+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 qemu-monitor.hx one, which
+  is the file that should be edited.
 
-Contact
--------
+Homepage
+--------
 
 http://www.linux-kvm.org/page/MonitorProtocol
-Luiz Fernando N. Capitulino <lcapitulino@redhat.com>
-- 
1.7.2.1.97.g3235b

[Qemu-devel] [master/0.13 0/4]: QMP: Stability related fixes

[Luiz Capitulino]

In the KVM Forum we talked about making the current QMP's interface stable
and deprecating it as soon as the right one is available.

This series updates some QMP docs to reflect that and also has a small fix
for the greeting message which would harder to change later.

Thanks.

[Qemu-devel] [PATCH 1/4] QMP: update 'query-version' documentation

[Luiz Capitulino]

From: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>

Update the documentation of 'query-version' to output the string version broken
down.

Signed-off-by: Miguel Di Ciurcio Filho <miguel.filho@gmail.com>
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 qemu-monitor.hx |   16 ++++++++++++++--
 1 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/qemu-monitor.hx b/qemu-monitor.hx
index 2af3de6..9c27b31 100644
--- a/qemu-monitor.hx
+++ b/qemu-monitor.hx
@@ -1623,13 +1623,25 @@ Show QEMU version.
 
 Return a json-object with the following information:
 
-- "qemu": QEMU's version (json-string)
+- "qemu": A json-object containing three integer values:
+    - "major": QEMU's major version (json-int)
+    - "minor": QEMU's minor version (json-int)
+    - "micro": QEMU's micro version (json-int)
 - "package": package's version (json-string)
 
 Example:
 
 -> { "execute": "query-version" }
-<- { "return": { "qemu": "0.11.50", "package": "" } }
+<- {
+      "return":{
+         "qemu":{
+            "major":0,
+            "minor":11,
+            "micro":5
+         },
+         "package":""
+      }
+   }
 
 EQMP
 
-- 
1.7.2.1.97.g3235b