I have drawn from the document:  VgaDriver.Doc
  How to add an (S)VGA driver to XFree86
  Copyright (c) 1993, 1994 David E. Wexelblat <dwex@XFree86.org>
  Issue 1.3 - May 29, 1994

and have written the following.  Hopefully in acknowledging the major source
of the information contained in this document above is sufficient to obeying 
the copyright.

The following is a proposed document for people looking to develop a new
chipset/clock/ramdac driver for scrdrv...

 1)  get the documentation for your chipset...see the reference at the end..
     a) obtain the 'databook' for the chipset
     b) make CERTAIN the person understands you wish to do register level
	programming (so they don't send you EE-style datasheet)..
     c) ask for any example code, programming kits, etc..

 2)  become familiar with VGA register-level programming ..either
     a) you already know how, or you should
     b) get and read Richard Ferraro's 'bible' .. see references below..

 3)  create your directories
     a) scrdrv*/drivers/chipset/chipsetname
     b) possibly the plain vga driver or a simple one like TSENG or TRIDENT
	would be a good place to start by copying the files from there
     c) setup the makefiles to cause your driver to be built...
        (this should just involve adding another subdir to the scrdrv*/drivers/chipset/Makefile )

 4)  Begin the actual development
     a)  Bank Switching Functions

	  The normal VGA memory map is 64k starting at address 0xA0000.  To
  	access more than 64k of memory, SuperVGA chipsets implement ``bank
  	switching'' - the high-order address bits are used to select the bank
  	of memory in which operations will take place.  The size and number of
  	these banks varies, and will be spelled out in the chipset
  	documentation.  A chipset will have zero, one or two bank registers.
  	Likely the ONLY case of zero bank registers is a generic VGA, and
  	hence is not a concern.

  	Note that some of the newer chipsets (e.g. Trident 8900CL, Cirrus)
  	allow for a linear mapping of the video memory.  

  	Most SVGA chipsets have two bank registers.  This is the most
  	desirable structure (if any banking structure can be called
  	``desirable''), because data can be moved from one area of the screen
  	to another with a simple `mov' instruction.  There are two forms of
  	dual-banking - one where the two bank operations define a read-only
  	bank and a write-only bank, and one with two read/write windows.  With
  	the first form, the entire SVGA memory window is used for both read a
  	write operations, and the two bank registers determine which bank is
  	actually used (e.g. ET3000, ET4000).  With the second form, the SVGA
  	memory window is split into two read/write banks, with each bank
  	pointer being used to control one window.  In this case, one window is
  	used for read operations and the other for write operations (e.g.
  	PVGA1/Western Digital, Cirrus).

  	A chipset that has a single bank register uses that one bank for both
  	read and write access.  This is problematic, because copying
  	information from one part of the screen to another requires that the
  	data be read in, stored, and then written out. For the mmap-code you
	should start out from a driver that does the same thing as your card.
	If there is no such driver available, you are on your own, but looking
	for a similar one would still be a good idea.

    b)	The Driver
	There are two main things that have to be implemented to get a
	working driver for a new chipset: Bank switching and mode setting.

	While the first one is quite trivial, when you can start from a
	similar driver. The register access that does the page-select in the 
	kgi_GraphmapNopage function must simply be replaced with the code
	necessary for your hardware.
	If you have to implement a completely new scheme and do not know that
	much about all this mmap-magic, feel free to ask one of the developers
	for advice.

	The second task is much more difficult - it requires a thorough
	knowledge of what modes the card is capable of (if you think the
	card can only do what DOS/BIOS offer ... go and read the docs ...).

	There are two functions to implement : CheckChipsetTiming and
	SetChipsetTiming.

	The first one should check if the card can do a particular mode
	AND calculate all the necessary parameters.
	It should adjust values that it cannot provide to the next possible
	value in a desireable direction (i.e. it should e.g. use a higher
	resolution,not a lower, if the desired one is unavailable).

	For this task you are quite on your own, as chipsets differ widely
	in this respect. You should still use the existing sources as a
	guideline.

	Please note that due to the recursive mode-resolution scheme it is
	very likely that you might produce an infinity loop with bad code.

	This is not too critical (CTRL-C will still work ...), but should
	really be avaoided - test thoroughly for that case !

	The SetChipsetTiming function will probably be the most difficult 
	one to code, as you have to understand the chipset very well to be
	able to do the right thing.

     c)  Chipset features to look for...

	1) Clock Select bits...
	The two low-order bits are part of the standard Miscellaneous 
	Output Register; most SVGA chipsets will include 1 or 2 more 
	bits, allowing the use of 8 or 16 discrete clocks.

	Please note that this normally belongs to the clock-driver.

	If your card can only hold that particular clock-chip (i.e. not
	like S3-boards that can bear the same chipset but different
	clock chips) the clock-driver should be integrated in the chipset
	driver. I would suggest to keep the structure (Check/SetClockTiming),
	but it could be completely integrated in the corresponding Chipset
	functions.

        2) Bank selection.
	The SVGA chipset will have one or two registers that control
	read/write bank selection.

        3) CRTC extensions.
	The standard VGA registers don't have enough bits to address
	large displays.  So the SVGA chipsets have extension bits.

	4) Interlaced mode.
	Standard VGA does not support interlaced displays.  So the SVGA
	chipset will have a bit somewhere to control interlaced mode.
	Some chipsets require additional registers to be set up to 	
	control interlaced mode.

	5) Starting address.
	The standard VGA only has 16 bits in which to specify the starting
	address for the display.  This restricts the screen size usable by
	the virtual screen feature.  The SVGA chipset will usually provide
	one or more extension bits.
	You will have to code this information into hw_setdispstart().

	6) Lock registers.
	Many SVGA chipset prevent modification of extended registers unless
	the registers are first ``unlocked''.  You will need to disable 
	protection of any registers you will need for other purposes.

        7) Any other facilities.
	Some chipset may, for example, require that certain bits be set before
	you can access extended VGA memory (beyond the IBM-standard 256k).  Or
	other facilities; read through all of the extended register descriptions
	and see if anything important leaps out at you.

  If you are fortunate, the chipset vendor will include in the databook
  some tables of register settings for various BIOS modes.  You can
  learn a lot about what manipulations you must do by looking at the
  various BIOS modes.


    d) Probe function

	The Probe() function is in our system less important than e.g. in X,
	as our drivers mostly support only a small number of very closely
	related boards to keep the module small, but we should still protect
	dumb users from themselves by checking if we have the right board at
	startup.

	If you are lucky, the chipset will have an identification mechanism
  	(ident/version registers, etc), and this will be documented in the
  	databook.  Otherwise, you will have to determine some scheme, using
  	the reference materials listed below.

	  The identification is often done by looking for particular patterns in
  	register, or for the existence of certain extended registers.  Or with
  	some boards/chipsets, the requisite information can be obtained by
  	reading the BIOS for certain signature strings.  The best advise is to
	study the existing probe functions, and use the reference documentation.  
	You must be certain that your probe is non-destructive
  	- if you modify a register, it must be saved before, and restored
  	after.

	If your driver supports multiple chipsets (you should not try to
	put too different chipsets into one driver - it would make it
	either slow or large) you should check here which one we have and
	put entries in the ChipPar structure stating the amount of Video
	RAM,...

5)  Debugging

  Debugging a new driver can be a painful experience, unfortunately.  It
  is likely that incorrect programming of the SVGA chipset can lock up
  your machine.  More likely, however, is that the display will be lost,
  potentially requiring a reboot to correct.

  However - once you have CheckText and SetText implemented correctly, it
  will probably be easy to back off from a screwed state by using the
  tm-utility.

  It is still recommended (especially for the time before CheckText works
  perfectly) that the system has an attached terminal or a network login
  to allow for a clean shutdown. The SAK-patch (for Linux) is also re-
  commended, as it will often allow to back off from a weird state.

  As this is a module debugging is a problem anyway ... but redirecting
  printk-messages either to a file or a terminal via klogd is advisable.

  Using multiple VTs for debugging is possible when the Set/CheckText
  part works.

  Because of the potential for locking up the machine, it is a VERY good
  idea to remember to do a `sync' or two before starting the driver.  In
  addition, any unnecessary filesystems should be unmounted while the
  debugging session is going on (to avoid having to run unnecessary
  fsck's).

6)  Advice

  I cannot stress this enough - study all available references, and the
  existing code, until you understand what is happening.  Do this BEFORE
  you begin writing a driver.  This will save you a massive amount of
  headache.  Try to find a driver for a chipset that is similar to
  yours, if possible.  Use this as an example, and perhaps derive your
  driver from it.

  Do not let the gloom-and-doom in the debugging section  discourage
  you.  While you will probably have problems initially (I still do),
  careful, deliberate debugging steps can bear fruit very quickly.  It
  is likely that, given a good understanding of the chipset, a driver
  can be written and debugged in a day or two.  For someone just
  learning about this kind of programming, a week is more reasonable.

