
                          clgen v1.3 (12-Jan-98)
                  A generic driver for Cirrus Logic based
               graphic boards for the Amiga under Linux/m68k

                  Copyright (c) 1997,1998 by Frank Neumann

------------------------------------------------------------------------

This document describes installation and usage of the framebuffer device
driver for Cirrus Logic based graphic boards for the Amiga under Linux/m68k.

IT IS IMPORTANT THAT YOU READ ALL OF THIS BEFORE EVEN ATTEMPTING TO USE
THE DRIVER! DON'T EXPECT X11 TO WORK AS ON INTEL LINUX BOXES!

0) Changes since v1.2
   - some bugfixes
   - now accepts monitorcap: and mode: on command line

   Changes since v1.0
   - text consoles on your graphic board! Just start the kernel with
     amiboot [..] video=clgen
   - For 8 bpp (standard case), console scrolling&filling is accelerated
   - Picasso IV support
   - no more need to use the "tog" tool
   - correct standard VGA color palette
   - uses the FB_ACTIVATE_* flags correctly now
   - correct behaviour when used with fbset

   Important! The driver now sits in fb0*, so you can remove the old fb1*
   entries from /dev. Though, you'll either have to rename your fb0*
   entries to more meaningful names ("fb0pal" is a bit irritating for
   1024x768 :-), or create additional symlinks with meaningful names;
   see below in "Creating /dev entries".


1) Supported hardware
---------------------

This driver supports the following graphic boards:
- Piccolo SD64 (Ingenieurbuero Helfrich)
- Piccolo      (Ingenieurbuero Helfrich)
- EGS Spectrum (GVP)
- Picasso II   (Villagetronic)
- Picasso IV   (Villagetronic)

The Picasso II is only supported in linear (non-segmented) mode. Please
make sure that the switch on the rear of the board is set to linear mode.

All other boards only do linear mode, and should thus work out of the box.
It shouldn't matter whether you use them in Z2 or Z3 mode; the only
difference probably being that throughput into the Z2 area is not as fast as
into Z3 memory.


2) Features
-----------

- Variable resolutions: The user can create his own resolutions if he knows
  what he is doing. The driver comes with some pre-generated resolutions, 
  though:
  640x480, 31.25 kHz, 60 Hz, 25 MHz PixClock (startup mode)
  800x600, 48 kHz, 72 Hz, 50 MHz PixClock
  1024x768, 55.8 kHz, 70 Hz, 80 MHz PixClock
  320x200, 31.4 kHz, 70 Hz, 25 MHz PixClock (Super-LoRes ;-)
  1024x768i (interlaced), 31.5 kHz, 77 Hz, 44.9 MHz PixClock
  1024x768hi (interlaced), 46.5 kHz, 113 Hz, 66.2 MHz PixClock
  1280x1024i (interlaced), 51 kHz, 87 Hz, 80 MHz PixClock

  Interlaced modes should not exceed 1024 lines; this is a "Todo" item.

- Color depth: Right now, only 1 bit (monochrome) and 8 bit PseudoColor
  (256 colors, using a LookUp table) are supported. There is already
  code for 16 bit HiColor and 24/32 bit TrueColor in the driver, but it is
  still disabled because the XF68_FBDev Xserver doesn't yet support these 
  modes correctly.

- Virtual screens: Supports "AutoScroll" resolutions larger than the visible
  screen area, e.g. when used with the Xserver. For example, on a 4 MB
  SD64 board using 8 bits per pixel, you can create a workspace as large
  as 2048x2048 pixels. Moving the cursor towards one of the screen borders
  will scroll the display in that direction.
  Please note that in monochrome modes you can only use 1/4 of the display 
  memory due to hardware limitations; for that reason, on a 4 MB board
  the maximum virtual resolution in monochrome is also limited to
  2048x2048 pixels.

