[Qemu-devel] [PATCH v2 0/4]: QMP capability negotiation support

[Qemu-devel] [PATCH v2 0/4]: QMP capability negotiation support

[Luiz Capitulino]

 Capability negotiation allows clients to enable new QMP capabilities they
support and thus allows QMP to evolve in a compatible way.

 This series implements Markus's design and is a revamp of the previous
one. It's very simple now, as mode-oriented support has been dropped. I've
maintained the same terminology, though.

 Basically, QMP starts in capability negotiation mode where only the
'qmp_capabilities' command is allowed to run. This command should be used
by clients to enable capabilities they support. When this command is issued
QMP enters in command mode, where the party begins.

 Details in the patches.

changelog
---------

v1 -> v2

- Typos and minor changes

v0 -> v1

- Drop mode-oriented support

[Qemu-devel] [PATCH 1/4] QMP: Add QEMU's version to the greeting message

[Luiz Capitulino]

With capability negotiation support clients will only have a chance
to check QEMU's version (ie. issue 'query-version') after the
negotiation procedure is done.

It might be useful to clients to check QEMU's version before
negotiating features, though.

To allow that, this commit adds the QEMU's version object to the
greeting message.

Not really sure this is needed, but doesn't hurt anyway.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 QMP/README       |    6 ++++--
 QMP/qmp-spec.txt |    6 ++++--
 monitor.c        |   10 +++++++++-
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/QMP/README b/QMP/README
index 09e7053..9334c25 100644
--- a/QMP/README
+++ b/QMP/README
@@ -52,9 +52,11 @@ $ telnet localhost 4444
 Trying 127.0.0.1...
 Connected to localhost.
 Escape character is '^]'.
