From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=43452 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PogTZ-00005S-HG for qemu-devel@nongnu.org; Sun, 13 Feb 2011 13:15:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PogTY-0000Hl-8Z for qemu-devel@nongnu.org; Sun, 13 Feb 2011 13:15:13 -0500 Received: from mail-yi0-f45.google.com ([209.85.218.45]:53823) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PogTY-0000Hh-44 for qemu-devel@nongnu.org; Sun, 13 Feb 2011 13:15:12 -0500 Received: by yie21 with SMTP id 21so1944127yie.4 for ; Sun, 13 Feb 2011 10:15:11 -0800 (PST) Message-ID: <4D581FAA.5020808@codemonkey.ws> Date: Sun, 13 Feb 2011 12:15:06 -0600 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [RFC] qapi: events in QMP References: <4D581E04.1020901@codemonkey.ws> In-Reply-To: <4D581E04.1020901@codemonkey.ws> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , Luiz Capitulino , qemu-devel , Markus Armbruster On 02/13/2011 12:08 PM, Anthony Liguori wrote: > Hi, > > In my QAPI branch[1], I've now got almost every existing QMP command > converted with (hopefully) all of the hard problems solved. There is > only one remaining thing to attack before posting for inclusion and > that's events. Here's my current thinking about what to do. > > Events in QMP Today > > QMP events are asynchronous messages. They are not tied explicitly to > any type of context, do not have a well defined format, and are have > no mechanism to mask or filter events. As of right now, we have > somewhere around a dozen events. > > Goals of QAPI > > 1) Make all interfaces consumable in C such that we can use the > interfaces in QEMU > > 2) Make all interfaces exposed through a library using code generation > from static introspection > > 3) Make all interfaces well specified in a formal schema > > Proposal for events in QAPI > > For QAPI, I'd like to model events on the notion of signals and > slots[2]. A client would explicitly connect to a signal through a QMP > interface which would result in a slot being added that then generates > an event. Internally in QEMU, we could also connect slots to the same > signals. Since we don't have an object API in QMP, we'd use a pair of > connect/disconnect functions that had enough information to identify > the signal. > > Example: > > We would define QEVENT_BLOCK_IO_EVENT as: > > # qmp-schema.json > { 'BlockIOEvent': {'device': 'str', 'action': 'str', 'operation': > 'str'} } > > The 'Event' suffix is used to determine that the type is an event and > not a structure. This would generate the following structures for QEMU: > > typedef void (BlockIOEventFunc)(const char *device, const char > *action, const char *operation, void *opaque); One thing I'm on the fence about, is making the slot callback take a BlockIOEvent *event as the first argument. If we did this, the signals would be compatible with GObject signals. It's hard to map that to a libqmp though so I'm not sure. Regards, Anthony Liguori > > typedef struct BlockIOEvent { > /* contents are private */ > } BlockIOEvent; > > /* Connect a slot to a BlockIOEvent signal and return a handle to the > connection */ > int block_io_event_connect(BlockIOEvent *event, BlockIOEventFunc *cb, > void *opaque); > > /* Signal any connect slots of a BlockIOEvent */ > void block_io_event_signal(BlockIOEvent *event, const char *device, > const char *action, const char *operation); > > /* Disconnect a slot from a signal based on a connection handle */ > void block_io_event_disconnect(BlockIOEvent *event, int handle); > > In the case of BlockIOEvent, this is a global signal that is not tied > to any specific object so there would be a global BlockIOEvent object > within QEMU. > > From a QMP perspective, we would have the following function in the > schema: > > [ 'block-io-event', {}, {}, 'BlockIOEvent' ] > > A function definition that returns an Event is a signal accessor. > Within QEMU, we implement a signal accessor like so: > > BlockIOEvent *qmp_block_io_event(Error **errp) > { > return &global_block_io_event; > } > > For QMP and libqmp, signal accessors are handled specially. A signal > accessor is expanded into two QMP functions: > > [ 'block-io-event-connect', {}, {}, 'str' ] > [ 'block-io-event-disconnect', {'tag' : 'str'}, {}, 'none' ] > > Connect returns a handle to the connection as an opaque string. > Disconnect takes that handle. Both functions will also take any > arguments that the signal accessor takes and under the cover uses the > signal accessor to access the object. > > In libqmp, the following interfaces will be generated: > > int libqmp_block_io_event_connect(QmpSession *sess, BlockIOEventFunc > *cb, void *opaque, Error **errp); > void libqmp_block_io_event_disconnect(QmpSession *sess, int handle, > Error **errp); > > Again, if the signal accessor takes additional arguments, they will be > passed here. > > All existing events will be converted to signals with signal accessors > that take no arguments. However, BlockIOEvent is a good example of a > signal that we'll add a new version of that takes a 'const char > *device' as an argument for the signal accessor. This will let > clients register for block io events on specific block devices. > > Backwards Compatibility > > Right now, QMP events to not have any type of context information > which means that there's no way to communicate the connection handle. > We'll solve this by adding a new 'tag' field to events that are > registered through one of the connect interfaces. Since this is only > present on events registered through this new interface, backwards > compatibility is preserved. > > Upon initial connection, we'll treat all existing signals as having a > 'default signal connection'. We'll introduce a new QMP command that > can be executed while in capabilities mode to disconnect default > signal connections. The effect is that new clients can use the > explicit register/unregister interface while old clients will continue > to see the old style events. > > We'll deprecate the 'default signal connections' and make sure to > never add a new one post 0.15. Old clients will need to be updated to > explicitly register for events. > > Another Example > > Here's an example of BlockDeviceEvent, the successor to BlockIOEvent. > It makes use of signal accessor arguments and QAPI enumeration support: > > # qmp-schema.json > { 'BlockDeviceAction': [ 'report', 'stop', 'none' ] } > { 'BlockDeviceOperation': [ 'read', 'write' ] } > { 'BlockDeviceActionReason': [ 'nospc', 'io', 'other' ] } > { 'BlockDeviceEvent': { 'action': 'BlockDeviceAction', 'operation': > 'BlockDeviceOperation', 'reason': 'BlockDeviceActionReason' } } > > [ 'block-device-event', { 'device': 'str' }, {}, 'BlockDeviceEvent' ] > > # qemu/block.c (Signal Accessor) > BlockDeviceEvent *qmp_block_device_event(const char *str, Error **errp)' > > # qemu/qmp-types.h (Generated QMP interfaces) > typedef enum BlockDeviceAction { > BDA_REPORT = 0, > BDA_STOP, > BDA_NONE, > } BlockDeviceAction; > > typedef enum BlockDeviceOperation { > BDO_READ = 0, > BDO_WRITE, > } BlockDeviceOperation; > > typedef enum BlockDeviceActionReason { > BDAR_NOSPC = 0, > BDAR_IO, > BDAR_OTHER, > } BlockDeviceActionReason; > > typedef struct BlockDeviceEvent { > /* private */ > } BlockDeviceEvent; > > typedef void (BlockDeviceEventFunc)(BlockDeviceAction action, > BlockDeviceOperation operator, BlockDeviceActionReason reason); > > int block_device_event_connect(BlockDeviceEvent *event, > BlockDeviceEventFunc *cb, void *opaque); > void block_device_event_disconnect(BlockDeviceEvent *event, int handle); > > # qemu/libqmp.h (Generated libqmp interfaces) > > int libqmp_block_device_event_connect(QmpSession *sess, const char > *device, BlockDeviceEventFunc *cb, void *opaque); > > void libqmp_block_device_event_disconnect(QmpSession *sess, const char > *device, int handle); > > Regards, > > Anthony Liguori > > [1] http://repo.or.cz/w/qemu/aliguori.git/shortlog/refs/heads/glib > > [2] http://en.wikipedia.org/wiki/Signals_and_slots > >