path: root/README

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 re-implements Nitpicker, but with the KISS notion.
SIMPLICITY is the goal here, with small amounts of code.

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.

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.

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