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);
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
