I855CRT driver V 0.4 - Intel Montara 855GM CRT out auxiliary driver

Copyright (c) Merello Andrea 2004
Some parts of this driver are taken/based on 'i810switch' driver
Some parts of this driver are taken/based on the 855GM fb driver
Some parts of this driver are based on 'xvattr'

Released under the terms of GPL (general public licence)

##IF YOU TRY THIS DRIVER *PLEASE* LET ME KNOW IF IT WORKS OR DOENSN'T WORK FOR YOU, THANKS!##

DRIVER OVERVIEW

This is a little userspace driver that should enable CRT out on intel 855GM/GME based laptop.
At the moment XFree 4.4.0 (and maybe 4.3.0 and others) includes an opensource driver for this video card,
but it doesn't provide any way to manage crt out.
Some other auxiliary driver has been written with the purpose to do that, but none of them worked for me, 
or worked as i expected.
In particular the 'i810switch' driver can enable CRT out but with some limitation.
The main difference between this driver and the i810switch is that the latter simply enables
the DAC and connect it to the same pipe used by the primary video out, while this driver uses two
different pipes, one connected to the LVDS (internal LCD port) and one for the CRT DAC.

-This has some advantages..

1) Connecting the DAC to the same pipe of witch the LVDS is connected (always the pipe B in i855) can cause some
image corruption. In my case it was dirty and unstable. Using two pipes should solve this issue.
2) Using two pipe allow to use different refresh rates for the CRT and the LVDS ports.

-And some drawbacks..

1) Using two pipes implies using two planes, one for each pipe, where render the image.
This not cause any performance loss since we can map both the planes on the same framebuffer,
however, according to the intel datasheet, it isn't possible to have video overlay on both pipes (at least
without SW tricks).
This actually means that you can view your preferred X, gtk or qt program on both LCD and CRT at the same
time without any problem, but if you want to see a DVD-player or similar program (that uses video overlay) 
on both CRT and LCD at the same time you have to do a SW copy of the overlay plane. This can cause performance issues. 

2) by default in the i810 XFree driver HW mouse cursor is enabled. If you want to use HW cursor you need to apply 
xf86-4.4.0-patch to such driver. (see next chapter). Patching is also required to use overlay routing.

Note that this driver has been tested only on XFree 4.4.0 and intel Montara 855GM/GME on kernel 2.6.4 with
vesafb. In particular a framebuffer driver for 855GM-like exist in kernel 2.4 series, but since it isn't 
available in 2.6 kernels i have had no way to try if it can co-exist with this driver.


HW CURSOR AND XFree PATCH

