

            clgen v1.0 - a generic driver for Cirrus Logic based
               graphic boards for the Amiga under Linux/m68k

                     Copyright (c) 1997 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!


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

This driver supports the following graphic boards:
- Piccolo SD64 (Ingenieurbuero Helfrich)
- Piccolo      (Ingenieurbuero Helfrich)
- EGS Spectrum (GVP)
- Picasso II   (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 through 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
  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! :-)

- 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.

- 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 via a new little program "freq"
  (see below) which might be integrated into fbset later.


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.29 kernel source tree. I haven't yet tried with 2.1.x kernels;
this might require a few changes.

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

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).
Likewise, you will now create some nodes for the clgen driver, which should
be named fb1*. Here is what I suggest; these are sort-of telling names that 
correspond to the modes that come with the driver:

cd /dev
mknod fb1current c 29 32
mknod fb1autodetect c 29 33
mknod fb1_640 c 29 34
mknod fb1_800 c 29 35
mknod fb1_1024 c 29 36
mknod fb1_320 c 29 37
mknod fb1_1024i c 29 38
mknod fb1_1024hi c 29 39
mknod fb1_1280i c 29 40


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

This driver comes what a small set of tools for maintenance; these are
"freq", "tog" and a slightly modified version of "fbset". You get both 
sources and binaries. For now, I suggest to copy the binaries to your
/usr/local/bin 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.

"tog" is a tool to switch the relais on the graphic board that selects
between "Pass-Through" mode (Amiga video signal is passed through the
graphic board) or "Board mode" (where the board's own video signal is
sent to the output).

The new "fbset" is just slightly extended to allow to set/clear the
the "ClockHalving" bit which is usually required for DoubleScan modes
(at least on VGA boards). Its purpose is to avoid interferences between
the video and the memory clock if they are close to each other. These
interferences cause jagged vertical lines in the display, and by first
doubling the video clock and then "artificially" halving it again this
problem goes away.


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 via "tog".

If you have a 2-monitor-setup (one monitor connected to the Amiga, the other
connected to the VGA board), the usage of "tog" is still the same; but you 
can just instruct "tog" to switch to the VGA board's output ONCE at boot
time, and never have to care about it afterwards. 


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

Starting the kernel works just the same way you were used to; there are
(as of now) no additional parameters you have to give. This might change
one day when console support is added.

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.0 (27-Feb-97)
 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.

When you see these messages, the driver has started up successfully, and
has already initialized the board to a safe video mode (640x480). You just
can't see it because the board's video toggle switch is still in 
"Pass-Through" mode.

To see the video output of the board, log in as root, make sure you have
created the necessary device nodes as described in the 
"Creating /dev entries" section, and type 

tog 1 1

The monitor should now display the VGA board's signal - which, if everything
went well, is a 640x480 display with a line frequency of 31.5 kHz, a 
frame frequency of 60 Hz, showing a black screen surrounded by a white
border with a pattern of colors in the center (16 shades of each white,
red, green, blue, yellow, purple, cyan). 
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.

To switch back to the Amiga's video display, you will have to type
in (BLINDLY):

tog 1 0

This may seem very unconvenient, but it's all I can do at the moment.
You'd better get a feeling for typing this; it might happen e.g. that
your Xsession crashes and leaves you with a "frozen" display from the
VGA board; at that time you will also have to use "tog 1 0" manually
to switch back to the Amiga display.
More information on the usage and parameters of "tog" can be found below
in the "Switching to/back from the board" section.


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 use the "freq" tool to tell the
driver about it. 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 #1 (which is probably
your graphic board), type:

root@debian:~> freq -f 1 -q
Current monitor limit settings for fb driver #1 [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 1 -s 30000:58000:50:100
Monitor limit settings for fb driver #1 [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.


9) Switching to/back from the board
-----------------------------------
You have already learnt about the "tog" utility that is used to switch
the signal relais on the graphic board. Here is how "tog" is actually
used:

root@debian:~/txt> tog
Usage: tog <boardnum> 0/1
0=Video from Amiga
1=Video from board

So, the first parameter to "tog" is the board number - or, rather the
framebuffer number. As the built-in video hardware is serviced by the
amifb framebuffer (#0), your graphic board will typically be registered
as framebuffer #1, and so this parameter will be 1 in most cases.
The second parameter is self-explanatory: It selects either the
"PassThrough" or the "Board" mode.

This command is intentionally named so short to allow easy&quick
"blind typing".


10) 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 -ofb /dev/fb1current -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 -ifb /dev/fb1current --info

and write the "mode" part of the output into your /etc/fb.modes file
where it is quickly available.

(This section is still a bit short; sorry. To be extended..)


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/fb1_640 -vxres 1024 -vyres 768

Now you just have to tell the Xserver which mode to use, and start it:
# export FRAMEBUFFER=/dev/fb1_640
# 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.


11) 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.

The problem is this: The Xserver on PCs allows to switch back and forth
between the text consoles and the Xserver's graphical display at any
time. This is also true for the m68k implementation of the Xserver, but
the kernel-based graphic drivers do not get to know when a switch occurs,
and so the clgen driver cannot tell when it has to switch the monitor
relais on the board. This problem does not occur on the built-in (OCS/
ECS/AGA) framebuffer because it never has to switch a monitor bit.

The only way out is to either manually type in the "tog" invocations when
you want to switch, or rather not use the VT/X switching capability at
all during one X session.

Now, to at least have the switch automatically perform its task at the 
start and end of an Xsession, I suggest to put the following lines into 
your ~/.xinitrc:

- Immediately before the first X application is started (like fvwm, xterm
  or whatever), put in:

  tog 1 1

- Behind the last application (the critical application; this is the one
  that is not started in the background and makes the Xsession fall through
  when it is terminated) :
  tog 1 0

This should be usable - although it is certainly not nice.

If you rather start an Xsession via xdm instead of "startx", you will have
to put the "tog 1 1" line into something like /etc/init.d/boot (or 
wherever your xdm gets started). In that case you'll probably never
want to switch back to VCs.


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).

- module support: Allow the driver to be compiled as a module that can be
  loaded/unloaded on demand.

- Console support: It would be nice to also make use of the boards' text
  modes, but this is not nicely integratable into the current m68k 
  console handling. Probably when the whole stuff has been cleared up,
  I'll go for this. Of course, once that is implemented, it will NOT be
  possible to use the console feature AND a modularized driver at once. :-)

- Make use of the BitBlt engine: 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. Probably once we adopt the ggi concept, this might be added.
  Until then, there is nothing I can do about it.


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.

- On my monitor, the SD64 display in 1024x768 looks somewhat blurry (all
  characters "smear" a bit to the right). I'm not sure what causes this;
  the cable is a good one (BNC). If other people notice this, too (and find
  that under AmigaOS they do NOT have this problem), I might have to 
  investigate on it.

- I could test this driver on a Piccolo, SD64 and Picasso II; therefore,
  the Spectrum support is yet untested by me. If someone with a Spectrum
  uses this driver: PLEASE TELL ME ABOUT THE RESULTS! I believe it
  should work, but the Spectrum support was put in "blindly".

- A lot of safety checks still need to be written; e.g., you can easily
  create Oopses by requesting a display larger than the board's DRAM
  area. So, DON'T DO THAT.


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.
- 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 Billybox 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.

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.

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


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 in late '98 - got an
interesting job then? Here I am. :-)

Frank, March 16th, 1997
--
+        Frank Neumann, Hauptstr. 107, 26131 Oldenburg, Germany         +
+     InterNet: Frank.Neumann@informatik.uni-oldenburg.de IRC:Franky    +