docs/internals.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>libvirt internals</h1>
   6
   7     <p>
   8       This section provides documents useful to those working on the libvirt
   9       internals, adding new public APIs, new hypervisor drivers or extending
  10       the libvirtd daemon code.
  11     </p>
  12
  13     <ul>
  14       <li>Introduction to basic rules and guidelines for
  15       <a href="hacking.html">hacking</a> on libvirt code</li>
  16       <li>Guide to adding <a href="api_extension.html">public APIs</a></li>
  17       <li>Insight into libvirt <a href="internals/eventloop.html">event loop and worker pool</a></li>
  18       <li>Approach for <a href="internals/command.html">spawning commands</a>
  19       from libvirt driver code</li>
  20       <li>The libvirt <a href="internals/rpc.html">RPC infrastructure</a></li>
  21       <li>The <a href="internals/locking.html">Resource Lock Manager</a></li>
  22     </ul>
  23
  24     <p>Before adding new code it will be important to get a basic understanding
  25     of the many elements involved with making any call or change to the libvirt
  26     code. The architecture <a href="goals.html">goals</a> must be adhered to
  27     when submitting new code. Understanding the many places that need to be
  28     touched and the interactions between various subsystems within libvirt
  29     will directly correlate to the ability to be successful in getting new
  30     code accepted.</p>
  31     <p>The following diagram depicts code flow from a client application, in
  32     this case the libvirt provided <code>virsh</code> command through the
  33     various layers to elicit a response from some chosen hypervisor.
  34     </p>
  35
  36     <p class="image">
  37       <img alt="virConnectOpen calling sequence"
  38            src="libvirt-virConnect-example.png"/>
  39     </p>
  40     <ul>
  41         <li>"virsh -c qemu:///system list --all"
  42         <p>After the virsh code processes the input arguments, it eventually
  43         will make a call to open the connection using a default set of
  44         authentication credentials (virConnectAuthDefault). </p></li>
  45         <li>virConnectOpenAuth()
  46         <p>Each of the virConnectOpen APIs will first call virInitialize() and
  47         then revector through the local "do_open():" call.</p>
  48           <ul>
  49             <li>virInitialize()
  50             <p>Calls the registration API for each of the drivers with
  51             client-side only capabilities and then call the remoteRegister()
  52             API last. This ensures the virDriverTab[] tries local drivers
  53             first before using the remote driver.</p></li>
  54             <li>Loop through virDriverTab[] entries trying to call their
  55             respective "open" entry point (in our case remoteOpen())</li>
  56             <li>After successful return from the virDriverTab[] open()
  57             API, attempt to find and open other drivers (network, interface,
  58             storage, etc.)</li>
  59           </ul>
  60         </li>
  61         <li>remoteOpen()
  62         <p>After a couple of URI checks, a call to doRemoteOpen() is made</p>
  63           <ul>
  64             <li>Determine network transport and host/port to use from URI
  65             <p>The transport will be either tls, unix, ssh, libssh2, ext,
  66             or tcp with the default of tls. Decode the host/port if provided
  67             or default to "localhost".</p></li>
  68             <li>virNetClientRegisterAsyncIO()
  69             <p>Register an I/O callback mechanism to get returned data via
  70             virNetClientIncomingEvent()</p></li>
  71             <li>"call(...REMOTE_PROC_OPEN...)"
  72             <p>Eventually routes into virNetClientProgramCall() which will
  73             call virNetClientSendWithReply() and eventually uses
  74             virNetClientIO()to send the message to libvirtd and
  75             then waits for a response using virNetClientIOEventLoop()</p></li>
  76             <li>virNetClientIncomingEvent()
  77             <p>Receives the returned packet and processes through
  78             virNetClientIOUpdateCallback()</p></li>
  79           </ul>
  80         </li>
  81         <li>libvirtd Daemon
  82         <p></p>
  83           <ul>
  84               <li>Daemon Startup
  85               <p>The daemon initialization processing will declare itself
  86               as a daemon via a virNetDaemonNew() call, then creates new server
  87               using virNetServerNew() and adds that server to the main daemon
  88               struct with virNetDaemonAddServer() call.  It will then use
  89               virDriverLoadModule() to find/load all known drivers,
  90               set up an RPC server program using the <code>remoteProcs[]</code>
  91               table via a virNetServerProgramNew() call. The table is the
  92               corollary to the <code>remote_procedure</code> enum list in
  93               the client. It lists all the functions to be called in
  94               the same order. Once RPC is set up, networking server sockets
  95               are opened, the various driver state initialization routines
  96               are run from the <code>virStateDriverTab[]</code>, the network
  97               links are enabled, and the daemon waits for work.</p></li>
  98               <li>RPC
  99               <p>When a message is received, the <code>remoteProcs[]</code>
 100               table is referenced for the 'REMOTE_PROC_OPEN' call entry.
 101               This results in remoteDispatchOpen() being called via the
 102               virNetServerProgramDispatchCall().</p></li>
 103               <li>remoteDispatchOpen()
 104               <p>The API will read the argument passed picking out the
 105               <code>name</code> of the driver to be opened. The code
 106               will then call virConnectOpen() or virConnectOpenReadOnly()
 107               depending on the argument <code>flags</code>.</p></li>
 108               <li>virConnectOpen() or virConnectOpenReadOnly()
 109               <p>Just like the client except that upon entry the URI
 110               is what was passed from the client and will be found
 111               and opened to process the data.</p>
 112               <p>The returned structure data is returned via the
 113               virNetServer interfaces to the remote driver which then
 114               returns it to the client application.</p></li>
 115           </ul>
 116         </li>
 117     </ul>
 118   </body>
 119 </html>