qemu: EVENTHANDLERS.txt: Move to kbase and rSTisze

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

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.

docs/kbase/internals/meson.build

@@ -5,6 +5,7 @@ docs_kbase_internals_files = [
   'locking',
   'migration',
   'overview',
+  'qemu-event-handlers',
   'qemu-migration',
   'qemu-threads',
   'rpc',

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
+``qemu_monitor_json.c:qemuMonitorJSONIOProcessEvent()``. It looks up the
-event by name in the table eventHandlers (in the same file), which
+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
+NB: This table is searched with bsearch, so it *must* be alphabetically sorted.
-  alphabetically sorted.
 
-qemuMonitorJSONIOProcessEvent calls the function listed in
+``qemuMonitorJSONIOProcessEvent`` calls the function listed in
-eventHandlers, e.g.:
+``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
+which uses ``QEMU_MONITOR_CALLBACK()`` to call
-mon->cb->domainNicRxFilterChanged(). domainNicRxFilterChanged is one
+``mon->cb->domainNicRxFilterChanged()``. ``domainNicRxFilterChanged`` is one
-in a list of function pointers in qemu_process.c:monitorCallbacks. For
+in a list of function pointers in ``qemu_process.c:monitorCallbacks``. For
-our example, it has been set to:
+our example, it has been set to::
 
    qemuProcessHandleNicRxFilterChanged()
 
-This function allocates a qemuProcessEvent object, and queues an event
+This function allocates a ``qemuProcessEvent`` object, and queues an event
-named QEMU_PROCESS_EVENT_NIC_RX_FILTER_CHANGED (you'll want to add an
+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
+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