qemu: new API for tracking arbitrary monitor events

Several times in the past, qemu has implemented a new event,
but libvirt has not yet caught up to reporting that event to
the user applications.  While it is possible to track libvirt
logs to see that an unknown event was received and ignored,
it would be nicer to copy what 'virsh qemu-monitor-command'
does, and expose this information to the end developer as
one of our unsupported qemu-specific commands.

If you find yourself needing to use this API for more than
just development purposes, please ask on the libvirt list
for a supported counterpart event to be added in libvirt.so.

While the supported virConnectDomainEventRegisterAny() API
takes an id which determines the signature of the callback,
this version takes a string filter and always uses the same
signature.  Furthermore, I chose to expose this as a new API
instead of trying to add a new eventID at the top level, in
part because the generic option lacks event name filtering,
and in part because the normal domain event namespace should
not be polluted by a qemu-only event.  I also added a flags
argument; unused for now, but we might decide to use it to
allow a user to request event names by glob or regex instead
of literal match.

This API intentionally requires full write access (while
normal event registration is allowed on read-only clients);
this is in part due to the fact that it should only be used
by debugging situations, and in part because the design of
per-event filtering in later patches ended up allowing for
duplicate registrations that could potentially be abused to
exhaust server memory - requiring write privileges means
that such abuse will not serve as a denial of service attack
against users with higher privileges.

* include/libvirt/libvirt-qemu.h
(virConnectDomainQemuMonitorEventCallback)
(virConnectDomainQemuMonitorEventRegister)
(virConnectDomainQemuMonitorEventDeregister): New prototypes.
* src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister)
(virConnectDomainQemuMonitorEventDeregister): New functions.
* src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them.
* src/driver.h (virDrvConnectDomainQemuMonitorEventRegister)
(virDrvConnectDomainQemuMonitorEventDeregister): New callbacks.

Signed-off-by: Eric Blake <eblake@redhat.com>

diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h
index 3e79a8ccfa39538e2d9e78f41bc126b6b8b95c4a..ed6d3d2abe005a9b8c9140e961793c960a5af322 100644 (file)
--- a/include/libvirt/libvirt-qemu.h
+++ b/include/libvirt/libvirt-qemu.h
@@ -4,7 +4,7 @@
  * Description: Provides the interfaces of the libvirt library to handle
  *              qemu specific methods
  *
- * Copyright (C) 2010, 2012 Red Hat, Inc.
+ * Copyright (C) 2010-2014 Red Hat, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -54,6 +54,40 @@ typedef enum {
 char *virDomainQemuAgentCommand(virDomainPtr domain, const char *cmd,
                                 int timeout, unsigned int flags);
 
+/**
+ * virConnectDomainQemuMonitorEventCallback:
+ * @conn: the connection pointer
+ * @dom: the domain pointer
+ * @event: the name of the event
+ * @seconds: the qemu timestamp of the event: seconds since Epoch, or -1 if
+ *           not available
+ * @micros: the qemu timestamp of the event: microseconds within the second
+ * @details: the JSON details of the event, if any were given
+ * @opaque: application specified data
+ *
+ * The callback signature to use when registering for a qemu monitor
+ * event with virConnectDomainQemuMonitorEventRegister().
+ */
+typedef void (*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn,
+                                                         virDomainPtr dom,
+                                                         const char *event,
+                                                         long long seconds,
+                                                         unsigned int micros,
+                                                         const char *details,
+                                                         void *opaque);
+
+int virConnectDomainQemuMonitorEventRegister(virConnectPtr conn,
+                                             virDomainPtr dom,
+                                             const char *event,
+                                             virConnectDomainQemuMonitorEventCallback cb,
+                                             void *opaque,
+                                             virFreeCallback freecb,
+                                             unsigned int flags);
+
+int virConnectDomainQemuMonitorEventDeregister(virConnectPtr conn,
+                                               int callbackID);
+
+
 # ifdef __cplusplus
 }
 # endif

diff --git a/src/driver.h b/src/driver.h
index d106d59b544e72d6cec9f3a5bb1894beed18b3a2..d728705623896947ac1e78640f39b9f46f39f51c 100644 (file)
--- a/src/driver.h
+++ b/src/driver.h
@@ -842,6 +842,19 @@ typedef virDomainPtr
                           unsigned int pid_value,
                           unsigned int flags);
 
