[Qemu-devel] [PATCH 4/6] Document new events (v2)

[Anthony Liguori]

This patch introduces a standard way to document all new events.  It also
enforces that documentation exists for each event.  This documentation includes
a description of the details parameters that the event generates.

Signed-off-by: Anthony Liguori <address@hidden>

diff --git a/Makefile.target b/Makefile.target
index b32d1af..adfe81b 100644
--- a/Makefile.target
+++ b/Makefile.target
@@ -495,6 +495,7 @@ endif #CONFIG_BSD_USER
 ifndef CONFIG_USER_ONLY
 
 OBJS=vl.o osdep.o monitor.o pci.o loader.o isa_mmio.o machine.o dma-helpers.o
+OBJS+=wait-events.o
 # virtio has to be here due to weird dependency between PCI and virtio-net.
 # need to fix this properly
 OBJS+=virtio.o virtio-blk.o virtio-balloon.o virtio-net.o virtio-console.o
diff --git a/monitor.c b/monitor.c
index 1a7d026..8aed435 100644
--- a/monitor.c
+++ b/monitor.c
@@ -43,6 +43,7 @@
 #include "kvm.h"
 #include "acl.h"
 #include "wait.h"
+#include "wait-events.h"
 
 //#define DEBUG
 //#define DEBUG_COMPLETION
@@ -1752,6 +1753,8 @@ static const mon_cmd_t mon_cmds[] = {
     { "poll", "-xs?", do_poll,
       "[-x] [mask]",
       "poll for an asynchronous event (-x to make mask exclusive, mask 
specifies the event classes to poll for)" },
+    { "show_event", "s?s?", do_show_event, "[class [name]]",
+      "show information about supported events" },
     { NULL, NULL, },
 };
 
diff --git a/wait-events.c b/wait-events.c
new file mode 100644
index 0000000..3617ca6
--- /dev/null
+++ b/wait-events.c
@@ -0,0 +1,143 @@
+/*
+ * Asynchronous monitor notification support
+ *
+ * Copyright IBM, Corp. 2009
+ *
+ * Authors:
+ *  Anthony Liguori   <address@hidden>
+ *
+ * This work is licensed under the terms of the GNU GPL, version 2.  See
+ * the COPYING file in the top-level directory.
+ *
+ */
+
+#include "qemu-common.h"
+#include "wait-events.h"
+
+typedef struct EventDesc
+{
+    const char *name;
+    const char *short_desc;
+    const char *long_desc;
+    const char *detail_format;
+} EventDesc;
+
+typedef struct EventClassDesc
+{
+    const char *class;
+    const char *short_desc;
+    const char *long_desc;
+    const EventDesc *events;
+} EventClassDesc;
+
+static const EventDesc vm_state_events[] = {
+    { 0 },
+};
+
+static const EventClassDesc vm_event_classes[] = {
+    { 0 },
+};
+
+static const EventDesc *find_event_desc(const EventClassDesc *desc, const char 
*name)
+{
+    int i;
+
+    for (i = 0; desc->events[i].name; i++) {
+        if (strcmp(desc->events[i].name, name) == 0)
+            return &desc->events[i];
+    }
+
+    return NULL;
+}
+
+static const EventClassDesc *find_event_class(const char *class)
+{
+    int i;
+
+    for (i = 0; vm_event_classes[i].class; i++) {
+        if (strcmp(vm_event_classes[i].class, class) == 0)
+            return &vm_event_classes[i];
+    }
+
+    return NULL;
+}
+
+int qemu_is_notify_event_valid(const char *class, const char *name)
+{
+    const EventClassDesc *c;
+    const EventDesc *e;
+
+    c = find_event_class(class);
+    if (c == NULL)
+        return 0;
+
+    e = find_event_desc(c, name);
+    if (e == NULL)
+        return 0;
+
+    return 1;
+}
+
+static void do_show_event_name(Monitor *mon, const EventDesc *e)
+{
+    monitor_printf(mon, "%s\n", e->long_desc);
+    if (e->detail_format && strlen(e->detail_format)) {
+        monitor_printf(mon, "\n");
+        monitor_printf(mon, "Details Format:\n");
+        monitor_printf(mon, "%s\n", e->detail_format);
+    }
+}
+
+static void do_show_event_class(Monitor *mon, const EventClassDesc *c)
+{
+    int i;
+
+    monitor_printf(mon, "%s\n", c->long_desc);
+    monitor_printf(mon, "\n");
+    monitor_printf(mon, "Events:\n");
+    for (i = 0; c->events[i].name; i++) {
+        monitor_printf(mon, " %s - %s\n",
+                       c->events[i].name,
+                       c->events[i].short_desc);
+    }
+}
+
+static void do_show_event_list(Monitor *mon)
+{
+    int i;
+
+    for (i = 0; vm_event_classes[i].class; i++) {
+        monitor_printf(mon, "%s - %s\n",
+                       vm_event_classes[i].class,
+                       vm_event_classes[i].short_desc);
+    }
+}
+
+void do_show_event(Monitor *mon, const char *class, const char *name)
+{
+    if (class && strlen(class)) {
+        const EventClassDesc *c;
+
+        c = find_event_class(class);
+        if (c == NULL) {
+            monitor_printf(mon, "Unknown class: %s\n", class);
+            return;
+        }
+
+        if (name && strlen(name)) {
+            const EventDesc *e;
+
+            e = find_event_desc(c, name);
+            if (e == NULL) {
+                monitor_printf(mon, "Unknown event: %s\n", name);
+                return;
+            }
+
+            do_show_event_name(mon, e);
+        } else {
+            do_show_event_class(mon, c);
+        }
+    } else {
+        do_show_event_list(mon);
+    }
+}
diff --git a/wait-events.h b/wait-events.h
new file mode 100644
index 0000000..4770ec5
--- /dev/null
+++ b/wait-events.h
@@ -0,0 +1,23 @@
+/*
+ * Asynchronous monitor notification support
+ *
+ * Copyright IBM, Corp. 2009
+ *
+ * Authors:
+ *  Anthony Liguori   <address@hidden>
+ *
+ * This work is licensed under the terms of the GNU GPL, version 2.  See
+ * the COPYING file in the top-level directory.
+ *
+ */
+
+#ifndef QEMU_WAIT_EVENTS_H
+#define QEMU_WAIT_EVENTS_H
+
+#include "monitor.h"
+
+int qemu_is_notify_event_valid(const char *class, const char *name);
+
+void do_show_event(Monitor *mon, const char *class, const char *name);
+
+#endif
diff --git a/wait.c b/wait.c
index ebc156a..a976a72 100644
--- a/wait.c
+++ b/wait.c
@@ -16,6 +16,7 @@
 #include "sys-queue.h"
 #include "osdep.h"
 #include "wait.h"
+#include "wait-events.h"
 
 typedef struct WaitEvent
 {
@@ -161,6 +162,11 @@ void qemu_notify_event(const char *class, const char 
*name, const char *details)
 {
     WaitEvent *e;
 
+    if (!qemu_is_notify_event_valid(class, name)) {
+        fprintf(stderr, "BUG: invalid class/name %s: %s\n", class, name);
+        abort();
+    }
+
     e = qemu_mallocz(sizeof(*e));
 
     qemu_gettimeofday(&e->timestamp);