Clarify README

git-svn-id: svn+ssh://svn-nitpicker.cl.cam.ac.uk/linpicker/trunk@115 88473608-6f18-0410-8b6c-91216bd3049c

1 files changed, 36 insertions, 22 deletions

diff --git a/README b/README
index f6d1d49..cd6255d 100644
--- a/README
+++ b/README
@@ -1,8 +1,10 @@
 This is "Linpicker", a Linux version of Nitpicker.
 As much code as possible was copied from the Nitpicker implementation,
 so the same license (GNU GPL) applies.
+Phil Dollery came up with the name "Linpicker"; David A. Wheeler
+confirmed on Apr 20, 2007 that Google found no hits for the name.
 
-Nitpicker's implementation is deeply married to L4; trying to get its
+Nitpicker's original implementation is deeply married to L4; trying to get its
 incredibly baroque build environment and tools (esp. the DICE CORBA compiler)
 working took enormous amounts of time, even with the start of a Linux
 implementation.  That start turned out to be painful; it presumed that
@@ -26,32 +28,44 @@ since any search would find multiple instances of files.
 So this re-implements Nitpicker, but with the KISS notion.
 SIMPLICITY is the goal here, with small amounts of code.
 
-I thought about using an existing ORB (like ORBit), but that'd have the
-same problem as DICE: Lots of code that we can't depend on.  Since we must
-port to Xen (on grant tables, etc.), and nearly all CORBA functionality
-is unneeded, it was easier to write a tiny comm structure ourselves.
+Currently this implementation uses the CORBA implementation ORBit2,
+because this is a well-supported implementation.  The original Nitpicker
+depended on a CORBA interface, so this simplifies transition.
 
-Phil Dollery came up with the name "Linpicker"; David A. Wheeler
-confirmed on Apr 20, 2007 that Google found no hits for the name.
-
-Not trying to be CORBA (or DCE) compliant.  See:
-"The Rise and Fall of CORBA" by Michi Henning, ZeroC
-
-The comm structure has the goals of:
+The plan is to port to Linux using ORBit, and then separately replace
+the comm structure to use Xen directly.  
+We must port to Xen (on grant tables, etc.), and nearly all CORBA functionality
+is unneeded, so eventually a tiny comm structure that we can directly
+control will be helpful.  The issue is that we want to know EXACTLY
+what the code does, and limit its size, so that we can be confident of
+its security.  The eventual system need not be CORBA (or DCE) compliant, see
+"The Rise and Fall of CORBA" by Michi Henning, ZeroC.
+The comm structure will have the goals of:
 * Very simple tool implementation
 * Very simple resulting code (easily examined)
 * Robust against malicious clients: clients may drop partway through,
   send excessive or insufficient data, or send "wrong" messages.
 
-This code is dependant upon the direct frame buffer library.  It requires 
-that the file /dev/fb be present this means that the kernal level frame 
-buffer driver must be loaded.  In order to load the svga (vesa) frame buffer 
-you must load it in grub.conf.  This requires adding the following line to 
-one of the boot kernels:
+The code uses the "directfb" library, a library that simplifies access
+to the underlying framebuffer.  In particular, this means that we don't
+have to write code for drawing lines, characters, doing blits, etc.
+This library also supports 2D hardware acceleration, which is a nice plus.
+For this library to work, the underlying
+kernel must provide framebuffer access via /dev/fb.  On Linux,
+this means that kernel level frame buffer driver must be loaded.
+You can use a driver specific your graphics card that supports framebuffer
+access.  If one is not available, you can use the svga (vesa) framebuffer
+driver, which supports the application framebuffer interface by
+using the widely-supported vesa interface to the graphics card.
+
+In order to load the svga (vesa) frame buffer you must load it in
+at kernel boot time.  For GRUB users, this means modifying grub.conf
+by adding the following line to the boot kernel (change the kernel id
+to yours):
+kernel /vmlinuz-2.6.22.9-61.fc6 ro root=LABEL=/1 video=vesafb:ywrap,mtrr vga=788
+This fb driver is only activated at boot time and the settings cannot be 
+changed using fbset.
 
-kernel /vmlinuz-2.6.22.9-61.fc6 ro root=LABEL=/1 video=vesafb:ywrap,mtrr 
-vga=788
+You can also try loading a card-specific module as root
+if you know your card's maker.  
 
-This fb driver is only activated at boot time and the settings can not be 
-changed using fbset.  You can also try loading the module as root if you know 
-your cards maker.