- DoubleScan mode: For extra LowRes modes, the driver uses the "doublescan"
  feature of the vga controller which outputs every scanline twice. The
  supplied 320x200 mode uses this. Amaze your friends with a game like
  Thrust filling the entire screen! :-)
  Please note that this mode is not yet available with fbset, as it misses
  a little option I have to add. It's still in the kernel, though.

- Supports multiple boards in one computer: While probably not many users
  will ever need this feature, I found it very helpful while developing. :-)
  At startup, the driver looks for all boards it supports, and initializes
  and registers each of them.
  TODO: This does currently NOT work (v1.2) due to the number of changes
  I had to put in for console support.

- Should correctly determine the amount of DRAM available on the board
  (please mail me if this does not work on your board!)

- Allows to set the maximum vertical/horizontal frequencies with regard to
  the connected monitor. This is done either at the amiboot command line
  (recommended) or via a little program "freq" (see below).

- Allows larger consoles than the default right at kernel startup time;
  no PC-ish hassle with something like svgatextmode!

3) Installing the driver
------------------------
If you received this text file together with a precompiled kernel 
containing the clgen driver, you are ready to go; you can then safely
skip this section and go to the next, "Creating /dev entries".

Otherwise, you will have to compile a kernel of your own. This, of course,
requires a working Linux system complete with gcc, binutils and everything
else that is needed to compile&link a kernel.

You will now have to apply the clgen source patch to the kernel source tree.
The file containing the patch is named "clgen_diffs" and should be in the
archive you unpacked. However, it might also already have been applied
to the kernel source tree; if that is so, I forgot to update this text
file in time; in that case bug me to update it. :-)
I used a 2.0.33 kernel source tree. Adapting the driver for 2.1.xx kernels
will be the next thing to do. Please be patient.

Applying source patches should be something you know about; in a nutshell:
(cd /usr/src/linux; patch -p0 -s < "path_to_clgen_diffs" )

After that, copy the driver main files (clgen.c and clgen.h) to their
destination in "arch/m68k/amiga/" in the kernel source tree.

Next, start the configuration with 
# make config

When asked for the CLGEN driver, answer with "y":
[..]
Amiga Cirrus Logic boards support (CONFIG_FB_CLGEN) [Y/n]: y

After this you can do the usual
# make clean; make dep; make

and have one or maybe even LOTS of cups of coffee while you wait for the
compiler to finish. You should end up with a "vmlinux" kernel binary in
/usr/src/linux containing the clgen driver. Copy it to the usual location
where you keep kernel images on the AmigaOS side.


4) Creating /dev entries
------------------------

To allow any application program to communicate with the (kernel-based) 
driver (I write "any", although the mostly used application is going to
be the Xserver of the X Window System), you now have to create some entries 
in /dev. Usually, you already have a couple of fb0* nodes in there which 
are associated with the built-in video hardware of the Amiga (OCS, ECS or 
AGA).

Now, when starting the kernel with the console on the graphic board, the
fb0 framebuffer device is not used by the Amiga's video chipset (OCS/ECS/AGA),
but by the graphic board. This means you still use the fb0* entries in
/dev, but the video modes "behind" the names have changed (they are now
the predefined modes in the clgen driver). 

You could now either remove the old fb0* devices and create new ones with
the same major/minor device number, but with more meaningful names, or
(what I recommend) keep the old ones and create the new, meaningful names
as symlinks pointing to the old ones.

Here is what I suggest; these are sort-of telling names that correspond to 
the modes that come with the driver.

First, log in as root, go to /dev, check that there are already the
"typical" fb0 devices for Amiga; the following should exist:

crw-rw-rw-   1 root     root      29,   0 Aug  5  1996 fb0current
crw-rw-rw-   1 root     root      29,   1 Oct  1  1996 fb0autodetect
crw-rw-rw-   1 root     root      29,   2 Oct 21 20:11 fb0ntsc
crw-rw-rw-   1 root     root      29,   3 Oct 21 20:11 fb0ntsc-lace
crw-rw-rw-   1 root     root      29,   4 Oct 21 17:34 fb0pal
crw-rw-rw-   1 root     root      29,   5 Dec 31  1996 fb0pal-lace
crw-rw-rw-   1 root     root      29,   6 Dec  5  1996 fb0multiscan
crw-rw-rw-   1 root     root      29,   7 Dec  5  1996 fb0multiscan-lace
crw-rw-rw-   1 root     root      29,   8 Oct 21 17:34 fb0a2024-10

