From: Jon M. Taylor <taylorj@ecs.csus.edu>
  To  : GGI mailing list <ggi-develop@eskimo.com>
  Date: Sat, 8 Aug 1998 15:27:31 -0700 (PDT)

kgicon FAQ

	I wrote one up yesterday and sent it to the maintainer of the x86 
framebuffer HOWTO.  A new version of that howto should be out soon with 
the kgicon info included.  Here's what I sent him, although he may do 
some refarmatting and/or trimming and it mill probably be HTML-ized.

<---cut here--->
kgicon FAQ list
by Jon Taylor
Last updated 8/7/98

1. What is kgicon?

	kgicon is a way to use KGI video drivers as fbcon video drivers. 
it is a bridge layer between the fbcon and KGI interfaces.

2. OK, what is a KGI driver then?

	KGI stands for Kernel Graphics Interface.  KGI is a subproject of
the GGI project (http://www.ggi-project.org) which is concerned with
producing a video card driver API and a set of video drivers to be used
with Linux.  Conceptually, KGI is analogous to fbdev and the KGI drivers
are analogous to the fbcon video drivers.  There are important
architectural differences, though - see section 3 for more detail. The KGI
framework itself is currently being overhauled and is nonfunctional.  The
KGI *drivers*, though, are still quite useable.

3. How are KGI drivers different from fbcon drivers?

	fbcon drivers are "monolithic".  This means that all the driver
code is contained in one source file.  KGI drivers are modular.  Each
driver is composed of five driver subsection that are selected separately
and linked together at compile time.  These subsections are: 

* Chipset driver.  This is analogous to the monolithic fbcon driver, 
which is usually designed around a particular video chipset.

* Clockchip driver.  Controls the calculation of mode timings.  The same 
chipset can be use with a different clockchip on some video cards.

* Ramdac driver.  Controls the digital-to-analog conversion circutry on 
the card.  As with clockchips, the same chipset can be used with 
different ramdacs.

* Acceleration driver.  This controls accelerated drawing commands,
anything from drawing lines and block copying to more complex 3d
acceleration.

* Monitor driver.  This subsection does not actually control any video 
hardware.  It consists of a set of mode timing constraints, which prevent 
the other driver subsections (mostly the clockchip driver) from 
generating mode timings that the monitor cannot handle.

	This modular architecture allows for greater re-use of driver 
code.  It also enforces a clean separation of functionality and imposes a 
more consistent driver code layout.

2. What can kgicon do that vesafb cannot?

* Work on older hardware that does not support VESA 2.0. 

* Load as a module.  vesafb must be compiled into the kernel.

* Switch modes.  vesafb's video mode must be selected at kernel boot time
and cannot be changed later.  Because of this, all consoles must also run
in the same video mode.  In contrast, kgicon can switch modes with the
fbset utility any time, and each console can have its own mode. 

* Use YWRAP/YPAN to speed up console scrolling.  vesafb is limited in its
knowledge of the layout of and ability to control the underlying hardware,
and so it cannot use some tricks such as changing the start address of the
framebuffer to speed scrolling.  KGI drivers have full control over every
aspect of the hardware, and so they can use whatever capabilities are
present to speed up scrolling.

* Use non-fixed modes.  vesafb, by its nature, is limited to VESA standard
resolutions such as 640x480, 800x600, etc.  kgicon can set any mode the
video hardware is capable of, such as 1024x480, 896x762, or whatever you
want.  The only restriction is that the mode must have a legal mode timing
for the video hardware that is being used and the mode cannot be outside
of the monitor driver's capabilities. 

* Adjust mode timings.  vesafb can only use the mode timings which have 
been preset in the VESA BIOS.  kgicon drivers can set any mode timings 
that are legal for the hardware and the monitor.

3. What can vesafb do that kgicon cannot?

* Be compiled into the kernel and used at boot time.  kgicon drivers only 
work as modules right now.  Sorry, no penguin logo |-<.

* Work on VESA 2.0 compliant hardware for which a KGI driver has not been
written.  The NeoMagic chipsets which are used in many notebooks have no
KGI driver since the hardware specs are under NDA, but since they are VESA
2.0 compliant they can be used with vesafb.

* Be smaller and stabler.  vesafb does not have to deal with a lot of the
complexities that a true video driver does.  This greatly reduces the 
amount of code needed, as well as removing many opportunities for bugs to 
arise.

3. Which hardware does kgicon support? 

Chipsets:
* Chips & Technologies 655xx
* Cirrus Logic 542x and 546x
* Cyrix MediaGX
* Hercules monochrome
* IBM VGA
* Matrox Millennium I and II and Mystique
* S3 928, 96x, 765 (Trio64V+) and 325 (ViRGE)
* Tseng ET4000 and ET6000
* Western Digital PVGA, wd90c00, wd90c1x, wd90c2x, and wd90c3x

	Most clockchips and RAMDACs that were/are used with any of the
supported chipsets are also supported.  Acceleration support varies widely
from card to card, but there is a generic software acceleration driver
which can be used if a hardware acceleration driver is not present.  The 
acceleration driver is not currently used by kgicon anyway, as its 
functionality does not fit into the fbcon API very well.

	Monitor drivers are divided into three categories: monosync,
multisync and timelist.  

	Monosync monitors can only use a fixed set of one or more mode
timings.  There are three monosync drivers available: MDA (old monochrome 
drivers), VGA and SVGA.  Each allows only the timings which are standard 
for the given hardware.  SVGA standard timings are the VESA standard timings.

	Multisync monitors can use any mode timings within specified
ranges.  Each driver corresponds to a particular make and model of
monitor, since they all have their own unique timing constraints.  A 
database of monitor names and their timing specs is used.

	Timelist monitors are similar to multisync monitors, but they have
sets of allowable timing ranges rather than one continuous range.  Some
older monitors have this property.

4. I read the above, but I still am not sure if I can use kgicon because 
I don't know the specifics of what hardware I have.  Help!

	In a pinch, almost everyone whould be able to use the VGA drivers
and the monosync VGA monitor driver.  But to get the most benefit from
kgicon, you do need to know what hardware you have.  Here are some places
you can look for that info: 

* If you have XFree86 or another X server up and working, try 'X
--probeonly' to get a hardware report.  Look for the chipset, ramdac and
clockchip names.

* If you know the brand name of your video card, try looking on the 
website of the manufacturer for technical info.

* Ask around on video card related newsgroups/mailing lists/whatever.

* As a last resort, open up your computer and examine the video card. 
Write down all the names and numbers on the various chips, together with
descriptions of the shape and size of the chips, and then ask around. 

	As for your monitor, the best bet is to find out it's timing
constraints and make yourself a multisync monitor database entry.  Look at
your monitor manual for this info.  If you don't have a manual, look on 
the manufacturer's website or one of the many monitor timing databases 
available on the net.  Several of these databases are available from the 
GGI website at www.ggi-project.org.

	If you just can't find that timing info, use one of the monosync 
monitor drivers instead.  BE CAREFUL!  While newer monitors will blank or 
display an error message if they recieve signals that are outside their 
range, many older monitors will blindly use the invalid signal and can be 
damaged or destroyed.  When in doubt, use the VGA monosync driver - it 
should constrain the mode timings acceptably for any VGA monitor.


5. OK, I know what my hardware consists of and I am ready to give kgicon 
a try.  Where can I get it from?

	kgicon can be gotten from the main GGI CVS source tree.  If you
know what CVS is you can use it to fetch the tree ananymously from the GGI
project's CVS server.  If not, the whole tree is downloadable as one
.tar.gz archive from the GGI web page at www.ggi-project.org.  Yes, you
currently have to download the whole source tree, which contains a lot of
other stuff besides kgicon.  Sorry for the inconvenience.  If enough
people complain, we will try to arrange for kgicon to be available
separately.

6. I got the archive and unpacked it, and I now have a directory called 
'degas'.  What's up with that and what do I do next?

	The GGI project's releases are named after famous painters whose
names start with 'D'.  The last one was 'Dali'.  

	Anyway, if you look in degas/, you will see a directory named
'kgicon'.  Change to that directory and type 'su -c "make install"'.  This
will create a symlink to the kgicon/include/ directory from
/usr/src/linux/include/kgi.  If you do not have your kernel sources in
/usr/src/linux, you will need to make the symlink by hand.

	After you have done this, change directories to kgicon/kgi and do
a make.  A dialog-based config menu will pop up (yes, dialog is required)
which will lead you through the process of selecting the various
subsection drivers.  After this is done and you exit from the config
system, dependencies will be built and then the driver itself will be
compiled.

	Assuming that all goes well, you should end up with a file called
kgicon.o in the kgicon/kgi/ directory.  This is your kgicon video 
driver.  Go on to the next step.  If all did NOT go well (i.e. the 
compile died), retrace your steps and review these instructions to make 
sure you didn't screw something up somewhere along the line.  If you 
still have problems, make notes on what config you are trying to use and 
what errors you are getting (straight error logs are preferred) and post 
an error report to the GGI mailing list.

7. So how do I use this driver module?

	First, you want to sync your disks to minimize filesystem
corruption in case some bug surfaces and locks your system up.  Of course
we hope this won't occur and it isn't really all that likely, but video
cards tend to be particularly nasty about being misprogrammed and it is
better to be safe than sorry until you have gotten kgicon to work reliably
for you.

	kgicon comes with an 'insert' shell script in the kgi/ directory
that will insmod the driver module and call the con2fbmap utility to remap
your virtual consoles from the old driver (usually vgacon) to the new
kgicon driver.  By default, all VCs are remapped.  If all goes well, you
should see your screen flicker and probably change somewhat in appearance
and font style.  Congratulations, you are up and running with kgicon! 
Look elsewhere in this FAQ for ways to play with your new toy. 

8. The module insertion didn't work right.

	First, make sure it doesn't work right with the standard 'insert'
script.  Don't try anything wierd until you have the plain-jane insertion
working.  If you still have problems, see if you can reboot.  If you can,
your syslogs may give some clue as to what went wrong.  If everything is
frozen, just reset.  In either case, collect all the pertinent info and
syslogs if you could get them and mail a bug report to the GGI mailing
list.

9. Is kgicon going into the kernel?

	Not before 2.3, and even then it is still up to Linus.  We wanted
to try to get it in before 2.2, but it just wasn't ready in time.  The big
issue was the lack of kernel makefile integration - the KGI makefile
system is quite different from Linux's.  Work in underway to remedy this,
but in the meantime it is necessary to use modules.

10. I thought I needed to patch the kernel to use KGI drivers!

	Nope, not anymore.  That is the beauty of kgicon.  When the new
Degas-KGI system is ready, it will be necessary to patch the kernel to use
it, but kgicon will still be an option and will still not need any
patches. 

11. All the KGI drivers are for x86-based video hardware right now.  Is 
there a reason for this?  Will non-x86 KGI drivers ever be developed?

	The reason for this is that up until recently, KGI was explicitly
x86-oriented.  Also, there are a LOT more x86 boxes running Linux out
there than other types, and this was even more true a couple of years back
when KGI development started.  It is what people had to work with. 
Another factor is that until the m68k Linux ports were merged, the m68k
guys had fbcon and didn't need KGI.

	Nevertheless, there is no reason why non-x86 KGI drivers cannot BE
written.  There are a couple developers working on PPC and Sparc KGI
drivers right now.  But it is up to those with access to Linux running on
non-x86 platforms to step up and volunteer to do the work.  If you are
interested, look on the GGI project website for more info or ask on the
mailing list. 

12. Gimme some contact info.

	GGI project web page: http://www.ggi-project.org

	FAQ author: Jon Taylor <taylorj@ecs.csus.edu>

	GGI mailing list: ggi-develop@eskimo.com.  See the web page for 
	subscription info and list archives.


---
'Cloning and the reprogramming of DNA is the first serious step in 
becoming one with God.'
	- Scientist G. Richard Seed