Update README.

1 files changed, 124 insertions, 299 deletions

diff --git a/README b/README
index a73ced6..7aa2be4 100644
--- a/README
+++ b/README
@@ -1,299 +1,124 @@
-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 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
-UDP packets are never dropped (but they are!), that UDP port numbers have
-same properties as local thread ids (but they don't!), and so on.
-It was also deeply unsuitable for real security; Nitpicker itself was small,
-but all the code it deeply depended on turned out to be a massive
-infrastructure that "had" to come with it.  Not only would that be hard
-to validate for security - it was clear that it was NOT secure (against
-buffer overflows, denial-of-service attacks, and so on).
-Nitpicker's DICE compiler was particularly troublesome; it generated code
-that was unsuitable, so you ended up having to edit generated (code).
-DICE is specifically designed to be an "IDL kernel for L4 micro-kernels",
-as it clearly states on its web page... woe to those who don't use L4.
-In theory you could modify DICE, but DICE was absurdly complex (an example
-of how with enough method calls you can obscure any functionality).
-The build environment depended on virtual paths, which ONLY make could see...
-so all other tools (e.g., ctags, grep, etc.) were nearly useless,
-since any search would find multiple instances of files.
-
-So this ports Nitpicker, but with the KISS notion.
-SIMPLICITY is the goal here, with small amounts of code.
-
-At first this implementation uses the CORBA implementation ORBit2,
-because this is a well-supported implementation.  The original Nitpicker
-depended on a CORBA interface, so this simplified transition.
-
-The plan was 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.
-
-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=0x312
-This fb driver is only activated at boot time and the settings cannot be 
-changed using fbset.
-
-The graphic modes are NOT in the list which you get if you boot with
-vga=ask and hit return. The mode you wish to use is derived from the
-VESA mode number. Here are those VESA mode numbers:
-
-    | 640x480  800x600  1024x768 1280x1024
-----+-------------------------------------
-256 |  0x101    0x103    0x105    0x107   
-32k |  0x110    0x113    0x116    0x119   
-64k |  0x111    0x114    0x117    0x11A   
-16M |  0x112    0x115    0x118    0x11B   
-
-The video mode number of the Linux kernel is the VESA mode number plus
-0x200.
- 
- Linux_kernel_mode_number = VESA_mode_number + 0x200
-
-So the table for the Kernel mode numbers are:
-
-    | 640x480  800x600  1024x768 1280x1024
-----+-------------------------------------
-256 |  0x301    0x303    0x305    0x307   
-32k |  0x310    0x313    0x316    0x319   
-64k |  0x311    0x314    0x317    0x31A   
-16M |  0x312    0x315    0x318    0x31B   
-
-To enable one of those modes you have to specify "vga=ask" in the
-lilo.conf file and rerun LILO. Then you can type in the desired
-mode at the "vga=ask" prompt. For example if you like to use 
-1024x768x256 colors you have to say "305" at this prompt.
-
-For this code use mode 312 so the vga number will be 312.
-
-You can also try loading a card-specific module as root
-if you know your card's maker.  
-
-
-====================
-
-This depends on version 1.1 of directfb.  directfb is easily installed
-on a Fedora system using "yum install directfb", but at the time of this
-writing, this directfb is too old.
-
-To update to the latest version of directfb, follow these steps:
-
-Remove directfb, if you have it installed:
- sudo yum remove directfb # If previously installed by yum
-
-Make sure you have these installed:
- autoconf
- autoconf213
-
-You may want to install VNC development packages ahead-of-time, so it
-can use them.
-
-We will install in "/usr" instead of "/usr/local"; by default Fedora
-systems don't look at all the right /usr/local directories.
-
-
-# Download into a ~/directfb
-cd ~
-mkdir directfb
-cd directfb/
-git clone git://git.directfb.org/git/directfb/core/DirectFB.git
-git clone git://git.directfb.org/git/directfb/extras/DirectFB-extra.git
-
-# Compile and build DirectFB
-cd DirectFB
-aclocal -I ./m4
-autoheader
-libtoolize --automake
-automake --copy --add-missing
-# Lots of warnings
-autoconf
-
-./configure --prefix=/usr
-make
-
-su
-make install
-# control-D to leave su mode
-
-
-cd .. # Done.
-
-
-
-# Compile and install DirectFB-extras.
-# Note: You MUST install "DirectFB" before trying to build and install
-# the DirectFB-extras.
-
-cd DirectFB-extra
-
-# Note: NOT aclocal -I ./m4
-# because there's no "m4" subdirectory.  If you "mkdir -p m4" first,
-# then you could use the same command sequence as above.
-aclocal
-autoheader
-libtoolize --automake
-automake --copy --add-missing
-# Lots of warnings
-autoconf
-
-Otherwise the code goes into the 32 bit library
-
-# WARNING: 64-bit issue.  When you compile under 64 bit linux, by default the
-# installation diectory is wrong for direct FB.
-# So, for 64-bit you MUST change the configuration for direct FB.
-if [ "$HOSTTYPE" = 'x86_64' ]
-  ./configure  --prefix=/usr  --libdir=/usr/lib64
-else
-  ./configure --prefix=/usr
-fi
-
-make
-
-su
-make install
-# control-D to leave su mode
-
-
-cd ..
-
-
-
-
-To modify the CORBA IDL file you must do some extra steps.
-A number of files are generated from the IDL file, and one of them
-(..-skelimpl.c) is also edited directly.  Before editing the nitpicker.idl
-file, run "make begin-idl".  Then edit the IDL file.  Once done, run
-"make end-idl".  There is currently no equivalent for nitevent.idl,
-though one could be created using the existing Makefile as a model.
-
-
--------------------------------------------------------------------------------
-
-                                   Xen Issues
--------------------------------------------------------------------------------
-
-It turns out that there are some tricks to posting command line kernal paramaters under xen.
-
-It turns out that the standard 
-
-title Fedora (2.6.23.15-137.fc8-fb)
-        root (hd0,0)
-        kernel /vmlinuz-2.6.23.15-137.fc8 ro root=/dev/VolGroup00/LogVol01 vesafb:ywrap,mtrr vga=0x312 rhgb quiet
-        initrd /initrd-2.6.23.15-137.fc8.img
-will not work unless you specify the vesafb in the right line for the boot so that you have to insert the information in the line labled kernel only.
-
-title Fedora (2.6.18.8-xen-fb)
-        root (hd0,0)
-        kernel /xen-3.2.gz console=vga vesa:ywrap,mtrr vga=ask
-        module /vmlinuz-2.6.18.8-xen ro root=/dev/VolGroup00/LogVol01 rhgb quiet
-        module /initrd-2.6.18.8-xen.img
-
-problem is setting the vga mode only works as ask.
-
-
-If you are installing the "tip" of Xen there are additional issues.
-First, BE SURE TO UN-INSTALL Xen.  Do:
-  rpm -qa | grep -i xen
-and be sure to "rpm -e" all xen files, and all that depend on them.
-Otherwise, the "wrong" files will get occasionally called, resulting in
-exceedingly hard-to-diagnose error messages.  One possibility is an exception that causes
-xend to fail to start, where the error message (in /var/log/xen/xend.log) is
-"Permission denied".
-
-After installation of the latest Xen, it may fail to boot, with the error that
-attempting to run initrd fails to find generic_ata. The (ugly) solution proposed by:
-http://www.nabble.com/Xen-3.2-is-not-loading-on-FC8---Error:-Kernel-panic---Attempted-to-kill-init-td15467372.html
-is to use the "wrong" driver - copy the "more recent" Linux kernel module ata_generic into the
-older Linux kernel's /lib/modules directory.  Do it this way:
-
-cd /lib/modules/2.6.23.1-42.fc8  # Or whatever your current Linux kernel is
-cp kernel/drivers/ata/ata_generic.ko ../2.6.18.8-xen/kernel/drivers/scsi/
-cd ../2.6.18.8-xen/
-echo "/lib/modules/2.6.18.8-xen/kernel/drivers/scsi/ata_generic.ko:" >> modules.dep
-
-# Then run:
-depmod 2.6.18.8-xen
-# and then the "mkinitrd" command per the Xen documentation.
-# Then install the new initrd:
-cp initrd-2.6.18.8-xen.img /boot/
-
-
-It may be that building/installing Xen can erase the "modules.dep" file of the
-non-Xen Linux kernel - creating a zero-length /lib/modules/*/modules.dep.
-If this happens, rebuild it this way:
- cd /lib/modules/2.6.23.1-42.fc8/  # Or whatever kernel version you need to fix
- depmod 2.6.23.1-42.fc8            # Be sure this is the correct version name
-
-The installed version of Xen's head probably won't auto-start xend or xendomains.
-As root, you can start them using the usual way to start services:
- /etc/init.d/xend start
- /etc/init.d/xendomains start
-
-
-
-To install the SCTP library (for 64-bit):
-tar xvzf sctplib-1.0.7.tar 
-cd sctplib-1.0.7
-./configure --prefix=/usr --libdir=/usr/lib64
-make
-su
-make install
-
-
-
-Temporarily, to shut down server:
-./sctplib-1.0.7/sctplib/programs/test_tool test_script_server_kill_ida
-(Remove _ida if not at IDA).
-Currently clients must have a different IP address than the server.
-
-
-Currently linpicker doesn't "clean up" after itself.  When it's asked to create a shared buffer with the VM, it does a block attachment... but once that's done, it's never released when the server ends or restarts.  You have to clean it up yourself, or it won't work.
-
-Change the '2' below to whatever the VM id is.
-
-To see if there's anything to clean up:
-# /usr/sbin/xm block-list 2
-
-If you see a block with id of 51700 or more at the end, then you have a more-recent allocation that needs cleaning up.
-
-You need to use block-detach to do the detaching; here's a way to do that in one line (replace both "2"s with the VM id):
-
-# /usr/sbin/xm block-detach 2 `/usr/sbin/xm block-list 2 | tail -1 | cut -f1 -d ' '`
-
-
-To debug X in Fedora, install the "debuginfo" packages. E.G.:
-yum --enablerepo=fedora-debuginfo,updates-debuginfo install xorg-x11-server-debuginfo
-yum --enablerepo=fedora-debuginfo,updates-debuginfo install glibc-debuginfo
-
+This is "Linpicker", a display server for the Xen virtualization environment.
+
+CONTENTS
+	Installation Instructions
+	Setting up the Environment and Guests
+	Running Linpicker
+	History of Linpicker
+
+
+INSTALLATION INSTRUCTIONS
+
+Requirements:
+* linux pvops dom0 or stub domain
+* libxenlight, libxenstore, libxenctrl, etc. (Xen 4.0+ recommended).
+* directfb 1.4.2 or greater
+* libudev 145 or greater
+* libxcb
+
+The standard ./configure; make should work to build Linpicker; refer to INSTALL
+for the stock instructions.  Linpicker additionally supports the following
+configure options:
+
+--enable-loglevel=n (default: 0)
+	Sets the log level for messages (from 0 to 3).  Setting it to 2 will
+	log useful events such as XenStore state changes, framebuffer mapping
+	information, etc.  Setting it to 3 will also log individual update
+	events which will likely flood the log.
+
+--enable-socket (default: n)
+	Causes linpicker_server to listen on a local socket and enables
+	compilation of linpicker_cli which can be used to send commands to
+	linpicker_server.  Currently there is only one command which causes
+	linpicker_server to dump information about all views into the log.
+
+
+SETTING UP THE ENVIRONMENT AND GUESTS
+
+Linpicker is based on DirectFB which works by opening /dev/fb0 and directly
+writing the framebuffer.  Thus, your dom0 (or whatever domain will be used to
+run Linpicker) needs to be booted in graphical mode so that /dev/fb0 exists.
+
+Add the following to your grub.conf: vga=gfx-1600x900x32
+Substitute 1600x900 with whatever resolution you want to use.  vga=ask can
+be used to get a boot menu to choose a resolution.
+
+Note that DirectFB (and hence Linpicker) doesn't support VT-switching
+at the moment, meaning you need to exit the server in order to switch to X
+or another VT or whatever.  Fixing this is on the TODO list.  However, this
+does allow the Ctrl+Alt+Fn combo to work for switching VT's inside the guests,
+which is a plus.
+
+As for guests, anything that supports the Xen framebuffer and input frontends
+should work fine out of the box.  This includes all recent Linuxes.  The
+Linux framebuffer frontend driver should read XenStore to determine the
+correct resolution to run in, however if you wish to specify a resolution
+manually, this can be done by adding the following to the guest boot line:
+xen_fbfront.video=4,800,600 where the first number is the amount of RAM in MiB
+to allocate (which needs to be large enough for a 32bpp framebuffer of the
+specified resolution) and the second and third numbers are the resolution.
+
+For MS Windows guests, framebuffer and input frontend drivers do exist, but
+this package does not currently include any as the ones used by the author are
+still under development.
+
+To use the "combined desktop" mode in which windows from multiple guests are
+combined, the "linpicker_track" program needs to be installed in each guest
+and run as part of the guest X session; see below.
+
+RUNNING LINPICKER
+
+Linpicker consists of three parts, linpicker_monitor, linpicker_server, and
+the optional linpicker_track.
+
+linpicker_monitor is a non-graphical program that waits for new guests to
+start and sets up the backend information in XenStore.  This program needs to
+be started before any guests that are intended to be used with Linpicker.
+
+linpicker_server is the actual display server that maps the guest framebuffers
+and provides the user interface.  It can also detect new guests starting up,
+but it does not write XenStore at all, it just listens passively.
+
+Both programs have no command line arguments.  They will create log files in
+/var/log/xen and send all messages there.  Both programs need to run as root.
+This is for two reasons, 1) /dev/fb0 typically needs root permission to open,
+and more importantly, 2) most of the Xen operations such as mapping grant
+references, touching XenStore, etc. require root.  Moving to a model in which
+linpicker_monitor handles _all_ Xen operations should allow linpicker_server
+to be unprivileged; this is on the TODO list.
+
+The typical way to run Linpicker is to run linpicker_monitor at boot time
+(before xendomains) and then run linpicker_server from the command line.
+To get back to the command line once linpicker_server is run one can either
+ssh from one of the guests, or exit linpicker_server and then re-run it.
+
+linpicker_track provides the extra information needed to use the combined
+desktop mode with X-Windows guests.  It needs to be run as part of the guest
+X session, unfortunately, in order to communicate using Xen primitives it
+needs to be run as root!  This could be done using setuid or sudo.  It works
+by passively tracking window position and location and forwarding this
+information to linpicker_server using a ring buffer.
+
+
+HISTORY OF LINPICKER
+
+Linpicker is based on the Nitpicker project developed at the University of
+Dresden for the L4 microkernel.  Many of the same concepts present in
+Nitpicker are present in Linpicker, in particular the track program and the
+ideas of buffer and view.  However, the code has been completely rewritten
+to work natively on Linux and Xen.
+
+Nitpicker's original implementation was deeply married to L4.  The initial
+port of Nitpicker to Linux was made by an IDA team led by David A. Wheeler
+with Phil Dollery supervising.  The name "Linpicker" was devised by Phil
+Dollery; David A. Wheeler confirmed on Apr 20, 2007 that Google found no hits
+for the name.  This initial port used a shared RAM disk to host the guest
+framebuffers and SCTP networking to send update and input events back and
+forth.  It relied on X drivers to serve as framebuffer and input frontends.
+
+This initial port was completely rewritten by Eamon Walsh and Daniel De Graaf
+to support native Xen framebuffer and input frontends.  The backend code was
+borrowed from QEMU, and a simple, ring-buffer based inter-domain communications
+library called vchan was developed using code borrowed from Qubes-OS, however
+this code was rewritten to use the gntalloc and gntdev devices instead of
+relying on a "MFN-to-PFN" kernel driver and map_foreign_range().