Initial revision

1 files changed, 101 insertions, 0 deletions

diff --git a/docs/library.xen b/docs/library.xen
new file mode 100644
index 0000000..aa2c822
--- /dev/null
+++ b/docs/library.xen
@@ -0,0 +1,101 @@
+
+          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
+