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().