If they don't exist, get the fbset program source, compile and install
it; it contains a target in the Makefile to create those (and more) device
nodes for you.

Now, create the clgen device nodes as symlinks pointing to the old devices:
# ln -s fb0ntsc fb0cl-low
# ln -s fb0ntsc-lace fb0cl-med
# ln -s fb0pal fb0cl-high
# ln -s fb0multiscan fb0cl-highi
# ln -s fb0multiscan-lace fb0cl-highi+
# ln -s fb0a2024-10 fb0cl-vhigh

You should now see this:

root@colorpot:/dev> ll fb0cl*
lrwxrwxrwx   1 root        6 Dec 19 15:47 fb0cl-high -> fb0pal
lrwxrwxrwx   1 root       12 Dec 19 15:47 fb0cl-highi -> fb0multiscan
lrwxrwxrwx   1 root       17 Dec 19 15:47 fb0cl-highi+ -> fb0multiscan-lace
lrwxrwxrwx   1 root        7 Dec 19 15:47 fb0cl-low -> fb0ntsc
lrwxrwxrwx   1 root       12 Dec 19 15:47 fb0cl-med -> fb0ntsc-lace
lrwxrwxrwx   1 root       11 Dec 19 15:48 fb0cl-vhigh -> fb0a2024-10

Well, that's it. Now you can access the modes through meaningful (or so I
think :-) names, but still have the old Amiga video mode names around.

At this time you might wonder what video modes are actually behind those
names; here is a short list:

/dev name     resolution    line frequency (kHz)    frame frequency (Hz)
              x     y
fb0cl-low     640   480           31.25                   60
fb0cl-med     800   600           48.1                    72
fb0cl-high    1024  768           56                      70
fb0cl-highi   1024  768           31.3                    77   (*)
fb0cl-highi+  1024  768           46.3                    113  (*)
fb0cl-vhigh   1280  1024          51                      87   (*)

(*) interlaced video modes

Additionally, you might want to create one more symlink that will be used
for X11 at all times; for instance, I always use the 1024x768 non-interlaced
mode for X11 (which is named "fb0cl-high" in the example above).
So, I create a symlink:

# ln -s fb0cl-high fb0x11

And now I just tell the Xserver to use this mode when starting:
$ export FRAMEBUFFER=/dev/fb0x11
$ startx


5) Installing the utilities
---------------------------

[Please note: Now that it is possible to set the monitor limits immediately
at kernel-startup time, there is no more need for "freq" at all; but I
still include it for your convenience.
For information about setting the monitor limits on the amiboot command line,
see below in "Starting the kernel"].

This driver comes with a small tool for maintenance named "freq".
You get both sources and binaries (compiled for libc6 aka glibc).
For now, I suggest to copy the binary to your /sbin directory and having 
your PATH variable point at that location.

"freq" allows to inquire or set the current monitor limits for the driver,
on a per-board basis.

There used to be another tool named "tog", but this is not required
anymore and will do nothing when started against this driver version;
please delete it. Also, remove any invocations of it, like in your
$HOME/.xinitrc.


6) Checking the cabling
-----------------------

The cabling for the typical (one-monitor) system is just the same as you
might be used to from AmigaOS: The Amiga's output is connected to the VGA
board's 9-pin input with a short cable, and the VGA board's output is
connected to the monitor. This allows to either see the Amiga video signal
(by letting it pass through the board) or the VGA board's signal (by
switching the toggle). If you start the kernel with "video=clgen", though
(see below, under "Starting the kernel"), the board's own video output is
visible all the time and there is no Amiga display at all, so there is no
need to ever switch back to the Amiga signal.

