add a readme

README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5c0ba1f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+<!--
+    Copyright 2014, NICTA
+
+    This software may be distributed and modified according to the terms of
+    the BSD 2-Clause license. Note that NO WARRANTY is provided.
+    See "LICENSE_BSD2.txt" for details.
+
+    @TAG(NICTA_BSD)
+-->
+
+libsel4utils
+=============
+
+libsel4utils provides OS-like utilities for building benchmarks and applications on seL4.
+Although the library attempts to be policy agnostic, some decisions must be made.
+
+This library is intended to be used to quickly get tests, benchmarks and prototypes off the ground
+with minimal effort. 
+It can also be used as a reference for 'how-to' implement OS mechanisms on seL4.
+
+Utilities provided by this library:
+
+    * threads
+    * processes
+    * elf loading
+    * virtual memory management
+    * stack switching
+    * debugging tools
+
+No allocator is provided, although any allocator that implements the seL4 vka interface can be used
+(we recommend libsel4allocman). 
+
+Dependencies
+------------------
+
+libsel4utils depends on libsel4vka, libsel4vspace, libutils, libelf, libcpio, libsel4.
+
+Repository overview
+-------------------
+   
+*include/sel4utils*:
+
+    * client_server_vspace.h -- a virtual address space that proxies calls between two different 
+                                vspaces
+    * elf.h -- elf loading.
+    * mapping.h -- page mapping.
+    * process.h -- process creation, deletion.
+    * profile.h -- profiling.
+    * sel4_debug.h -- for printing seL4 error codes.
+    * stack.h -- switch to a newly allocated stack. 
+    * thread.h -- threads (kernel threads) creation, deletion.
+    * util.h -- includes utilities from libutils.
+    * vspace.h -- virtual memory management (implements vspace interface)
+    * vspace_internal.h -- virtual memory management internals, for hacking the above.
+
+*arch_include/sel4utils*:
+
+    * util.h -- utils to assist in writing arch independent code.
+
+Configuration options
+----------------------
+
+* SEL4UTILS_STACK_SIZE -- the default stack size to use for processes and threads.
+* SEL4UTILS_CSPACE_SIZE_BITS -- the default cspace size for new processes (threads use the current
+                                cspace).
+
+License
+========
+
+The files in this repository are release under standard open source licenses.
+Please see individual file headers and the `LICENSE_BSD2`.txt file for details.