|
 |
9119d9 |
From ff87b8626006538a4f681cfe68ef336d861e2d4d Mon Sep 17 00:00:00 2001
|
|
|
9119d9 |
Message-Id: <ff87b8626006538a4f681cfe68ef336d861e2d4d@dist-git>
|
|
|
9119d9 |
From: Laine Stump <laine@laine.org>
|
|
|
9119d9 |
Date: Mon, 3 Nov 2014 10:00:19 -0500
|
|
|
9119d9 |
Subject: [PATCH] qemu: add short document on qemu event handlers
|
|
|
9119d9 |
|
|
|
9119d9 |
https://bugzilla.redhat.com/show_bug.cgi?id=848199
|
|
|
9119d9 |
|
|
|
9119d9 |
This text was in the commit log for the patch that added the event
|
|
|
9119d9 |
handler for NIC_RX_FILTER_CHANGED, and John Ferlan expressed a desire
|
|
|
9119d9 |
that the information not be "lost", so I've put it into a file in the
|
|
|
9119d9 |
qemu directory, hoping that it might catch the attention of future
|
|
|
9119d9 |
writers of handlers for qemu events.
|
|
|
9119d9 |
|
|
|
9119d9 |
(cherry picked from commit ac4f8be422521875b64f51bcea953a6d1c6bfb09)
|
|
|
9119d9 |
|
|
|
9119d9 |
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
|
|
|
9119d9 |
---
|
|
|
9119d9 |
src/qemu/EVENTHANDLERS.txt | 76 ++++++++++++++++++++++++++++++++++++++++++++++
|
|
|
9119d9 |
1 file changed, 76 insertions(+)
|
|
|
9119d9 |
create mode 100644 src/qemu/EVENTHANDLERS.txt
|
|
|
9119d9 |
|
|
|
9119d9 |
diff --git a/src/qemu/EVENTHANDLERS.txt b/src/qemu/EVENTHANDLERS.txt
|
|
|
9119d9 |
new file mode 100644
|
|
|
9119d9 |
index 0000000..79c1505
|
|
|
9119d9 |
--- /dev/null
|
|
|
9119d9 |
+++ b/src/qemu/EVENTHANDLERS.txt
|
|
|
9119d9 |
@@ -0,0 +1,76 @@
|
|
|
9119d9 |
+This is a short description of how an example qemu event can be used
|
|
|
9119d9 |
+to trigger handler code that is called from the context of a worker
|
|
|
9119d9 |
+thread, rather than directly from the event thread (which should
|
|
|
9119d9 |
+itself never block, and can't do things like send qemu monitor
|
|
|
9119d9 |
+commands, etc).
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+In this case (the NIC_RX_FILTER_CHANGED event) the event is handled by
|
|
|
9119d9 |
+calling a qemu monitor command to get the current RX filter state,
|
|
|
9119d9 |
+then executing ioctls/sending netlink messages on the host in response
|
|
|
9119d9 |
+to changes in that filter state. This event is *not* propagated to the
|
|
|
9119d9 |
+libvirt API (but if someone wants to add details of how to handle that
|
|
|
9119d9 |
+to the end of this document, please do!).
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+Hopefully this narration will be helpful when adding handlers for
|
|
|
9119d9 |
+other qemu events in the future.
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+----------------------------------------------------
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+Any event emitted by qemu is received by
|
|
|
9119d9 |
+qemu_monitor_json.c:qemuMonitorJSONProcessEvent(). It looks up the
|
|
|
9119d9 |
+event by name in the table eventHandlers (in the same file), which
|
|
|
9119d9 |
+should have an entry like this for each event that libvirt
|
|
|
9119d9 |
+understands:
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ { "NIC_RX_FILTER_CHANGED", qemuMonitorJSONHandleNicRxFilterChanged, },
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ NB: This table is searched with bsearch, so it *must* be
|
|
|
9119d9 |
+ alphabetically sorted.
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+qemuMonitorJSONProcessEvent calls the function listed in
|
|
|
9119d9 |
+eventHandlers, e.g.:
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ qemu_monitor_json.c:qemuMonitorJSONHandleNicRxFilterChanged()
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+which extracts any required data from the JSON ("name" in this case),
|
|
|
9119d9 |
+and calls:
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ qemu_monitor.c:qemuMonitorEmitNicRxFilterChanged()
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+which uses QEMU_MONITOR_CALLBACK() to call
|
|
|
9119d9 |
+mon->cb->domainNicRxFilterChanged(). domainNicRxFilterChanged is one
|
|
|
9119d9 |
+in a list of function pointers in qemu_process.c:monitorCallbacks. For
|
|
|
9119d9 |
+our example, it has been set to:
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ qemuProcessHandleNicRxFilterChanged()
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+This function allocates a qemuProcessEvent object, and queues an event
|
|
|
9119d9 |
+named QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED (you'll want to add an
|
|
|
9119d9 |
+enum to qemu_domain.h:qemuProcessEventType for your event) for a
|
|
|
9119d9 |
+worker thread to handle.
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+(Everything up to this point has happened in the context of the thread
|
|
|
9119d9 |
+that is reading events from qemu, so it should do as little as
|
|
|
9119d9 |
+possible, never block, and never call back into the qemu
|
|
|
9119d9 |
+monitor. Everything after this is handled in the context of a worker
|
|
|
9119d9 |
+thread, so it has more freedom to make qemu monitor calls and blocking
|
|
|
9119d9 |
+system calls on the host.)
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+When the worker thread gets the event, it calls
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ qemuProcessEventHandler()
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+which switches on the eventType (in our example,
|
|
|
9119d9 |
+QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED) and decides to call:
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+ processNicRxFilterChangedEvent()
|
|
|
9119d9 |
+
|
|
|
9119d9 |
+and *that* is where the actual work will be done (and any
|
|
|
9119d9 |
+event-specific memory allocated during qemuProcessHandleXXX() will be
|
|
|
9119d9 |
+freed). Note that this function must do proper refcounting of the
|
|
|
9119d9 |
+domain object, and assure that the domain is still active prior to
|
|
|
9119d9 |
+performing any operations - it is possible that the domain could have
|
|
|
9119d9 |
+been destroyed between the time the event was received and the time
|
|
|
9119d9 |
+that it is processed, and it is also possible that the domain could be
|
|
|
9119d9 |
+destroyed *during* the event processing if it doesn't get properly
|
|
|
9119d9 |
+referenced by the handler.
|
|
|
9119d9 |
--
|
|
|
9119d9 |
2.1.3
|
|
|
9119d9 |
|