From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43)
	id 1NY4Hu-0000ID-MP
	for qemu-devel@nongnu.org; Thu, 21 Jan 2010 16:09:58 -0500
Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43)
	id 1NY4Hp-0000BT-Fj
	for qemu-devel@nongnu.org; Thu, 21 Jan 2010 16:09:57 -0500
Received: from [199.232.76.173] (port=53519 helo=monty-python.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1NY4Hp-0000BC-9x
	for qemu-devel@nongnu.org; Thu, 21 Jan 2010 16:09:53 -0500
Received: from mx1.redhat.com ([209.132.183.28]:48642)
	by monty-python.gnu.org with esmtp (Exim 4.60)
	(envelope-from <lcapitulino@redhat.com>) id 1NY4Ho-0002wU-Sp
	for qemu-devel@nongnu.org; Thu, 21 Jan 2010 16:09:53 -0500
From: Luiz Capitulino <lcapitulino@redhat.com>
Date: Thu, 21 Jan 2010 19:09:29 -0200
Message-Id: <1264108180-3666-1-git-send-email-lcapitulino@redhat.com>
Subject: [Qemu-devel] [RFC 00/11]: QMP feature negotiation support
List-Id: qemu-devel.nongnu.org
List-Unsubscribe: <http://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/pipermail/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <http://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: qemu-devel@nongnu.org, armbru@redhat.com, aliguori@us.ibm.com, avi@redhat.com

 Feature negotiation allows clients to enable QMP capabilities they are
interested in using. This allows QMP to envolve without breaking old clients.

 A capability is a new QMP feature and/or protocol change which is not part of
the core protocol as defined in the QMP spec.

 Feature negotiation is implemented by defining a set of rules and adding
mode-oriented support.

 The set of rules are:

o All QMP capabilities are disabled by default
o All QMP capabilities must be advertised in the capabilities array
o Commands to enable/disable capabilities must be provided

NOTE: Asynchronous messages are now considered a capability.

 Mode-oriented support adds the following to QMP:

o Two modes: handshake and operational
o By default all QMP Monitors start in handshake mode
o In handshake mode only commands to query/enable/disable QMP capabilities are
  allowed (there are few exceptions)
o Clients can switch to the operational mode at any time
o In Operational mode most commands are allowed and QMP capabilities changes
  made in handshake mode take effect

 Also note that each QMP Monitor has its own mode state and set of capabilities,
this means that if QEMU is started with N QMP Monitors protocol setup done in
one of them doesn't affect the others.

 Session example:

"""
{"QMP": {"capabilities": ["async messages"]}}

{ "execute": "query-qmp-mode" }
{"return": {"mode": "handshake"}}

{ "execute": "change", "arguments": { "device": "vnc", "target": "password", "arg": "1234" } }
{"error": {"class": "QMPInvalidModeCommad", "desc": "The issued command is invalid in this mode", "data": {}}}

{ "execute": "async_msg_enable", "arguments": { "name": "STOP" } }
{"return": {}}

{ "execute": "qmp_switch_mode", "arguments": { "mode": "operational" } }
{"return": {}}

{ "execute": "query-qmp-mode" }
{"return": {"mode": "operational"}}

{ "execute": "change", "arguments": { "device": "vnc", "target": "password", "arg": "1234" } }
{"return": {}}
"""

 TODO:

- Update the spec
- Test more and fix some known issues
- Improve the changelog a bit