7)  Advanced Topics

  Newer chipsets are getting into two advanced areas: programmable clock
  generators, and accelerated capabilities (BitBlt, line drawing, HW
  cursor).
  I will write a short introduction on how to implement that later - in
  the meantime, please use the existing source.

8.  References


     o  Programmer's Guide to the EGA and VGA Cards, 2nd ed.

        Richard Ferraro

        Addison-Wesley, 1990

        ISBN 0-201-57025-4

        (This is the bible of SVGA programming - it has a few errors, so
        watch out).

     o  vgadoc3.zip

        Finn Thoegersen

        (This is a collection of SVGA and other chipset documentation.
        It is available on most MS-DOS/Windows related FTP archives,
        including wuarchive.  It is DOS/BIOS oriented, but is still
        extremely useful, especially for developing probe functions).


9.  Vendor Contact Information


     ATI Technologies (VGA-Wonder, Mach8, Mach32)
        33 Commerce Valley Drive East" Thornhill, Ontario

        Canada L3T 7N6

        (905) 882-2600 (sales)

        (905) 882-2626 (tech support)

        (905) 764-9404 (BBS)

        (905) 882-0546 (fax)


     Chips & Technologies
        ???


     Cirrus Logic (SVGA, Accelerators - CL-GD5426)
        3100 West Warren Ave.

        Fremont, CA  94538

        (510) 623-8300 (N. CA, USA)

        (49) 8152-40084 (Germany)

        (44) 0727-872424 (UK)

     Genoa Systems (GVGA)
        75 E. Trimble Road

        San Jose, CA 95131

        (408) 432-9090 (sales)

        (408) 432-8324 (tech support)


     Headland Technologies, Inc (Video-7 VGA 1024i, VRAM II)
        46221 Landing Parkway

        Fremont, CA  94538

        (415) 623-7857


     Oak Technology, Inc (OTI-067,OTI-077)
        139 Kifer Ct.

        Sunnyvale, CA 94086

        (408) 737-0888

        (408) 737-3838 (fax)


     S3 (911, 924, 801
        805, 928)/ (408) 980-5400


     Trident Microsystems Inc (8800, 8900, 9000)
        205 Ravendale Dr

        Mountainside, CA 94043

        (415) 691-9211


     Tseng Labs Inc,
        6 Terry Drive

        Newtown, PA  18940

        (215) 968-0502


     Weitek (Power9000, 5186)
        1060 E. Arques Ave,

        Sunnyvale, CA  94086

        (408) 738-5765


     Western Digital
        (714) 932-4900



