Intel 810 Framebuffer driver
 	Tony Daplas <adaplas@pol.net>
	July 2001
================================================================

CHANGES v0.0.6
	- added hardware panning.  This really speeds up text scrolling. 
	  Try 'time cat textfile' and see the changes.  The speed increase
	  will only work if you have a virtual vertical resolution greater 
	  than the actual vertical resolution.  You can use fbset to change the 
	  virtual resolution, or use the kernel/module option (vyres)
	- a few more rewrites in the acceleration code, hopefully to improve 
	  performance
        - bug fix:  crashes the machine if more than 4 MB of RAM is
	  allocated for the framebuffer - fixed
	- buf unfix:  Unfortunately, the green cursor is not yet fixed :(. 
	  It appears only at 8 bpp and during the first power-up.  Launching X 
	  restores the color to normal.  X must be doing something I don't
	  know about :)

CHANGES v0.0.5
	- added compile-time options to either use standard or nonstandard
	  video timings.  The default is to use the documented and required
	  video timings according to the i810 documentation.
	- a few code clean-ups and fixes

CHANGES v0.0.4
	- added support for 24bpp with accelerated and non-accelerated modes
	- acceleration code rewrites to reduce code size
	- bug fix:  hardware cursor stops blinking when X in framebuffer
          mode is used
	- increased verbosity (just a bit) of kernel messages

CHANGES v0.0.3
	- color map fixes, now the penguin logo and the 8bpp cursor is
          properly colorized
	- bug fix:  vt switching between X and console crashes the machine
          when hardware cursor is disabled
	- bug fix:  Config.in in was fixed so tkparsing works during make
          xconfig.  Consequently, module dependencies are also fixed :)

CHANGES v0.0.2
	- added hardware cursor support
	- added kernel-doc compatible source code comments
	- development stopped for kernel 2.2.19	

CHANGES from Sept 21, 2001:
	- a lot of fixes to provide stability and usability
		* can load and unload agpgart without crashing the machine
		* more stable concurrent X and framebuffer use
	- Config.in changes to disallow static compilation of agpgart; this
	  is necessary for the stability of the driver
	- driver is stable enough to give it a version number 0.0.1

CHANGES from Sept 18, 2001:

	- fixed display corruption upon invocation of the driver
	- added parameters for module loading
	- can support X in framebuffer and native mode

TODO:
	- incorporate modedb support
	- video overlay support (?)
	- code cleanup

1. Introduction
	This is a framebuffer driver for various Intel 810 compatible
graphics devices.  These would include:

	Intel 810
	Intel 810E
	Intel 810-DC100

	This code used vfb.c by Geert Uytterhoeven as its framework. Various
codes from agpgart_be.c and Xfree86 v4.0.3 where also partly implemented.

2.  Features

	- Supports a range of horizontal resolutions from 640 to 1600 in multiples of 8
	- Supports bits per pixel values of 2, 4, 8 and 16
	- Supports  accelerated and unaccelerated modes 
	- Supports mtrr
	- Utilizes monitor specifications to automatically compute modelines 
	- Independent agp code (linking to agpgart is not necessary)
	- Can coexist with xfree86 running with native i810 drivers under certain
precautions
	- hardware cursor support new in version 0.0.2

3.  Kernel parameters 
	
	"video=i810fb" - enables the i810 driver

	"xres=<value>" - horizontal resolution pixels (default = 640)

	"yres=<value>" - totally unused; computed as 3*xres/4 
	"vyres=<value>" - virtual vertical resolution in scanlines (default
= 480)

	"vram=<value>" - amount of system RAM in MB to allocate for the device
(default = 4)

	"bpp=<value>" - bits per pixel (default = 8)

	"hsync1/hsync2=<value>" - the minimum and maximum Horizontal Sync
Frequency of the monitor KHz (default = 31).  hsync1 must be equal to hsync2
if a fixed frequency monitor is to be used.

	"vsync1/vsync2=<value>" -  the minimum and maximum Vertical Sync
Frequency of the monitor in Hz (default = 50/60).

	"rr=<value>" - vertical refresh rate to be used.  Whether the value
is going to be used will depend on the monitor specifications.  Default =
not set)
	"accel" - use acceleration (default = not set)
	"mtrr" - use mtrr (default = not set)
	"xcon=<value>" - assignes the virtual terminal X will use.  The
value is zero-based, so tty7 is 6.  (default = 6)
	"hwcur" - enable hardware cursor (default = not set)
##############
Sample Usage
##############

In /etc/lilo.conf, add the line:

append="video=i810fb:vram=2:xres=1024:bpp=16:hsync1=30:hsync2=55:vsync1=50:vsync2=85:accel:mtrr"