If you have a 2-monitor-setup (one monitor connected to the Amiga, the other
connected to the VGA board), you will see that when you start the kernel
with "video=clgen", the Amiga's signal is just a gray blank screen. This
is so because the Amiga display subsystem is not initialized at all.
You can safely forget about the monitor connected to the Amiga's video
output now.

7) Starting the kernel
----------------------

Starting the kernel with its display on your graphics board works similar to
the way you used to start kernels before: To your list of options passed to 
either amiboot or amiga-lilo (I only use amiboot, so I can't explain what
exactly you have to do to the latter), add the following:

video=clgen[:suboption,suboption]

The suboptions allow you to set the monitor capabilities or startup video
mode right here, instead of having to use freq or fbset later. Here's
how they have to look like:

monitorcap:vmin;vmax;hmin;hmax

  where vmin and vmax are vertical minimum and maximum frequencies in Hz,
  and hmin and hmax are horizontal min/max frequencies in kHz(!).
  The default values are "monitorcap:50;90;30;38", which means vertical
  range from 50 to 90 Hz and horizontal range from 30 to 38 kHz.

mode:{low|med|high}
  This sets the startup (default) video mode for all consoles.

  Name    resolution[pixels]   hfreq[kHz]     vfreq[Hz]   columns  rows
  low        640x480            31.25           60           80     30
  med        800x600            48              72          100     37
  high      1024x768            55.8            70          128     48

So, here's as an example a complete line from MY current setup;
don't even think about using exactly this line in your setup:

   "video=clgen:monitorcap:50;120;30;86,mode:high"

PLEASE NOTE! The ";" character under AmigaOS has the meaning of a comment,
thereby discarding the rest of the line. Therefore, if you use the
"monitorcap:" suboption, don't forget to enclose the whole option in
double quotes (" ") to avoid this misinterpretation of ";". If the kernel
does not start in the way you expected, this is a possible reason; type
"cat /proc/cmdline" to see whether really the whole parameter list was
passed through.

When the kernel starts, you should see the clgen driver report its
version number and what hardware it has found, like this:

[..]
   0x42000000: Helfrich SD64 Graphics Board (RAM) (Z3, 16M)
   0x00e90000: Helfrich SD64 Graphics Board (REG) (Z2, 64K)
 clgen: Driver for Cirrus Logic based graphic boards, v1.3 (12-Jan-98)
 clgen: Monitor limits set to H: 30000 - 86000 Hz, V: 50 - 120 Hz
 clgen: SD64 board detected;  RAM (16384 KB) at $42000000,  REG at $e90000
 clgen: This board has 4194304 bytes of DRAM memory
[..]

Don't be confused by the different numbers for RAM amount (16 MB vs. 4 MB);
the first number is the Zorro address space usage, which is often larger
than the amount of RAM on the board. The number in the last line should
be the actual amount of RAM your board has.

At this point you can already open a bottle of champagne, because if you
can read the above messages, it means the driver works for you. The (default)
console looks pretty much like before on OCS/ECS/AGA, but it's now in 
60 Hz instead of 50 Hz (PAL), and it uses 256 colors. Of course, if you
immediately try to use one of the higher console sizes (mode:med or 
mode:high), it will look even better :-). But for a start it's probably
wise to begin with the default mode and make sure that it works.

If you attempt to start the kernel with a video mode that exceeds the
monitor limits, the driver will fall back to the standard "low" mode instead.
Also, if your "monitorcap:" suboption makes no sense, the driver will
switch back to the default of H:30-38 kHz, V:50-90 Hz.

The display might be misaligned now (like too wide or not centered).
If your monitor has the ability to store video mode settings (display
size and location), you can use its controls now to center the display.
Though, you can also use fbset to do that; see below, in "Using fbset
to adjust modes".


8) Setting/inquiring the monitor limits
---------------------------------------

