Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
docs/kbase/index.rst | 3 ++
docs/kbase/internals/meson.build | 1 +
.../kbase/internals/qemu-event-handlers.rst | 44 ++++++++++---------
3 files changed, 28 insertions(+), 20 deletions(-)
rename src/qemu/EVENTHANDLERS.txt => docs/kbase/internals/qemu-event-handlers.rst (64%)
diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst
index d0f2167be8..8b710db85a 100644
--- a/docs/kbase/index.rst
+++ b/docs/kbase/index.rst
@@ -107,3 +107,6 @@ Internals
`QEMU migration internals <internals/qemu-migration.html>`__
Description of migration phases in the ``v2`` and ``v3`` migration protocol.
+
+`QEMU monitor event handling <internals/qemu-event-handlers.html>`__
+ Brief outline how events emitted by qemu on the monitor are handlded.
diff --git a/docs/kbase/internals/meson.build b/docs/kbase/internals/meson.build
index 4f7b223786..a16d5a290b 100644
--- a/docs/kbase/internals/meson.build
+++ b/docs/kbase/internals/meson.build
@@ -5,6 +5,7 @@ docs_kbase_internals_files = [
'locking',
'migration',
'overview',
+ 'qemu-event-handlers',
'qemu-migration',
'qemu-threads',
'rpc',
diff --git a/src/qemu/EVENTHANDLERS.txt b/docs/kbase/internals/qemu-event-handlers.rst
similarity index 64%
rename from src/qemu/EVENTHANDLERS.txt
rename to docs/kbase/internals/qemu-event-handlers.rst
index 39094d793e..3589c4c48c 100644
--- a/src/qemu/EVENTHANDLERS.txt
+++ b/docs/kbase/internals/qemu-event-handlers.rst
@@ -1,10 +1,14 @@
+===================
+QEMU event handlers
+===================
+
This is a short description of how an example qemu event can be used
to trigger handler code that is called from the context of a worker
thread, rather than directly from the event thread (which should
itself never block, and can't do things like send qemu monitor
commands, etc).
-In this case (the NIC_RX_FILTER_CHANGED event) the event is handled by
+In this case (the ``NIC_RX_FILTER_CHANGED`` event) the event is handled by
calling a qemu monitor command to get the current RX filter state,
then executing ioctls/sending netlink messages on the host in response
to changes in that filter state. This event is *not* propagated to the
@@ -14,39 +18,39 @@ to the end of this document, please do!).
Hopefully this narration will be helpful when adding handlers for
other qemu events in the future.
-----------------------------------------------------
+QEMU monitor events
+-------------------
Any event emitted by qemu is received by
-qemu_monitor_json.c:qemuMonitorJSONIOProcessEvent(). It looks up the
-event by name in the table eventHandlers (in the same file), which
+``qemu_monitor_json.c:qemuMonitorJSONIOProcessEvent()``. It looks up the
+event by name in the table ``eventHandlers`` (in the same file), which
should have an entry like this for each event that libvirt
-understands:
+understands::
{ "NIC_RX_FILTER_CHANGED", qemuMonitorJSONHandleNicRxFilterChanged, },
- NB: This table is searched with bsearch, so it *must* be
- alphabetically sorted.
+NB: This table is searched with bsearch, so it *must* be alphabetically sorted.
-qemuMonitorJSONIOProcessEvent calls the function listed in
-eventHandlers, e.g.:
+``qemuMonitorJSONIOProcessEvent`` calls the function listed in
+``eventHandlers``, e.g.::
qemu_monitor_json.c:qemuMonitorJSONHandleNicRxFilterChanged()
which extracts any required data from the JSON ("name" in this case),
-and calls:
+and calls::
qemu_monitor.c:qemuMonitorEmitNicRxFilterChanged()
-which uses QEMU_MONITOR_CALLBACK() to call
-mon->cb->domainNicRxFilterChanged(). domainNicRxFilterChanged is one
-in a list of function pointers in qemu_process.c:monitorCallbacks. For
-our example, it has been set to:
+which uses ``QEMU_MONITOR_CALLBACK()`` to call
+``mon->cb->domainNicRxFilterChanged()``. ``domainNicRxFilterChanged`` is one
+in a list of function pointers in ``qemu_process.c:monitorCallbacks``. For
+our example, it has been set to::
qemuProcessHandleNicRxFilterChanged()
-This function allocates a qemuProcessEvent object, and queues an event
-named QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED (you'll want to add an
-enum to qemu_domain.h:qemuProcessEventType for your event) for a
+This function allocates a ``qemuProcessEvent`` object, and queues an event
+named ``QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED`` (you'll want to add an
+enum to ``qemu_domain.h:qemuProcessEventType`` for your event) for a
worker thread to handle.
(Everything up to this point has happened in the context of the thread
@@ -56,17 +60,17 @@ monitor. Everything after this is handled in the context of a worker
thread, so it has more freedom to make qemu monitor calls and blocking
system calls on the host.)
-When the worker thread gets the event, it calls
+When the worker thread gets the event, it calls::
qemuProcessEventHandler()
which switches on the eventType (in our example,
-QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED) and decides to call:
+``QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED``) and decides to call::
processNicRxFilterChangedEvent()
and *that* is where the actual work will be done (and any
-event-specific memory allocated during qemuProcessHandleXXX() will be
+event-specific memory allocated during ``qemuProcessHandleXXX()`` will be
freed). Note that this function must do proper refcounting of the
domain object, and assure that the domain is still active prior to
performing any operations - it is possible that the domain could have
--
2.35.3
