[PATCH 3/3] qemu: EVENTHANDLERS.txt: Move to kbase and rSTisze

[Peter Krempa]

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 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