libvirt/docs/library.xen

          About a libxen library
	  ======================

Functional description:
-----------------------

  Small C library to be able to control Xen Linux guest, i.e.
    provide the following operations for Xen guest domains running Linux
    from domain 0 code linked to the library (running as root):
     - start
     - stop
     - suspend
     - resume
     - monitor 
  More advanced features should be allowed as future extensions, but
  are not expected to be provided in first shipment.
  
  Open enough Licence that customers can link their apps to it (LGPL)

  Small and contained enough that we can use it as a way to
  provide API and ABI stability in spite if the evolution of Xen
  existing API and hypervisor calls.

The current state of Xen userland:
----------------------------------

  the existing Xen 3.0 userland code is mostly based on tiny C functions
using direct hypervisor calls (or /proc/xen/ interfaces) and a lot of
Python code on top driving the hypervisor.
  The C code is relatively hairy, functions with 10 parameters or more
are not uncommon, and it is very low level usually without comment about
the function or its arguments. They are usually only called once in the
whole tree by the python bindings. In essence it looks like the Xen project
was not implemented with the idea of reusing that part of the code by 
applications. 
  Indeed most of the userland code coming with Xen is built on Python,
like xend the xen daemon running on domain 0 or the xenstored daemon which
manage the state of the domains launched.

Rebuilding a library ?:
-----------------------

  Providing a library at the C level to drive domain execution is in a
very large part a rimplementation of existing code but in a different way
and somehow with different goals for the code. The existing Licence (GPL)
makes it uneasy, we can't copy GPL code to put it in a LGPL'ed library,
and rewriting everything while looking at the Xen code will inevitably
lead to code similarities especially with this kind of system code. Plus
we will still need to run xend and probably xenstored to not diverge
completely from Xen existing code base.

The IBM way:
------------

  Here is supposition about code that I can't instanciate except by looking
at said code but it looks that IBM also needed a C programmatic API to 
manage the Xen domain definitions. Their solution was to build (Rusty
Russell did this) an LGPL C API connecting directly to the xenstore
daemon (./tools/xenstore/*). In a way this is quite more fragile as it depends
on the whole existing stack of the Xen code, but it isolate the API
from the implementation details of the current Xen source (API in
./tools/xenstore/xs.h). The goal seems to be more about testing and controlling
the xen store daemon, but it shows a different approach to decouple client
API/ABI from the Xen existing code.

Open question:
---------------

  To what extent should libxen be a rewrite or an isolation layer around
some of the existing code ?

  Rewrite:

    Pros:
     - avoid the GPL Licence problem potentially more users
     - allow do build a cleaner more stable layer
     - the existing code is frigthening
    Cons:
     - awful lot of work debugging very hard
     - will still require existing Xen code to be running
     - splitting interfaces is hard politically and lower the
       Open Source efforts toward the project

  Wrappers on top of existing code:

    Pros:
     - much smaller code rewrite
     - benefits from the bugfixes injected by other patchers upstream
    Cons:
     - Licence constraint GPL only for apps
     - API/ABI isolation may not be easier in that way

  Potentially the API could be implemented as a layer on top of the existing
libxc C code library and then progressively migrating out the existing
dependance to Xen code as the interfaces stabilize.

Daniel Veillard <veillard@redhat.com>

Mon Oct 24 18:40:19 CEST 2005