docs: kbase: internals: Make 'overview' page useful and link to it

While the content is slightly outdated it's still a good primer on how
an API call traverses through the client library and to the remote
driver.

To make the page useful, this commit:
 - removes the paragraphs which were intended to serve as a directory
   page for the 'internals' subdirectory
 - adds a note saying that some facts might not be up to date
 - adds linking to this page from the kbase directory page
 - adds more monospace formatting around function names

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

docs/kbase/index.rst

@@ -86,6 +86,10 @@ Internals
    VM migration implementation details, complementing the info in
    `migration <../migration.html>`__
 
+`API call flow overview <internals/overview.html>`__
+   Overview of how an API call is handled by the ``libvirt`` library and passed
+   over RPC to the daemon.
+
 `Spawning commands <internals/command.html>`__
    Spawning commands from libvirt driver code
 

docs/kbase/internals/overview.rst

@@ -1,117 +1,102 @@
-==========================
+=========================
-libvirt internals overview
+libvirt API call overview
-==========================
+=========================
-
-This section provides documents useful to those working on the libvirt
-internals, adding new public APIs, new hypervisor drivers or extending the
-libvirtd daemon code.
-
--  Introduction to basic rules and guidelines for `hacking <../../hacking.html>`__ on
-   libvirt code
--  Guide to adding `public APIs <../../api_extension.html>`__
--  Insight into libvirt `event loop and worker
-   pool <eventloop.html>`__
--  Approach for `spawning commands <command.html>`__ from libvirt
-   driver code
--  The libvirt `RPC infrastructure <rpc.html>`__
--  The `Resource Lock Manager <locking.html>`__
-
-Before adding new code it will be important to get a basic understanding of the
-many elements involved with making any call or change to the libvirt code. The
-architecture `goals <../../goals.html>`__ must be adhered to when submitting new code.
-Understanding the many places that need to be touched and the interactions
-between various subsystems within libvirt will directly correlate to the ability
-to be successful in getting new code accepted.
 
 The following diagram depicts code flow from a client application, in this case
 the libvirt provided ``virsh`` command through the various layers to elicit a
 response from some chosen hypervisor.
 
+**Note:** Some aspects of this document may be outdated.
+
 .. image:: ../../images/libvirt-virConnect-example.png
    :alt: virConnectOpen calling sequence
 
--  "virsh -c qemu:///system list --all"
+-  ``virsh -c qemu:///system list --all``
 
    After the virsh code processes the input arguments, it eventually will make a
    call to open the connection using a default set of authentication credentials
-   (virConnectAuthDefault).
+   (``virConnectAuthDefault``).
 
--  virConnectOpenAuth()
+-  ``virConnectOpenAuth()``
 
-   Each of the virConnectOpen APIs will first call virInitialize() and then
+   Each of the ``virConnectOpen`` APIs will first call ``virInitialize()`` and
-   revector through the local "do_open():" call.
+   then revector through the local "``do_open()``" call.
 
-   -  virInitialize()
+   -  ``virInitialize()``
 
       Calls the registration API for each of the drivers with client-side only
-      capabilities and then call the remoteRegister() API last. This ensures the
+      capabilities and then call the ``remoteRegister()`` API last. This
-      virDriverTab[] tries local drivers first before using the remote driver.
+      ensures the ``virDriverTab[]`` tries local drivers first before using the
+      remote driver.
 
-   -  Loop through virDriverTab[] entries trying to call their respective "open"
+   -  Loop through ``virDriverTab[]`` entries trying to call their respective
-      entry point (in our case remoteOpen())
+      "open" entry point (in our case ``remoteOpen()``)
 
-   -  After successful return from the virDriverTab[] open() API, attempt to
+   -  After successful return from the ``virDriverTab[]`` ``open()`` API,
-      find and open other drivers (network, interface, storage, etc.)
+      attempt to find and open other drivers (network, interface, storage, etc.)
 
--  remoteOpen()
+-  ``remoteOpen()``
 
-   After a couple of URI checks, a call to doRemoteOpen() is made
+   After a couple of URI checks, a call to ``doRemoteOpen()`` is made
 
    -  Determine network transport and host/port to use from URI
 
