Initial revision

ChangeLog

+Wed Nov  2 13:44:47 CET 2005 Daniel Veillard <veillard@redhat.com>
+
+	* src/libxen.c src/Makefile.am include/libxen.h configure.in
+	  Makefile.am COPYING.LIB: creation

Makefile.am

+## Process this file with automake to produce Makefile.in
+
+SUBDIRS = src #docs
+EXTRA_DIST = libxen.spec.in libxen.spec COPYING.LIB \
+             libxen.pc.in libxen.pc
+
+pkgconfigdir = $(libdir)/pkgconfig
+pkgconfig_DATA = libxen.pc
+

configure.in

+dnl Process this file with autoconf to produce a configure script.
+AC_INIT(entities.c)
+AM_CONFIG_HEADER(config.h)
+AC_CANONICAL_HOST
+
+LIBXEN_MAJOR_VERSION=0
+LIBXEN_MINOR_VERSION=0
+LIBXEN_MICRO_VERSION=1
+LIBXEN_MICRO_VERSION_SUFFIX=
+LIBXEN_VERSION=$LIBXEN_MAJOR_VERSION.$LIBXEN_MINOR_VERSION.$LIBXEN_MICRO_VERSION$LIBXEN_MICRO_VERSION_SUFFIX
+LIBXEN_VERSION_INFO=`expr $LIBXEN_MAJOR_VERSION + $LIBXEN_MINOR_VERSION`:$LIBXEN_MICRO_VERSION:$LIBXEN_MINOR_VERSION
+
+LIBXEN_VERSION_NUMBER=`expr $LIBXEN_MAJOR_VERSION \* 10000 + $LIBXEN_MINOR_VERSION \* 100 + $LIBXEN_MICRO_VERSION`
+
+if test -f CVS/Entries; then
+  extra=`grep ChangeLog CVS/Entries | grep -v LIBXEN | sed -e s\%/ChangeLog/1\.%% -e s\%/.*$%%`
+  echo extra=$extra
+  if test "$extra" != ""
+  then
+      LIBXEN_VERSION_EXTRA="-CVS$extra"
+  fi
+fi
+
+AC_SUBST(LIBXEN_MAJOR_VERSION)
+AC_SUBST(LIBXEN_MINOR_VERSION)
+AC_SUBST(LIBXEN_MICRO_VERSION)
+AC_SUBST(LIBXEN_VERSION)
+AC_SUBST(LIBXEN_VERSION_INFO)
+AC_SUBST(LIBXEN_VERSION_NUMBER)
+AC_SUBST(LIBXEN_VERSION_EXTRA)
+
+VERSION=${LIBXEN_VERSION}
+
+AM_INIT_AUTOMAKE(libxen, $VERSION)
+

docs/Plan

+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

+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

+
+          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
+

include/libxen.h

+/*
+ * libxen.h: interface for the libxen library to handle Xen domains
+ *           from a process running in domain 0
+ *
+ * Copyright (C) 2005 Red Hat, Inc.
+ *
+ * See COPYING.LIB for the License of this software
+ *
+ * Daniel Veillard <veillard@redhat.com>
+ */
+
+#ifndef __XEN_XENLIB_H__
+#define __XEN_XENLIB_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * xenConnect:
+ *
+ * a xenConnect is a private structure representing a connection to
+ * the Xen Hypervisor.
+ */
+typedef struct _xenConnect xenConnect;
+
+/**
+ * xenConnectPtr:
+ *
+ * a xenConnectPtr is pointer to a xenConnect private structure, this is the
+ * type used to reference a connection to the Xen Hypervisor in the API.
+ */
+typedef xenConnect *xenConnectPtr;
+
+/**
+ * xenDomain:
+ *
+ * a xenDomain is a private structure representing a Xen domain.
+ */
+typedef struct _xenDomain xenDomain;
+
+/**
+ * xenDomainPtr:
+ *
+ * a xenDomainPtr is pointer to a xenDomain private structure, this is the
+ * type used to reference a Xen domain in the API.
+ */
+typedef xenDomain *xenDomainPtr;
+
+
+/**
+ * xenDomainFlags:
+ *
+ * Flags OR'ed together to provide specific behaviour when creating a
+ * Domain.
+ */
+typedef enum {
+     XEN_DOMAIN_NONE = 0
+} xenDomainFlags;
+
+/*
+ * Connection and disconnections to the Hypervisor
+ */
+xenConnectPtr		xenOpenConnect		(const char *name);
+int			xenCloseConnect		(xenConnectPtr conn);
+unsigned long		xenGetVersion		(xenConnectPtr conn);
+
+/*
+ * Domain creation and destruction
+ */
+xenDomainPtr		xenCreateLinuxDomain	(xenConnectPtr conn,
+						 const char *kernel_path,
+						 const char *initrd_path,
+						 const char *cmdline,
+						 unsigned int flags);
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __XEN_XENLIB_H__ */

src/Makefile.am

+## Process this file with automake to produce Makefile.in
+
+INCLUDES = -I$(top_builddir)/include -I@srcdir@/include
+
+lib_LTLIBRARIES = libxen.la
+libxen_la_LIBADD = 
+libxen_la_LDFLAGS = -version-info @LIBXML_VERSION_INFO@
+libxen_la_SOURCES = libxen.c

src/libxen.c

+/*
+ * libxen.h: Main interfaces for the libxen library to handle virtualization
+ *           domains from a process running in domain 0
+ *
+ * Copyright (C) 2005 Red Hat, Inc.
+ *
+ * See COPYING.LIB for the License of this software
+ *
+ * Daniel Veillard <veillard@redhat.com>
+ */
+
+#include "libxen.h"
+
+#include "memory.h"
+#include "internal.h"
+
+/*
+ * TODO:
+ * - use lock to protect against concurrent accesses ?
+ * - use reference counting to garantee coherent pointer state ?
+ */
+
+#define XEN_CONNECT_MAGIC 0x4F23DEAD
+/**
+ * _xenConnect:
+ *
+ * Internal structure associated to a connection
+ */
+struct _xenConnect {
+    unsigned int magic;		/* specific value to check */
+    int	         handle;	/* internal handle used for hypercall */
+}
+
+/**
+ * xenGetConnect:
+ * @name: optional argument currently unused, pass NULL
+ *
+ * This function should be called first to get a connection to the 
+ * Hypervisor
+ *
+ * Returns a pointer to the hypervisor connection or NULL in case of error
+ */
+xenConnectPtr
+xenOpenConnect(const char *name ATTRIBUTE_UNUSED) {
+    return(NULL);
+}
+
+/**
+ * xenCloseConnect:
+ * @conn: pointer to the hypervisor connection
+ *
+ * This function closes the connection to the Hypervisor. This should
+ * not be called if further interaction with the Hypervisor are needed
+ * especially if there is running domain which need further monitoring by
+ * the application.
+ *
+ * Returns 0 in case of success or -1 in case of error.
+ */
+int
+xenCloseConnect(xenConnectPtr conn) {
+    if ((conn == NULL) || (conn->magic != XEN_CONNECT_MAGIC))
+        return(-1);
+    /*
+     * TODO:
+     * Free the domain pointers associated to this connection
+     */
+    conn->magic = -1;
+    free(conn);
+    return(0);
+}
+
+/**
+ * xenGetVersion:
+ * @conn: pointer to the hypervisor connection
+ *
+ * Get the version level of the Hypervisor running