It is possible that a graphic board can damage the connected monitor by
sending it a video signal with too high or too low line/frame frequencies.
To avoid this, the clgen driver will reject a video mode that would exceed
the specifications of the monitor. But how can the driver know the limits?
The answer is: You have to tell him.

By default, clgen assumes that the connected monitor is a "poor" model that
can only do 30 - 38 kHz line frequency and 50 - 90 Hz frame frequency. 
These should be "careful" defaults for most monitors in use nowadays.
Also, the video mode that the board produces at kernel startup is a
very "careful" mode using just 640x480 pixels with 31.5 kHz line frequency
and 60 Hz frame frequency - even fixed-frequency old VGA monitors should
be able to handle this.

If you try to activate a mode that exceeds your monitor's limits, you will
get a message from the clgen driver on the current console, like this:

      clgen: desired mode exceeds monitor limits (rejected)!

If your monitor CAN handle higher frequencies than the default, please look
up its limits in your monitor's manual, and set the corresponding values
in the kernel, using either the "monitorcap:" option as explained in the
previous chapter, or use the "freq" tool to tell the driver about it. 
I recommend using the "monitorcap:" option of amiboot, as your monitor limits
will probably rarely ever change in the near future, and most of the time
there is no need to change the limits during one Linux session.

The usage is:

Usage: freq [-q] [-f n] [-s minhor:maxhor:minvert:maxvert]
 -q                                queries the current monitor settings
 -f n                              chooses framebuffer driver #n
 -s minhor:maxhor:minvert:maxvert  sets new limits
    All min/max values are in Hertz (hz), e.g. 30000:38000:50:90

So, to get the current limits for framebuffer #0 (which is probably
your graphic board), type:

root@debian:~> freq -f 0 -q
Current monitor limit settings for fb driver #0 [CLGen:SD64]:
Horizontal: 30000 - 38000 Hz
Vertical: 50 - 90 Hz

Let's assume your monitor can do 30 - 58 kHz line frequency, and 50 - 100
Hz frame frequency. Then, you'd type (as root):

root@debian:~> freq -f 0 -s 30000:58000:50:100
Monitor limit settings for fb driver #0 [CLGen:SD64] have been set to:
Horizontal: 30000 - 58000 Hz
Vertical: 50 - 100 Hz

You see that the limits have been raised, and modes within the new limits
will not be rejected anymore. Please note that modifying the limits is
regarded as a "privileged" operation, and can thus only be executed
by root. Anyone can inquire the current settings, though.

PLEASE NOTE: Don't just enter some invented numbers - LOOK UP THE SPECS
IN YOUR MONITOR'S MANUAL! Otherwise you risk damaging your hardware.

PLEASE NOTE2: If you are upgrading from the 1.0 driver, check out any place
where you start freq; the framebuffer number is now 0 and not 1 anymore
(as it used to be)!

Personal suggestion: If you do not want to use the "monitorcap:" option
for whatever reason, I suggest to put the "freq" invocation into a startup
file like "/etc/init.d/boot" (or however it is called on your installation).
But note that by the time the program is started, your root partition is
probably the only one that is mounted - so keep the "freq" binary in a place
on the root partition (like /sbin).

PLEASE NOTE3: Once you have installed the "freq" invocation in a startup
file like suggested in the previous note, starting the kernel with an
Amiga console again ("video=pal-lace" or similar), you might run into
problems when trying to change a mode; this is so because some of the Amiga's
video modes just use 15 kHz line frequency (even if doubled by a hardware
flickerfixer; it's the number that counts), and your monitor can only do 
30 kHz or above. In that case, you will have to change the monitor limits
again before you can change video modes for it.


9) Using fbset to adjust modes
-------------------------------
You have probably 2 choices to center the display on your monitor:
You can either use the monitor itself (newer models are able to store
a lot of video mode settings and immediately activate a stored profile
whenever they recognize a certain frame format), or you use fbset.
fbset also allows to adjust a lot of other things - like, setting totally
new timing parameters. I will not explain the fbset usage in full detail
here; rather, I'll only give a little example of what might be a typical
usage of it for the clgen driver.