-      The transport will be either tls, unix, ssh, libssh2, ext, or tcp with the
+      The transport will be either ``tls``, ``unix``, ``ssh``, ``libssh2``,
-      default of tls. Decode the host/port if provided or default to
+      ``ext``, or ``tcp`` with the default of ``tls``. Decode the host/port if
-      "localhost".
+      provided or default to ``localhost``.
 
-   -  virNetClientRegisterAsyncIO()
+   -  ``virNetClientRegisterAsyncIO()``
 
       Register an I/O callback mechanism to get returned data via
-      virNetClientIncomingEvent()
+      ``virNetClientIncomingEvent()``
 
-   -  "call(...REMOTE_PROC_OPEN...)"
+   -  ``call(...REMOTE_PROC_OPEN...)``
 
-      Eventually routes into virNetClientProgramCall() which will call
+      Eventually routes into ``virNetClientProgramCall()`` which will call
-      virNetClientSendWithReply() and eventually uses virNetClientIO()to send
+      ``virNetClientSendWithReply()`` and eventually uses ``virNetClientIO()``
-      the message to libvirtd and then waits for a response using
+      to send the message to libvirtd and then waits for a response using
-      virNetClientIOEventLoop()
+      ``virNetClientIOEventLoop()``
 
-   -  virNetClientIncomingEvent()
+   -  ``virNetClientIncomingEvent()``
 
       Receives the returned packet and processes through
-      virNetClientIOUpdateCallback()
+      ``virNetClientIOUpdateCallback()``
 
 -  libvirtd Daemon
 
    -  Daemon Startup
 
       The daemon initialization processing will declare itself as a daemon via a
-      virNetDaemonNew() call, then creates new server using virNetServerNew()
+      ``virNetDaemonNew()`` call, then creates new server using
-      and adds that server to the main daemon struct with
+      ``virNetServerNew()`` and adds that server to the main daemon struct with
-      virNetDaemonAddServer() call. It will then use virDriverLoadModule() to
+      ``virNetDaemonAddServer()`` call. It will then use
-      find/load all known drivers, set up an RPC server program using the
+      ``virDriverLoadModule()`` to find/load all known drivers, set up an RPC
-      ``remoteProcs[]`` table via a virNetServerProgramNew() call. The table is
+      server program using the ``remoteProcs[]`` table via a
-      the corollary to the ``remote_procedure`` enum list in the client. It
+      ``virNetServerProgramNew()`` call. The table is the corollary to the
-      lists all the functions to be called in the same order. Once RPC is set
+      ``remote_procedure`` enum list in the client. It lists all the functions
-      up, networking server sockets are opened, the various driver state
+      to be called in the same order. Once RPC is set up, networking server
-      initialization routines are run from the ``virStateDriverTab[]``, the
+      sockets are opened, the various driver state initialization routines are
-      network links are enabled, and the daemon waits for work.
+      run from the ``virStateDriverTab[]``, the network links are enabled, and
+      the daemon waits for work.
 
    -  RPC
 
       When a message is received, the ``remoteProcs[]`` table is referenced for
-      the 'REMOTE_PROC_OPEN' call entry. This results in remoteDispatchOpen()
+      the ``REMOTE_PROC_OPEN`` call entry. This results in
-      being called via the virNetServerProgramDispatchCall().
+      ``remoteDispatchOpen()`` being called via the
+      ``virNetServerProgramDispatchCall()``.
 
-   -  remoteDispatchOpen()
+   -  ``remoteDispatchOpen()``
 
       The API will read the argument passed picking out the ``name`` of the
-      driver to be opened. The code will then call virConnectOpen() or
+      driver to be opened. The code will then call ``virConnectOpen()`` or
-      virConnectOpenReadOnly() depending on the argument ``flags``.
+      ``virConnectOpenReadOnly()`` depending on the argument ``flags``.
 
-   -  virConnectOpen() or virConnectOpenReadOnly()
+   -  ``virConnectOpen()`` or ``virConnectOpenReadOnly()``
 
       Just like the client except that upon entry the URI is what was passed
       from the client and will be found and opened to process the data.
 
-      The returned structure data is returned via the virNetServer interfaces to
+      The returned structure data is returned via the ``virNetServer``
-      the remote driver which then returns it to the client application.
+      interfaces to the remote driver which then returns it to the client
+      application.