1
0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 17:34:18 +03:00

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>
This commit is contained in:
Peter Krempa 2022-04-07 14:08:41 +02:00
parent b51afd97e5
commit a89b17c2a7
2 changed files with 57 additions and 68 deletions

View File

@ -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

View File

@ -1,117 +1,102 @@
==========================
libvirt internals 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.
=========================
libvirt API call overview
=========================
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
revector through the local "do_open():" call.
Each of the ``virConnectOpen`` APIs will first call ``virInitialize()`` and
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
virDriverTab[] tries local drivers first before using the remote driver.
capabilities and then call the ``remoteRegister()`` API last. This
ensures the ``virDriverTab[]`` tries local drivers first before using the
remote driver.
- Loop through virDriverTab[] entries trying to call their respective "open"
entry point (in our case remoteOpen())
- Loop through ``virDriverTab[]`` entries trying to call their respective
"open" entry point (in our case ``remoteOpen()``)
- After successful return from the virDriverTab[] open() API, attempt to
find and open other drivers (network, interface, storage, etc.)
- After successful return from the ``virDriverTab[]`` ``open()`` API,
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
default of tls. Decode the host/port if provided or default to
"localhost".
The transport will be either ``tls``, ``unix``, ``ssh``, ``libssh2``,
``ext``, or ``tcp`` with the default of ``tls``. Decode the host/port if
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
virNetClientSendWithReply() and eventually uses virNetClientIO()to send
the message to libvirtd and then waits for a response using
virNetClientIOEventLoop()
Eventually routes into ``virNetClientProgramCall()`` which will call
``virNetClientSendWithReply()`` and eventually uses ``virNetClientIO()``
to send the message to libvirtd and then waits for a response using
``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()
and adds that server to the main daemon struct with
virNetDaemonAddServer() call. It will then use virDriverLoadModule() to
find/load all known drivers, set up an RPC server program using the
``remoteProcs[]`` table via a virNetServerProgramNew() call. The table is
the corollary to the ``remote_procedure`` enum list in the client. It
lists all the functions to be called in the same order. Once RPC is set
up, networking server sockets are opened, the various driver state
initialization routines are run from the ``virStateDriverTab[]``, the
network links are enabled, and the daemon waits for work.
``virNetDaemonNew()`` call, then creates new server using
``virNetServerNew()`` and adds that server to the main daemon struct with
``virNetDaemonAddServer()`` call. It will then use
``virDriverLoadModule()`` to find/load all known drivers, set up an RPC
server program using the ``remoteProcs[]`` table via a
``virNetServerProgramNew()`` call. The table is the corollary to the
``remote_procedure`` enum list in the client. It lists all the functions
to be called in the same order. Once RPC is set up, networking server
sockets are opened, the various driver state initialization routines are
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()
being called via the virNetServerProgramDispatchCall().
the ``REMOTE_PROC_OPEN`` call entry. This results in
``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
virConnectOpenReadOnly() depending on the argument ``flags``.
driver to be opened. The code will then call ``virConnectOpen()`` or
``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 remote driver which then returns it to the client application.
The returned structure data is returned via the ``virNetServer``
interfaces to the remote driver which then returns it to the client
application.