Let's assume you have sucessfully started the kernel, see the initial
640x480 image, but it is not centered. Now you can use fbset like this
to move the image around:

# fbset -move [left|right|up|down]

This will move the image in the corresponding directions (not every
invocation moves the display as the granularity of fbset is finer than
that of the VGA hardware; try invoking it several times to get a feeling
for it).
Similarly, you can set all timing values (-left, -right, -up, -down,
-hslen and -vslen) until you are satisfied. When done, you can ask
fbset to print out the current timing parameters of the "current"
video mode:

# fbset -i

and write the "mode" part of the output into your /etc/fb.modes file
where it is quickly available. Replace the "name" with a meaningful name
(I suugest to choose a naming scheme that start with "cl-", like "cl-high".
From now on, you can immediately set this mode with a command like
"fbset cl-high".

NOTE GPM USERS!
The "gpm" program which lets you do Cut&Paste operations on the console
will not notice when you change the console's video mode (size) and will
continue to use the columns/rows numbers it has determined when it started.
This can lead to two strange things:

a) You change to a higher-resolution console: The mouse cursor of gpm will
   not be able to access certain parts of the console (at the far right
   and bottom of the screen).

b) You change to a lower-resolution console: It is possible to move the
   mouse cursor out of the visible area.

These are no bugs of clgen. My solution suggestions are:
- to fix gpm's signal handling (if it's really the culprit)
- to not change the console size at all (and only use mode:xxx at startup)
- to restart gpm after a console size change

In section "Example of fb.modes entries" below you will find a list of
modes that you can append to your /etc/fb.modes file. The listed modes are
exactly the same as those found in the kernel driver (except for the
SuperLoRes mode).

All of this still doesn't really help you because the mode used by the kernel
at startup time is not taken from /etc/fb.modes, but from the driver itself;
if you have changed the video mode and want it to appear like that
immediately at kernel startup time, you still have the option to put your
new timings into the driver's mode database itself and compile your own
custom kernel. 


PLEASE NOTE: THE PARAMETER CHECKING IN THE DRIVER IS VERY INCOMPLETE;
YOU MIGHT BE ABLE TO CREATE A TIMING SETTING THAT CREATES AN UNUSABLE
DISPLAY (WHICH MIGHT EVEN LOCK UP THE COMPUTER). USE FBSET WITH CARE!

fbset is also used set an oversized ("autoscroll") display; here is
an example:

Let's assume you have a poor monitor that cannot do much better than
640x480 pixels, which is usually too little for reasonable working in X11.
So, to create a virtual workspace of, say, 1024x768 pixels, you'd
type:
# fbset -ofb /dev/fb0x11 -vxres 1024 -vyres 768

Now you just have to tell the Xserver which mode to use, and start it:
# export FRAMEBUFFER=/dev/fb0x11
# startx

When the Xserver has started, trying moving the mouse pointer against
the right or bottom border, and you should see the well-known autoscroll
effect.


10) Starting/using X11 with clgen
---------------------------------
The application that's (IMHO) going to be the most-used one is the X
Window System. Unfortunately, using it with the clgen driver is not quite
as easy as is with Linux on i386 machines, but it's very close by now.

The only thing you have to do before you can start X is to tell the Xserver
on which framebuffer device it has to work; using bash, this is typically
something like:

$ export FRAMEBUFFER=/dev/fb0x11
$ startx

Replace the "fb0x11" with whatever video mode device you want to use for X.

If you rather start an Xsession via xdm instead of "startx", you will have
to put the "export ..." line into something like /etc/init.d/boot (or 
wherever your xdm gets started). It's just important that FRAMEBUFFER
is set to the correct device name before the Xserver starts.


11) Example of fb.modes entries
-------------------------------