+typedef int
+(*virDrvConnectDomainQemuMonitorEventRegister)(virConnectPtr conn,
+                                               virDomainPtr dom,
+                                               const char *event,
+                                               virConnectDomainQemuMonitorEventCallback cb,
+                                               void *opaque,
+                                               virFreeCallback freecb,
+                                               unsigned int flags);
+
+typedef int
+(*virDrvConnectDomainQemuMonitorEventDeregister)(virConnectPtr conn,
+                                                 int callbackID);
+
 typedef int
 (*virDrvDomainOpenConsole)(virDomainPtr dom,
                            const char *dev_name,
@@ -1302,6 +1315,8 @@ struct _virDriver {
     virDrvDomainQemuMonitorCommand domainQemuMonitorCommand;
     virDrvDomainQemuAttach domainQemuAttach;
     virDrvDomainQemuAgentCommand domainQemuAgentCommand;
+    virDrvConnectDomainQemuMonitorEventRegister connectDomainQemuMonitorEventRegister;
+    virDrvConnectDomainQemuMonitorEventDeregister connectDomainQemuMonitorEventDeregister;
     virDrvDomainOpenConsole domainOpenConsole;
     virDrvDomainOpenChannel domainOpenChannel;
     virDrvDomainOpenGraphics domainOpenGraphics;

diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c
index 2f66e2d0b3787c32acf041b33aabf2561abe15f8..a75a725eb18b9dbb31cecc53c964f54880199039 100644 (file)
--- a/src/libvirt-qemu.c
+++ b/src/libvirt-qemu.c
@@ -217,3 +217,124 @@ error:
     virDispatchError(conn);
     return NULL;
 }
+
+
+/**
+ * virConnectDomainQemuMonitorEventRegister:
+ * @conn: pointer to the connection
+ * @dom: pointer to the domain, or NULL
+ * @event: name of the event, or NULL
+ * @cb: callback to the function handling monitor events
+ * @opaque: opaque data to pass on to the callback
+ * @freecb: optional function to deallocate opaque when not used anymore
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * This API is QEMU specific, so it will only work with hypervisor
+ * connections to the QEMU driver.
+ *
+ * Adds a callback to receive notifications of arbitrary qemu monitor events
+ * occurring on a domain.  Many qemu monitor events also result in a libvirt
+ * event which can be delivered via virConnectDomainEventRegisterAny(); this
+ * command is primarily for testing new qemu events that have not yet been
+ * given a libvirt counterpart event.
+ *
+ * If @dom is NULL, then events will be monitored for any domain. If @dom
+ * is non-NULL, then only the specific domain will be monitored.
+ *
+ * If @event is NULL, then all monitor events will be reported. If @event is
+ * non-NULL, then only the specific monitor event will be reported.  @flags
+ * is currently unused, but in the future may support a flag for passing
+ * @event as a glob instead of a literal name to match a category of events.
+ *
+ * The virDomainPtr object handle passed into the callback upon delivery
+ * of an event is only valid for the duration of execution of the callback.
+ * If the callback wishes to keep the domain object after the callback returns,
+ * it shall take a reference to it, by calling virDomainRef().
+ * The reference can be released once the object is no longer required
+ * by calling virDomainFree().
+ *
+ * The return value from this method is a positive integer identifier
+ * for the callback. To unregister a callback, this callback ID should
+ * be passed to the virConnectDomainQemuMonitorEventDeregister() method.
+ *
+ * Returns a callback identifier on success, -1 on failure
+ */
+int
+virConnectDomainQemuMonitorEventRegister(virConnectPtr conn,
+                                         virDomainPtr dom,
+                                         const char *event,
+                                         virConnectDomainQemuMonitorEventCallback cb,
+                                         void *opaque,
+                                         virFreeCallback freecb,
+                                         unsigned int flags)
+{
+    VIR_DOMAIN_DEBUG(dom,
+                     "conn=%p, event=%s, cb=%p, opaque=%p, freecb=%p, flags=%x",
+                     conn, NULLSTR(event), cb, opaque, freecb, flags);
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, -1);
+    if (dom) {
+        virCheckDomainGoto(dom, error);
+        if (dom->conn != conn) {
+            virReportInvalidArg(dom,
+                                _("domain '%s' in %s must match connection"),
+                                dom->name, __FUNCTION__);
+            goto error;
+        }
+    }
+    virCheckNonNullArgGoto(cb, error);
+    virCheckReadOnlyGoto(conn->flags, error);
+
+    if (conn->driver && conn->driver->connectDomainQemuMonitorEventRegister) {
+        int ret;
+        ret = conn->driver->connectDomainQemuMonitorEventRegister(conn, dom, event, cb, opaque, freecb, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+error:
+    virDispatchError(conn);
+    return -1;
+}
+
+
+/**
+ * virConnectDomainQemuMonitorEventDeregister:
+ * @conn: pointer to the connection
+ * @callbackID: the callback identifier
+ *
+ * Removes an event callback. The callbackID parameter should be the
+ * value obtained from a previous virConnectDomainQemuMonitorEventRegister()
+ * method.
+ *
+ * Returns 0 on success, -1 on failure
+ */
+int
+virConnectDomainQemuMonitorEventDeregister(virConnectPtr conn,
+                                           int callbackID)
+{
+    VIR_DEBUG("conn=%p, callbackID=%d", conn, callbackID);
+
+    virResetLastError();
+
+    virCheckConnectReturn(conn, -1);
+    virCheckNonNegativeArgGoto(callbackID, error);
+    virCheckReadOnlyGoto(conn->flags, error);
+
+    if (conn->driver && conn->driver->connectDomainQemuMonitorEventDeregister) {
+        int ret;
+        ret = conn->driver->connectDomainQemuMonitorEventDeregister(conn, callbackID);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virReportUnsupportedError();
+error:
+    virDispatchError(conn);
+    return -1;
+}

diff --git a/src/libvirt_qemu.syms b/src/libvirt_qemu.syms
index f968d9171611d2d725bd9532417380da1a6f6d8b..3a297e3a2bd1425a3f0a8b794540fb067d81213e 100644 (file)
--- a/src/libvirt_qemu.syms
+++ b/src/libvirt_qemu.syms
@@ -24,3 +24,9 @@ LIBVIRT_QEMU_0.10.0 {
     global:
         virDomainQemuAgentCommand;
 } LIBVIRT_QEMU_0.9.4;
+
+LIBVIRT_QEMU_1.2.3 {
+    global:
+        virConnectDomainQemuMonitorEventDeregister;
+        virConnectDomainQemuMonitorEventRegister;
+} LIBVIRT_QEMU_0.10.0;