If you wants to use hardware mouse cursor support you have to patch the i810 X driver.
To do this you need the source tree for XFree 4.4.0 (the patch may work for other version of X, but it's untested).
Place the xf86-4.4.0-patch file in your xc/programs/Xserver/hw/xfree86/drivers/i810 where xc is your X source tree root.
cd in such directory and run 'patch -p1 <xf86-4.4.0-patch'.When the system ask wich file to patch write 'i830_cursor.c'.
Now make X and install it.
If you want to install only the driver you can copy xc/programs/Xserver/hw/xfree86/drivers/i810/i810_drv.o in
/usr/X11/lib/modules/driver, however you haven't a valid makefile if you don't run the X main make so you can't built it.
For this reason a sample makefile is provided and named Makefile.i810.

if you wants to use software cursor you don't need to patch anything.
Just edit your X config file (usually /etc/X11/XF86-Config or XF86Config-4) and add the line 'Option "SWCursor" "1"'
in the section 'driver' near the line 'Driver "i810"'

OVERLAY and XVideo
Xv (or XVideo) is an X extension that is used by all most common players (as well as TV watching program, etc.) to
draw directly on a buffer that will be remapped inside a window.
Intel wrote a module, included in i810, to implement Xv in an hardware assisted manner, through the use of overlay
planes. Now i855crt contains a patch for such module that allow an usersapece program (included, but not limited to,
i855crt itself) to route overlay planes on pipe A or B. This means that you can decide to see Xvideo on your LCD or
your CRT (but not both at the same time, as explained above).
The patch adds an Xv attribute (named XV_PIPE) that can assume values 1 or 0 respectively for pipe B or A.
i855crt, by defaults, route overlay on pipe B (on LCD), you can route overlay on pipe A by running i855crt with
the 'overlaycrt' extra param.
It's also possible to use other utilities to manage Xv attributes, like 'xvattr', and there is the possibility
that your video player can do this also by itself.
To apply the patch read the instruction above about patching the hardware cursor code.
For video overlay the patch name is 'xf86-4.4.0-overlay-patch' and the file to patch is i830_video.c


INTERNAL DETAILS

I855 chipset provides some video out ports:
-a LVDS port, used to drive the local LCD panel
-an Analogic port, connected to an internal DAC, and used to drive external monitor
-two or three DVO ports, used to drive tv-encoders or other digital stuff

Each of these video ports has to be connected to a renderig pipe.
i855 has two rendering pipe.
LVDS must be connected with pipe B.
DVOx and CRT can be connected either with pipe A or B 
According to the intel datasheet is feasible to connect both the LVDS and the CRT to pipe B, and
this is actually what do the 'i810switch' driver.
However the same pipe / PLL settings has to be used for both CRT and LVDS.
This driver tries to improve image quality by using both pipes: the pipe A for CRT, and pipe B for 
LVDS.
Enabling and configuring the DAC and connecting it to PIPE A is not sufficient to see something on the monitor.
We have at least to configure the PIPE and the PLL for this pipe and to provide some image planes that renders 
on such pipe.
By default X driver uses PLANE B, OVERLAY PLANE and HW CURSOR PLANE A, and associates them with the PIPE B.
I855CRT driver enables a fourth plane (the plane A), remap it at the same base address of the plane B, clone some
parameters form the plane B (such as source resolution) and associates it with PIPE A/PLL A.
This is sufficient to have basic 'screen clone' image on both display with separate sync.
To support HW cursor we need also to enable CURSOR PLANE B.Ill-fatedly, as far as I know, it isn't possible to remap 
the CURSOR PLANE B on the CURSOR PLANE A as done with PLANE B and A. For such reason you need to apply a little
patch to the original i810 XFree driver.
The overlay plane can be rendered on PIPE A or B alternatively. In future release a SW copy from the overlay panel to PLANE C may be implemented, but this isn't really fast..
According to the intel datasheet this is the only way to render overlay plane on both pipes.

USAGE
To compile the driver simply cd to the driver source directory and run 'make' without quoting it

To activete the driver simply run, as root

'i855crt [swcursor] [overlaycrt] on <Mode-name>' 
	to enable crt binding it on a separate pipe (pipe A). 

	Mode-name are the same in the config file. Most common modes are already included and custom modelines can
	be added. for example 1024x768@85 is a valid modename

	The flag 'swcursor' is needed (or may be needed) if you want to use your X driver
	without HW cursor support. In such case patching it isn't needed.

	The flag 'overlaycrt' tells i855crto to route Overlay/XVideo on CRT instead of LCD. 
	This allows to view movies&co on CRT 

'i855crt on rawpipe' 
	to enable crt and bind DAC on the same pipe of the LVDS (read above) NOTICE THAT THIS 
	DOES EXACTLY THE SAME AS i810switch and vanify any attempt of this driver to improve video quality. 
	This shouldn't be used without a good reason.

'i855crt off' 
	to disable crt

Example: to set your CRT at 1024x768 at 85Hz with HW cursor 
./i855crt on 1024x768@85

Example: to set your CRT at 1024x768 at 85Hz with SW cursor and routing XVideo on CRT
./i855crt swcursor overlaycrt on 1024x768@85

Example: to switch off oyur crt
./i855crt off

*NOTE*: if you are NOT using X you may have to specify swcursor mode (for example you need it with vesafb).

**IMPORTANT NOTE**: This driver assumes that you have your LCD enabled, if your bios has disabled LVDS and enabled 
CRT by itself you probably need to reboot, since this driver most probably will make black both !

DUMPING UTILITY
In this version I have included a small utility that dumps all the memory mapped register on standard
output.
To complile it run 'gcc -o dumpreg dumpreg.c' without quoting it
Then you can run './dumpreg > log' and have full memory dump on file 'log'.
This may be useful if you have trouble and want to report me useful info.

VFAQ (Virtually frequently ansked question)

-What are modelines and mode-name
Modelines= entry in the configuration file that associates a name for a particular video mode(the mode-name) with 
the video settings that the video card/nonitor need to provides such mode.
For example 1024x768@85 is the modename for 1024x768 pixel resolution at 85 hertz.

-This driver don't work, make the system hang or made my monitor explode.
This is still *very* experimental.
Since i haven't programming specifications for the i855GM i had to guess how some registers work and how to
program them. Naturally some could be programmed in a wrong manner that affect some hw configuration or broke
things in some circumstances.

-Does this driver work with some other intel video chipset?
This may or may not work on i830-like mobile video chipset and may have some chance to work also with i810-like chip,
but I really don't know at all..
If you decide to try this driver plase let me know if it works.

-When i switch resolution in X the image on CRT get corrupted.
Since this driver is not integrated in X, it has no way to know that resolution has changed.
So you have to run again the driver to restore the CRT. Maybe this can be solved with a X driver patch in some
future release

-I see only noise or non-synced images on the CRT or i see a warning message 'out of range' or something like.
Most probably your monitor don't support resolution/vsync you are using.
Try to start X in a lower resolution or modify the mode driver parameter

-I see nothing on the CRT
There are two possibility:
1) As above the monitor can't get synced and shuts down
2) The driver failed to enable the DAC or to set up the pipe or the planes.
Try to understand what is happened by observing if your monitor led is blinking or it showing green or orange 
or something like. If you think it's the second option that make the CRT staying off please let me know.