The following is an excerpt from my /etc/fb.modes file; it provides the
same video modes as those predefined in the clgen driver. Just append this
to your /etc/fb.modes file, and you can immediately switch to one of them
by feeding its name (from the "mode" line) to fbset, like so:

$ fbset cl-med

This will of course only work if:
 - your monitor can operate at the desired frequency
 - you set the monitor limits with freq accordingly


########################
## CLGen modes, as found in the predefined modes in the driver
########################

# 640x480. This mode should work on ANY Multiscan monitor
mode "cl-low"
	# H: 31.250 kHz, V: 59.524 Hz
	geometry 640 480 640 480 8
	timings 40000 32 32 33 10 96 2
	hsync high
	vsync high
	bcast false
endmode

# 800x600. Nices for consoles
mode "cl-med"
	# H: 48.077 kHz, V: 72.188 Hz
	geometry 800 600 800 600 8
	timings 20000 64 56 23 37 120 6
	hsync high
	vsync high
	bcast false
endmode

# 1024x768, non-interlaced. If your monitor can do this, it's a
# good choice for X11.
mode "cl-high"
	# H: 55.866 kHz, V: 69.399 Hz
	geometry 1024 768 1024 768 8
	timings 12500 92 112 31 2 204 4
	hsync high
	vsync high
	bcast false
endmode

# 1024x768, interlaced. If your monitor is not capable of high
# horizontal frequencies, this might be a good alternative to cl-high.
mode "cl-highi"
	# H: 31.360 kHz, V: 76.769 Hz
	geometry 1024 768 1024 768 8
	timings 22268 92 112 32 9 204 8
	hsync high
	vsync high
	laced true
	bcast false
endmode

# 1024x768 interlaced, but with a bit higher frequencies, so less flicker.
mode "cl-highi+"
	# H: 46.240 kHz, V: 113.196 Hz
	geometry 1024 768 1024 768 8
	timings 15102 92 112 32 9 204 8
	hsync high
	vsync high
	laced true
	bcast false
endmode

# 1280x1024 interlaced. For those who want "full-size" X11. :-)
mode "cl-vhigh"
	# H: 51.020 kHz, V: 87.589 Hz
	geometry 1280 1024 1280 1024 8
	timings 12500 56 16 128 1 216 12
	hsync high
	vsync high
	laced true
	bcast false
endmode



12) Not-Yet-Features(tm), ToDo's
--------------------------------

- A copy of the driver's mode database should be created for each board
  detected. This is not yet done. Currently all initialized boards share
  the same video mode database in the driver.

- Activate 15/24/32 bit modes once the Xserver at least supports some of
  them (24/32 bits should not be too hard, but 16 bits is almost impossible
  because the upper/lower bytes are swapped on the bus (on some of the
  boards at least), so that you cannot access the colors as in 
  "rrrrrggg gggbbbbb", but instead "gggbbbbb rrrrrggg" which the Xserver
  will probably never be able to cope with).

- Make use of the BitBlt engine for X11: I understand that lacking blitter 
  support leaves a good deal of the hardware capabilities unused, but the 
  current framebuffer driver does not make any provisions for using 
  accelerated hardware in an application program (like the Xserver).
  Probably once we adopt the ggi concept, this might be added.
  Until then, there is nothing I can do about it. But at least the console
  is already accelerated.


13) Non-features(tm), also known as Known bugs
----------------------------------------------

- In 320x200 DoubleScan mode, a one pixel wide column is visible at the left
  border that should actually be at the right border. I haven't yet found
  the reason for this.

- A few safety checks are still not in there. Use the driver, but don't stress
  it to its limits :-}.


14) Credits
-----------

There are a couple of persons I'd like to thank: 
- Uli Sigmund of Viona, Karlsruhe, for providing me with Cluster sources
  of his EGS drivers.
- Joerg Ringelberg of Viona, Karlsruhe, for supplying me with the databooks
  for CL GD542x/5434.
