9 a.m.
Note that this document was not referenced from any top level page. This
patch does a straight conversion and leaves it unreferenced.
Next patch will then modify it to serve as an overview (hence the new
name) of how an API call happens.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/internals.html.in | 119 ------------------------------
docs/kbase/internals/meson.build | 1 +
docs/kbase/internals/overview.rst | 117 +++++++++++++++++++++++++++++
docs/meson.build | 1 -
4 files changed, 118 insertions(+), 120 deletions(-)
delete mode 100644 docs/internals.html.in
create mode 100644 docs/kbase/internals/overview.rst
diff --git a/docs/internals.html.in b/docs/internals.html.in
deleted file mode 100644
index e474f7ddd7..0000000000
--- a/docs/internals.html.in
+++ /dev/null
@@ -1,119 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>libvirt internals</h1>
-
- <p>
- 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.
- </p>
-
- <ul>
- <li>Introduction to basic rules and guidelines for
- <a href="hacking.html">hacking</a> on libvirt
code</li>
- <li>Guide to adding <a href="api_extension.html">public
APIs</a></li>
- <li>Insight into libvirt <a
href="internals/eventloop.html">event loop and worker
pool</a></li>
- <li>Approach for <a href="internals/command.html">spawning
commands</a>
- from libvirt driver code</li>
- <li>The libvirt <a href="internals/rpc.html">RPC
infrastructure</a></li>
- <li>The <a href="internals/locking.html">Resource Lock
Manager</a></li>
- </ul>
-
- <p>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 <a href="goals.html">goals</a> 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.</p>
- <p>The following diagram depicts code flow from a client application, in
- this case the libvirt provided <code>virsh</code> command through the
- various layers to elicit a response from some chosen hypervisor.
- </p>
-
- <p class="image">
- <img alt="virConnectOpen calling sequence"
- src="images/libvirt-virConnect-example.png"/>
- </p>
- <ul>
- <li>"virsh -c qemu:///system list --all"
- <p>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). </p></li>
- <li>virConnectOpenAuth()
- <p>Each of the virConnectOpen APIs will first call virInitialize() and
- then revector through the local "do_open():" call.</p>
- <ul>
- <li>virInitialize()
- <p>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.</p></li>
- <li>Loop through virDriverTab[] entries trying to call their
- respective "open" entry point (in our case
remoteOpen())</li>
- <li>After successful return from the virDriverTab[] open()
- API, attempt to find and open other drivers (network, interface,
- storage, etc.)</li>
- </ul>
- </li>
- <li>remoteOpen()
- <p>After a couple of URI checks, a call to doRemoteOpen() is
made</p>
- <ul>
- <li>Determine network transport and host/port to use from URI
- <p>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".</p></li>
- <li>virNetClientRegisterAsyncIO()
- <p>Register an I/O callback mechanism to get returned data via
- virNetClientIncomingEvent()</p></li>
- <li>"call(...REMOTE_PROC_OPEN...)"
- <p>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()</p></li>
- <li>virNetClientIncomingEvent()
- <p>Receives the returned packet and processes through
- virNetClientIOUpdateCallback()</p></li>
- </ul>
- </li>
- <li>libvirtd Daemon
- <p></p>
- <ul>
- <li>Daemon Startup
- <p>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
<code>remoteProcs[]</code>
- table via a virNetServerProgramNew() call. The table is the
- corollary to the <code>remote_procedure</code> 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 <code>virStateDriverTab[]</code>, the network
- links are enabled, and the daemon waits for work.</p></li>
- <li>RPC
- <p>When a message is received, the
<code>remoteProcs[]</code>
- table is referenced for the 'REMOTE_PROC_OPEN' call entry.
- This results in remoteDispatchOpen() being called via the
- virNetServerProgramDispatchCall().</p></li>
- <li>remoteDispatchOpen()
- <p>The API will read the argument passed picking out the
- <code>name</code> of the driver to be opened. The code
- will then call virConnectOpen() or virConnectOpenReadOnly()
- depending on the argument
<code>flags</code>.</p></li>
- <li>virConnectOpen() or virConnectOpenReadOnly()
- <p>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.</p>
- <p>The returned structure data is returned via the
- virNetServer interfaces to the remote driver which then
- returns it to the client application.</p></li>
- </ul>
- </li>
- </ul>
- </body>
-</html>
diff --git a/docs/kbase/internals/meson.build b/docs/kbase/internals/meson.build
index 879c4b2de8..8b5daad1f9 100644
--- a/docs/kbase/internals/meson.build
+++ b/docs/kbase/internals/meson.build
@@ -4,6 +4,7 @@ docs_kbase_internals_files = [
'incremental-backup',
'locking',
'migration',
+ 'overview',
'rpc',
]
diff --git a/docs/kbase/internals/overview.rst b/docs/kbase/internals/overview.rst
new file mode 100644
index 0000000000..84ea7858db
--- /dev/null
+++ b/docs/kbase/internals/overview.rst
@@ -0,0 +1,117 @@
+==========================
+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.
+
+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.
+
+.. image:: ../../images/libvirt-virConnect-example.png
+ :alt: virConnectOpen calling sequence
+
+- "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).
+
+- virConnectOpenAuth()
+
+ Each of the virConnectOpen APIs will first call virInitialize() and then
+ revector through the local "do_open():" call.
+
+ - 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.
+
+ - 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.)
+
+- remoteOpen()
+
+ 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".
+
+ - virNetClientRegisterAsyncIO()
+
+ Register an I/O callback mechanism to get returned data via
+ virNetClientIncomingEvent()
+
+ - "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()
+
+ - virNetClientIncomingEvent()
+
+ Receives the returned packet and processes through
+ 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.
+
+ - 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().
+
+ - 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``.
+
+ - 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.
diff --git a/docs/meson.build b/docs/meson.build
index 4291dea6f5..9f1f1ed80d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
'formatnwfilter',
'formatstoragecaps',
'index',
- 'internals',
'remote',
'storage',
'uri',
--
2.35.1