Initial revision

docs/Plan

@@ -0,0 +1,4 @@
+1/ go for a minimal library first, expand on use cases
+2/ reuse xenctrl.h / libxenctrl in a first implementation, but make
+   sure to clearly isolate the bits calling them
+3/ 

docs/analysis

@@ -0,0 +1,33 @@
+arch/xen/kernel/evtchn.c: Communication via Xen event channels
+->HYPERVISOR_xen_version call 
+->HYPERVISOR_physdev_op call
+->HYPERVISOR_event_channel_op call
+-> global HYPERVISOR_shared_info
+
+arch/xen/kernel/fixup.c: binary rewrinting for threads TLS
+-> message to suppress... + boot delay
+
+arch/xen/kernel/gnttab.c: memory access and sharing
+  inline assemby from privcmd.c using TRAP_INSTR macro to do an hypervisor
+  call apparently.
+
+arch/xen/kernel/reboot.c: 
+-> HYPERVISOR_suspend call
+
+include/asm-xen/asm-i386/hypercall.h:
+-> assembly macro for the hypervisor calls
+
+tools/libxc/xc_*.c: library for xen control
+
+tools/libxc/xc_private.h:
+  -> Xen hypervisor call is an ioctl() with an privcmd_hypercall_t parameter
+  xc_domain.c:
+  -> API for all domain supervisor calls, create, memory, cpu weight, destroy
+
+=> Fraser all over the place ...
+
+/Xen/xen-unstable.hg/tools/libxc
+
+
+  The hypervisor calls are defined as inlined functions in xc_private.h
+This is GPL and not installed. 

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
+