- Klaus Burkert of Villagetronic for some hints on Fifo threshold settings
  during the Steinhagen Amiga meeting in October '96, and also for info
  on how to turn off the VideoCapture unit on the P4.
- My professor of the Computer Graphics department, Peter Gorny, for
  accepting this as topic for a "Studienarbeit". I always knew studying
  CAN be fun at times. :-)
- Jes Soerensen for maintaining the Linux m68k kernel source since 1.3.xx
  so well (also thanks for this nice little parcel that made my ZipRAM farm
  complete :-)
- Martin Apel; his Cybervision driver for Linux is not really a very complete
  driver (yet? ;-), but due to its simplicity it helped understand some
  of the ideas behind fb.
- Geert Uytterhoeven for several helpful hints and suggestions
- Anyone else involved in making Linux/m68k as usable and stable as it is
  now. Although I believe we won't be able to push Billyboy Gates out
  of the market with this, it shows how well people from all over the world
  can cooperate in the Internet to work on a common goal.
- All you users who bugged me then and now about when this beast will be
  released; I know it took MUCH longer than I had expected/told you,
  but after all it's out now, and is free. Forgive me.
- The "beta guinea pigs" :-) on IRC - Chels, Nes, pCp, you know who you are.
  Thanks for testing&bug reporting.


15) Contacting the author
------------------------

If you 
 - find a bug in the CLGen driver
 - want to tell me how good/bad it works in your environment
 - have source patches/suggestions

please contact me via E-Mail: Frank.Neumann@Informatik.Uni-Oldenburg.DE
Especially if you found something that should be added to this documentation
file, I'll gladly accept it.
I do get LOTS of mail every day, so bear with me if replying takes a while.
(these "lots" do not come from thousands and millions of clgen users, but
from those too much mailing lists I'm subscribed to ;-). Oh, and one more
thing: I DO NOT LIKE MIME-MAIL.

The newest version of this driver should always be available through my
homepage: http://www.informatik.uni-oldenburg.de/~amigo/
Look out for some "Linux/m68k" stuff in that page. I'm sure you'll be
able to find it! :-)

If you want to report a bug, please don't forget to include:
 - what kernel you are running
 - what version of clgen you are using
 - what system configuration you have
 - how you triggered the bug
 - whether the problem is reproducible or not
 - ..and any other information that might be helpful.


16) History
----------

 *  - 16-Mar-1997: v1.0 First public release
 *  - 22-Oct-1997: v1.1 Added basic console support, P4 support (not working)
 *                      This was never released to the public
 *  - 19-Dec-1997: v1.2 Public release
 *                      working console support
 *                      working P4 support
 *                      hardware-accelerated RectFill/BitBLT on consoles
 *                      (only in 8 bits right now)
 *                      correct standard VGA colour table
 *                      1 bit support working again
 *                      uses the FB_ACTIVATE_* flags correctly now
 *                      correct behaviour when used with fbset
 * - 12-Jan-1998: v1.3  Public release
 *                      correct CLUT handling for Picasso4 (was BGR, not RGB)
 *                      removed left-over printk for Picasso II
 *                      now accepts monitorcap: and mode: on command line
 *                      correct "scrolling" when height or width = 0
 *                      (though that's been done in console/fbcon.c)


42) Final words
---------------

Well, good luck now, and of course: You use this driver at your own risk.
If it blows your computer, monitor, cat or girl-friend, I'm not responsible
for that. If it causes a parallel universe to be opened, I'll be interested
in hearing how you managed to do that, though. :-)
This is free software, but I'd never reject signs of appreciation. Even
a little postcard is something I'd always welcome.
Personal plug: I might be able to finish my studies sometime in spring '99 - 
got an interesting job then? Here I am. :-)

Frank, 12 Jan 1998
--
+        Frank Neumann, Hauptstr. 107, 26131 Oldenburg, Germany         +
+     InterNet: Frank.Neumann@informatik.uni-oldenburg.de IRC:Franky    +