-Is it a driver or an userspace program?
An userspace program that act as a driver by mapping /dev/mem and accessing directly the hw registers.
Note that you have to run it as root.

-Is a datasheet available for 855GM-like chipset?
Intel provides a datasheet for 855GM & co but it isn't complete.
Register explanation and programming tecniques are contained in the PRM (programming reference manual)
that, as far as I know, is not available.
PRM is downlodable for i810chip series.

-Does this driver work also for the TV-Out
No. It isn't sufficient to enable the correct out-port in the video chip (usually DVOA or DVOB or DVOC) to 
see something on the tv.
Programming the TV-encoder is also necessary.
I plan to make this driver capable to enable DVOx and some work has been already done for the most common 
TV-Encoder (NvTv for example supports some chrontel, philips, booktree and conexant encoder and should work 
also on some intel chip, but it doesn't work for me). 
So it is *theorically* possible, in future releases, to make this driver capable to enable some laptop TV-out 
by enabling DVOx and merging with nvtv encoder-driver code. 

-Why i see desktop and some programs on both LCD and CRT but DIVX or DVD shows correctly only on the LCD?
Because your DIVX/DVD-player uses Xv/video overlay planes.
It is possible to bind alternatively the overlay with the CRT or the LCD, but not with both at the same time.
This version of i855crt includes initial&experimental support to route Xv to pipe A or B. Read the relative
section for details.

-I can't see the mouse cursor on the CRT or the cursor don't move
you need to apply a patch to the i810 XFree driver (see relative chapter).
If you don't want to patch the driver you still can have cursor working by disabling HW cursor in i810
X driver (see man i810).
Note that you have to tell i855crt that you want to use SW cursor.
This is done by prefixing 'swcursor' as first input parameter.

-Is it possible to connect CRT to pipe B (as in rawpipe mode) and disabling the LCD to have overlay and cursor
without any workaround and to get better image quality on the crt?
Maybe it is possible. Most probalby it is possible at least to disable the LVDS to have a non-disturbed image.
I suppose that it is possible to change the refresh rate also, however i couldn't figure how to disable LVDS.
The LVDS register and DVOx register seems to have no effect. Most probably some registers described in the i815 RPM 
aren't still supported in 855GM or they work in some very different manner.
I know that i810 driver invokes bios routines to provide a limited/basics management of LCD but:
- I'm not sure if this can be used to explicity turn on/off the LCD, whitout let bios decide what devices
  are attached and what should be enabled
-Calling bios trap from protected mode is not trivial.. XFree contains a x86 emulator to do this...
So, since i have no detailed documentation about the LVDS registers, for now, no chance to do this vith i855crt, sorry.

-The image is ok except for a little rectangle somewhere in the screen.
This may happen if you not specify the swcursor flag and your XFree or framebuffer driver isn't using hardware 
mouse cursor mode.

-I have read all the VFAQ above but i still have problems with mouse cursor.
Try to use version 0.2 of the driver: cursor code has been partially rewritten
and there is the possibility that doing this I've introduced new bugs.
If V 0.2 works for you but you have problems with successive versions *PLEASE* send me
a mail at <andreamrl@tiscali.it>