-{"QMP": {"capabilities": []}}
+{"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
+{ "execute": "qmp_capabilities" }
+{"return": {}}
 { "execute": "query-version" }
-{"return": {"qemu": "0.11.50", "package": ""}}
+{"return": {"qemu": "0.12.50", "package": ""}}
 
 Contact
 -------
diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index 56f388c..b2617bb 100644
--- a/QMP/qmp-spec.txt
+++ b/QMP/qmp-spec.txt
@@ -48,10 +48,12 @@ waiting for commands.
 
 The format is:
 
-{ "QMP": { "capabilities": json-array } }
+{ "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)
 - The "capabilities" member specify the availability of features beyond the
   baseline specification
 
@@ -152,7 +154,7 @@ This section provides some examples of real QMP usage, in all of them
 3.1 Server greeting
 -------------------
 
-S: {"QMP": {"capabilities": []}}
+S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
 
 3.2 Simple 'stop' execution
 ---------------------------
diff --git a/monitor.c b/monitor.c
index ff22123..ec1d11e 100644
--- a/monitor.c
+++ b/monitor.c
@@ -4365,6 +4365,14 @@ void monitor_resume(Monitor *mon)
         readline_show_prompt(mon->rs);
 }
 
+static QObject *get_qmp_greeting(void)
+{
+    QObject *ver;
+
+    do_info_version(NULL, &ver);
+    return qobject_from_jsonf("{'QMP':{'version': %p,'capabilities': []}}",ver);
+}
+
 /**
  * monitor_control_event(): Print QMP gretting
  */
@@ -4376,7 +4384,7 @@ static void monitor_control_event(void *opaque, int event)
 
         json_message_parser_init(&mon->mc->parser, handle_qmp_command);
 
-        data = qobject_from_jsonf("{ 'QMP': { 'capabilities': [] } }");
+        data = get_qmp_greeting();
         assert(data != NULL);
 
         monitor_json_emitter(mon, data);
-- 
1.6.6

Re: [Qemu-devel] [PATCH 1/4] QMP: Add QEMU's version to the greeting message

[Anthony Liguori]

On 02/04/2010 02:10 PM, Luiz Capitulino wrote:
> With capability negotiation support clients will only have a chance
> to check QEMU's version (ie. issue 'query-version') after the
> negotiation procedure is done.
>
> It might be useful to clients to check QEMU's version before
> negotiating features, though.
>
> To allow that, this commit adds the QEMU's version object to the
> greeting message.
>
> Not really sure this is needed, but doesn't hurt anyway.
>
> Signed-off-by: Luiz Capitulino<lcapitulino@redhat.com>
>    

Applied all.  Thanks.

Regards,

Anthony Liguori
> ---
>   QMP/README       |    6 ++++--
>   QMP/qmp-spec.txt |    6 ++++--
>   monitor.c        |   10 +++++++++-
>   3 files changed, 17 insertions(+), 5 deletions(-)
>
> diff --git a/QMP/README b/QMP/README
> index 09e7053..9334c25 100644
> --- a/QMP/README
> +++ b/QMP/README
> @@ -52,9 +52,11 @@ $ telnet localhost 4444
>   Trying 127.0.0.1...
>   Connected to localhost.
>   Escape character is '^]'.
> -{"QMP": {"capabilities": []}}
> +{"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
> +{ "execute": "qmp_capabilities" }
> +{"return": {}}
>   { "execute": "query-version" }
> -{"return": {"qemu": "0.11.50", "package": ""}}
> +{"return": {"qemu": "0.12.50", "package": ""}}
>
>   Contact
>   -------
> diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
> index 56f388c..b2617bb 100644
> --- a/QMP/qmp-spec.txt
> +++ b/QMP/qmp-spec.txt
> @@ -48,10 +48,12 @@ waiting for commands.
>
>   The format is:
>
> -{ "QMP": { "capabilities": json-array } }
> +{ "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)
>   - The "capabilities" member specify the availability of features beyond the
>     baseline specification
>
> @@ -152,7 +154,7 @@ This section provides some examples of real QMP usage, in all of them
>   3.1 Server greeting
>   -------------------
>
> -S: {"QMP": {"capabilities": []}}
> +S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
>
>   3.2 Simple 'stop' execution
>   ---------------------------
> diff --git a/monitor.c b/monitor.c
> index ff22123..ec1d11e 100644
> --- a/monitor.c
> +++ b/monitor.c
> @@ -4365,6 +4365,14 @@ void monitor_resume(Monitor *mon)
>           readline_show_prompt(mon->rs);
>   }
>
> +static QObject *get_qmp_greeting(void)
> +{
> +    QObject *ver;
> +
> +    do_info_version(NULL,&ver);
> +    return qobject_from_jsonf("{'QMP':{'version': %p,'capabilities': []}}",ver);
> +}
> +
>   /**
>    * monitor_control_event(): Print QMP gretting
>    */
> @@ -4376,7 +4384,7 @@ static void monitor_control_event(void *opaque, int event)
>
>           json_message_parser_init(&mon->mc->parser, handle_qmp_command);
>
> -        data = qobject_from_jsonf("{ 'QMP': { 'capabilities': [] } }");
> +        data = get_qmp_greeting();
>           assert(data != NULL);
>
>           monitor_json_emitter(mon, data);
>    

[Qemu-devel] [PATCH 2/4] QMP: Introduce the qmp_capabilities command

[Luiz Capitulino]

This command will be used to enable QMP capabilities advertised
by the capabilities array.

Note that it will be mandatory to issue this command in order
to make QMP functional (although this behavior is not being
enforced by this commit).

Also, as we don't have any capabilities yet, the new command
doesn't accept any arguments. I will postpone the decision for
a format for this until we get our first capability.

Finally, this command is visible from the user Monitor too, in
the meaning that you can execute it but it won't do anything.
Making it only visible in QMP is beyond this series' goal, as
it requires changes in unrelated places.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 monitor.c       |   11 +++++++++++
 qemu-monitor.hx |   14 ++++++++++++++
 2 files changed, 25 insertions(+), 0 deletions(-)

diff --git a/monitor.c b/monitor.c
index ec1d11e..94fc685 100644
--- a/monitor.c
+++ b/monitor.c
@@ -122,6 +122,7 @@ typedef struct MonitorControl {
     QObject *id;
     int print_enabled;
     JSONMessageParser parser;
+    int command_mode;
 } MonitorControl;
 
 struct Monitor {
@@ -409,6 +410,15 @@ void monitor_protocol_event(MonitorEvent event, QObject *data)
     QDECREF(qmp);
 }
 
+static void do_qmp_capabilities(Monitor *mon, const QDict *params,
+                                QObject **ret_data)
+{
+    /* Will setup QMP capabilities in the future */
+    if (monitor_ctrl_mode(mon)) {
+        mon->mc->command_mode = 1;
+    }
+}
+
 static int compare_cmd(const char *name, const char *list)
 {
     const char *p, *pstart;
@@ -4382,6 +4392,7 @@ static void monitor_control_event(void *opaque, int event)
         QObject *data;
         Monitor *mon = opaque;
 
+        mon->mc->command_mode = 0;
         json_message_parser_init(&mon->mc->parser, handle_qmp_command);
 
         data = get_qmp_greeting();
diff --git a/qemu-monitor.hx b/qemu-monitor.hx
index e5bff8e..8edbf23 100644
--- a/qemu-monitor.hx
+++ b/qemu-monitor.hx
@@ -1066,6 +1066,20 @@ STEXI
 Set the encrypted device @var{device} password to @var{password}
 ETEXI
 
+    {
+        .name       = "qmp_capabilities",
+        .args_type  = "",
+        .params     = "",
+        .help       = "enable QMP capabilities",
+        .user_print = monitor_user_noop,
+        .mhandler.cmd_new = do_qmp_capabilities,
+    },
+
+STEXI
+@item qmp_capabilities
+Enable the specified QMP capabilities
+ETEXI
+
 STEXI
 @end table
 ETEXI
-- 
1.6.6

[Qemu-devel] [PATCH 3/4] QMP: Enforce capability negotiation rules

[Luiz Capitulino]

With this commit QMP will be started in Capabilities Negotiation
mode, where the only command allowed to run is 'qmp_capabilities'.

All other commands will return CommandNotFound error. Asynchronous
messages are not delivered either.

When 'qmp_capabilities' is successfully executed QMP enters in
Command mode, where all commands (except 'qmp_capabilities') are
allowed to run and asynchronous messages are delivered.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 monitor.c |   18 +++++++++++++++++-
 1 files changed, 17 insertions(+), 1 deletions(-)

diff --git a/monitor.c b/monitor.c
index 94fc685..a0ec7fc 100644
--- a/monitor.c
+++ b/monitor.c
@@ -153,6 +153,11 @@ Monitor *cur_mon = NULL;
 static void monitor_command_cb(Monitor *mon, const char *cmdline,
                                void *opaque);
 
+static inline int qmp_cmd_mode(const Monitor *mon)
+{
+    return (mon->mc ? mon->mc->command_mode : 0);
+}
+
 /* Return true if in control mode, false otherwise */
 static inline int monitor_ctrl_mode(const Monitor *mon)
 {
@@ -403,7 +408,7 @@ void monitor_protocol_event(MonitorEvent event, QObject *data)
     }
 
     QLIST_FOREACH(mon, &mon_list, entry) {
-        if (monitor_ctrl_mode(mon)) {
+        if (monitor_ctrl_mode(mon) && qmp_cmd_mode(mon)) {
             monitor_json_emitter(mon, QOBJECT(qmp));
         }
     }
@@ -4229,6 +4234,12 @@ static int monitor_check_qmp_args(const mon_cmd_t *cmd, QDict *args)
     return err;
 }
 
+static int invalid_qmp_mode(const Monitor *mon, const char *cmd_name)
+{
+    int is_cap = compare_cmd(cmd_name, "qmp_capabilities");
+    return (qmp_cmd_mode(mon) ? is_cap : !is_cap);
+}
+
 static void handle_qmp_command(JSONMessageParser *parser, QList *tokens)
 {
     int err;
@@ -4268,6 +4279,11 @@ static void handle_qmp_command(JSONMessageParser *parser, QList *tokens)
 
     cmd_name = qstring_get_str(qobject_to_qstring(obj));
 
+    if (invalid_qmp_mode(mon, cmd_name)) {
+        qemu_error_new(QERR_COMMAND_NOT_FOUND, cmd_name);
+        goto err_input;
+    }
+
     /*
      * XXX: We need this special case until we get info handlers
      * converted into 'query-' commands
-- 
1.6.6

[Qemu-devel] [PATCH 4/4] QMP: spec: Capability negotiation updates

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 QMP/qmp-spec.txt |   46 +++++++++++++++++++++++++++++-----------------
 1 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index b2617bb..f3c0327 100644
--- a/QMP/qmp-spec.txt
+++ b/QMP/qmp-spec.txt
@@ -44,7 +44,8 @@ they can be in ANY order, thus no particular order should be assumed.
 
 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.
+ready for capabilities negotiation (for more information refer to section
+'4. Capabilities Negotiation').
 
 The format is:
 
@@ -181,25 +182,36 @@ S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 "POWERDOWN"}
 
-4. Compatibility Considerations
---------------------------------
+4. Capabilities Negotiation
+----------------------------
 
-In order to achieve maximum compatibility between versions, Clients must not 
-assume any particular:
+When a Client successfully establishes a connection, the Server is in
+Capabilities Negotiation mode.
 
-- Size of json-objects or length of json-arrays
-- Order of json-object members or json-array elements
-- Amount of errors generated by a command, that is, new errors can be added
-  to any existing command in newer versions of the Server
+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
+advertised in the Server's greeting (section '2.2 Server Greeting') they
+support.
 
-Additionally, Clients should always:
+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
+messages are delivered.
 
-- Check the capabilities json-array at connection time
-- Check the availability of commands with 'query-commands' before issuing them
+5 Compatibility Considerations
+------------------------------
 
-5. Recommendations to Client implementors
------------------------------------------
+All protocol changes or new features which modify the protocol format in an
+incompatible way are disabled by default and will be advertised by the
+capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
+that array and enable the capabilities they support.
 
-5.1 The Server should be always started in pause mode, thus the Client is
-    able to perform any setup procedure without the risk of race conditions
-    and related problems
+Additionally, Clients must not assume any particular:
+
+- Size of json-objects or length of json-arrays
+- Order of json-object members or json-array elements
+- Amount of errors generated by a command, that is, new errors can be added
+  to any existing command in newer versions of the Server
-- 
1.6.6

Re: [Qemu-devel] [PATCH v2 0/4]: QMP capability negotiation support

[Markus Armbruster]

Luiz Capitulino <lcapitulino@redhat.com> writes:

>  Capability negotiation allows clients to enable new QMP capabilities they
> support and thus allows QMP to evolve in a compatible way.
>
>  This series implements Markus's design and is a revamp of the previous
> one. It's very simple now, as mode-oriented support has been dropped. I've
> maintained the same terminology, though.
>
>  Basically, QMP starts in capability negotiation mode where only the
> 'qmp_capabilities' command is allowed to run. This command should be used
> by clients to enable capabilities they support. When this command is issued
> QMP enters in command mode, where the party begins.
>
>  Details in the patches.
>
> changelog
> ---------
>
> v1 -> v2
>
> - Typos and minor changes
>
> v0 -> v1
>
> - Drop mode-oriented support

Looks good, thanks!

[Qemu-devel] [PATCH v1 0/4]: QMP capability negotiation support

[Luiz Capitulino]

 Capability negotiation allows clients to enable new QMP capabilities they
support and thus allows QMP to evolve in a compatible way.

 This series implements Markus's design and is a revamp of the previous
one. It's very simple now, as mode-oriented support has been dropped. I've
maintained the same terminology, though.

 Basically, QMP starts in capability negotiation mode where only the
'qmp_capabilities' command is allowed to run. This command should be used
by clients to enable capabilities they support. When this command is issued
QMP enters in command mode, where the party begins.

 Details in the patches.

changelog
---------

v0 -> v1

- Drop mode-oriented support

[Qemu-devel] [PATCH 4/4] QMP: spec: Capability negotiation updates

[Luiz Capitulino]

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 QMP/qmp-spec.txt |   46 +++++++++++++++++++++++++++++-----------------
 1 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/QMP/qmp-spec.txt b/QMP/qmp-spec.txt
index b2617bb..f3c0327 100644
--- a/QMP/qmp-spec.txt
+++ b/QMP/qmp-spec.txt
@@ -44,7 +44,8 @@ they can be in ANY order, thus no particular order should be assumed.
 
 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.
+ready for capabilities negotiation (for more information refer to section
+'4. Capabilities Negotiation').
 
 The format is:
 
@@ -181,25 +182,36 @@ S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 "POWERDOWN"}
 
-4. Compatibility Considerations
---------------------------------
+4. Capabilities Negotiation
+----------------------------
 
-In order to achieve maximum compatibility between versions, Clients must not 
-assume any particular:
+When a Client successfully establishes a connection, the Server is in
+Capabilities Negotiation mode.
 
-- Size of json-objects or length of json-arrays
-- Order of json-object members or json-array elements
-- Amount of errors generated by a command, that is, new errors can be added
-  to any existing command in newer versions of the Server
+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
+advertised in the Server's greeting (section '2.2 Server Greeting') they
+support.
 
-Additionally, Clients should always:
+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
+messages are delivered.
 
-- Check the capabilities json-array at connection time
-- Check the availability of commands with 'query-commands' before issuing them
+5 Compatibility Considerations
+------------------------------
 
-5. Recommendations to Client implementors
------------------------------------------
+All protocol changes or new features which modify the protocol format in an
+incompatible way are disabled by default and will be advertised by the
+capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
+that array and enable the capabilities they support.
 
-5.1 The Server should be always started in pause mode, thus the Client is
-    able to perform any setup procedure without the risk of race conditions
-    and related problems
+Additionally, Clients must not assume any particular:
+
+- Size of json-objects or length of json-arrays
+- Order of json-object members or json-array elements
+- Amount of errors generated by a command, that is, new errors can be added
+  to any existing command in newer versions of the Server
-- 
1.6.6