0. WARNING

THIS IS BETA CODE!  It might work for you, it might not work for you,
it might cause Squeak to crash, it might put your machine into a state
where the keyboard and screen become *unusable*.


1. INTRO

This is a driver for Squeak running on the Linux framebuffer.
Graphics are displayed directly in the video memory, keyboard input is
taken from the console, and mouse input from the raw mouse device.


2. HARDWARE REQUIREMENTS

You will need a graphics card that provides a framebuffer interface
(which is by no means all of them).  If you see a penguin logo while
Linux is booting, or if your console font suddenly changes during
boot, then you have a framebuffer device.

Otherwise, check for one by running

	/usr/sbin/fbset

and if it says "/dev/fb0: no such device" then you don't have a
framebuffer device.  (This program can be used to set the framebuffer
depth before running Squeak.)

Otherwise there might be a module you can load: look in
/lib/modules/X.Y.Z/kernel/drivers/video for a file called "cardfb.o",
where "card" is the name of your graphics card.  If you find one, load
it (as root) like this:

	modprobe cardfb

The following configurations are known to work at all screen depths:

	arch	kernel	graphics card		os driver
	----	------	-------------		---------
	PowerPC	2.4.20	ATI Radeon 9000 (M9)	radeonfb.o
	PowerPC	2.2.18	PowerMac Valkyrie	valkyriefb.o
	386	2.4.18	NeoMagic 256AV		neofb.o


3. SYSTEM REQUIREMENTS

To use this driver you must be logged in on the console with no window
system running.

You MUST have WRITE PERMISSION for the following devices:

  - the console
	this is either /dev/console or /dev/tty0 or the device
	reported by running the program "tty"

  - the framebuffer
	this is usually /dev/fb0

  - the mouse
	this is either /dev/psaux (if you have a real PS/2 mouse) or
	/dev/input/mice (which emulates PS/2 when you have some other
	kind of mouse)

In case of difficulty, the following might help:

	chmod a+rw /dev/tty* /dev/fb* /dev/psaux /dev/input/mice

although this will somewhat compromise the security of your machine.

Depending on your system you might also have to have ownership of the
above devices.  In extreme cases you might even have to run Squeak as
root to use this driver.


4. INVOCATION

You need to tell Squeak explicitly that you want to use the
framebuffer.  Either run Squeak with the '-vm-display-fbdev' option:

	squeak -vm-display-fbdev your.image

or set the variable SQUEAK_VM in your environment:

	export SQUEAK_VM=display-fbdev


5. RECOVERY

If the VM becomes unresponsive for any reason you will have no option
other than to log into your machine remotely and kill the VM.  If you
do this (or if the VM crashes) you will likely be left with the
keyboard and screen in an unusable state.  To recover from this, log
into the machine remotely and run

	kbd_mode -a

to restore the keyboard.  The screen is a little trickier; the most
reliable way to put it back into a sane state is to start the X server

	/usr/X11R6/bin/X :0

and then quit it by pressing Ctrl+Alt+Backspace.


6. MISSING

There is no rule number six.


7. LIABILITY

If this driver breaks your machine, you get to keep all the pieces.


8. CONTACTS

Please report bugs (and success stories) by email to: ian.piumarta@inria.fr

Thanks!