This will initialize the framebuffer to 1024x768 @ 16bpp.  The framebuffer
will use 2 MB of System RAM. MTRR support is enabled. The refresh rate will
be computed based on the hsync1/hsync2 and vsync1/vsync2 values.

3.  Module options
	
	The module parameters are essentially similar to kernel parameters,
except for mtrr and accel.  mtrr, accel, and hwcur should be boolean, ie. mtrr=1.

##############
Sample Usage
#############
Using the same setup as described above, load the module like this:

	modprobe i810fb vram=2 xres=1024 bpp=16 hsync1=30 hsync2=55 vsync1=50 vsync2=85 accel=1 mtrr=1

Or just add the following to /etc/modules.conf

	options i810fb vram=2 xres=1024 bpp=16 hsync1=30 hsync2=55 vsync1=50 vsync2=85 accel=1 mtrr=1

and just do a 

	modprobe i810fb


4.  Notes on using the driver with X

	If X is to use the framebuffer device, compatibility problems will
be pretty much avoided.  The problem is using X with its native driver.  The
xfree86 i810 driver uses the agpgart module to write to the graphics device. 
To avoid most conflicts, the framebuffer device utilizes its own agp
allocation routines which makes it independent from the agpgart module.  However,
there are still a few resource sharing that cannot be avoided.

	The pagetable register is an i810 register that contains a pointer
to the graphics translation table (GTT). This register is needed by agpgart
and by the framebuffer driver and because of the sharing, conflicts cannot
be avoided. The solution (hack?) is to have the framebuffer restore the
value of the register when it's going in and going out of context. 

	The same can be said of the ringbuffer register.  However this can
be completely avoided if unaccelerated mode is chosen.

	So a few precautions when using X and the framebuffer concurrently.
	
	- Make sure that the i810 framebuffer driver is loaded before
agpgart (Note:  this has been fixed in the latest version)

	- It's preferrable if agpgart is loaded autmoatically (using
automatic kernel loading).  If this cannot be avoided, manually loading
agpgart (using insmod or modprobe) will produce an initial screen corruption
but should be corrected by switching to another console and back again.
(Note:  this has been fixed in the latest version)

	- NEVER unload agpgart once it's loaded or your system will crash. 
Let it stay permanently in memory. (Note:  this has been fixed in the latest
version)

	- Using the safest setting (no acceleration, no mtrr) will improve
comptibility a lot

	- Do not change X drivers in one session.  A reboot of the system is
needed if X drivers are to be changed. (Note:  this has been fixed in the
latest version.  Some precautions are still needed however, see below)
	
	- If X is to be used using the framebuffer driver, then agpgart must
be unloaded from memory.  It will not crash the machine, but will produce a
corrupt X display.  To fix, just exit X, unload agpgart, and start X again.

	- If the agpgart module is loaded or unloaded manually while in the
framebuffer console, the display will become corrupt.  Just switch
terminals, and the display will be restored.
    
	- If mtrr is going to be enabled, then X would not be able to use
mtrr.  This is so because mtrr will not create overlapping mtrr's if the
first mtrr is created as 'write-combining'.  So, disable mtrr if you're
going to use X with its native drivers.

5.  Bugs

	- At initial load of the framebuffer, the screen will be corrupt. 
Actually, the screen will contain a block of foreground color (white) but
disappears completely after switching VT's.  A very annoying bug which I
can't find a solution.  I believe it's due to one of the function that's
called by register_framebuffer.  This is probably update_screen called from
take_over_console. (NOTE:  This has been fixed).

	- a pixellated penguin logo at 8bpp (NOTE: This has been fixed)

	- wrong penguin logo colors (endian problems?) (NOTE: This has been
fixed)

	- a green cursor at 8bpp (I'm too lazy to correct it at the moment
:) (NOTE: This has been fixed)

	- very limited bounds checking

	- frequent crashes when switching between X and console. (Note:
more stable with the most recent version)

	- Some nonstandard modes (like 936x702) may display incorrectly.
Expect pincushioning, shifted display frames, artifacts, or no display at
all.

	- And a host of others that I won't mention
	
	If you do find problems, please let me know at adaplas@pol.net.

5.  Acknowledgment:
	
	1.  Geert Uytterhoeven - his excellent howto and the virtual
framebuffer driver code makes this possible.

	2.  Jeff Hartmann for his agpgart code.  

	3.  The X developers.  Providing X with a means for a save and
restore greatly decreased the difficulty in coding.

	4.  Intel.  For this low-value driver and for providing
documentation.  


###########################
Tony

