From: dwex@cbnewsj.cb.att.com (david.e.wexelblat)
Subject: Re: Adding support for new card -- instructions wanted
Organization: AT&T
Date: Tue, 5 Jan 1993 19:37:41 GMT

In article <1993Jan2.095240.20788@zip.eecs.umich.edu> plph@quip.eecs.umich.edu (MarkMontague) writes:
> XFree86 gurus, please help!
> 

Sorry it took so long to get around to responding to this.  I haven't had
the time to thing about this until now.  I hope the following is useful,
and helps people out.  Others can feel free to add to this; this discussion
will become the basis for a readme-type file in the next XFree86 release.

For anyone who wants to understand how the X11R5 server works, I highly
recommend the following book:

	The X Window System Server
	X Version 11, Release 5
	Elias Israel and Erik Fortune
	Digital Press, 1992
	ISBN 1-55558-096-3
	ISBN 0-13-972753-1 (Prentice Hall edition)
	$45.95

This book is, unfortunately, incredibly weak in the area of accleration.
It does provide a lot of concrete information about other parts of the
server though.  It's a good investment.

> I have XFree86-1.1 running on my Linux system in monochrome 640x480 generic
> mode.  I WOULD *REALLY* LIKE TO GET IT RUNNING IN 1024x768 noninterlaced, 256
> COLORS.
> 
> Problem is, I have a Compaq QVision 1024/e (Triton) EISA video card.  I
> installed the mit X11R5 and XFree86-1.1 sources, but have _no_idea_ what
> I need to do to add a support for a new card.  I *do* have the technical
> reference manual for the card, and it seems to be very complete.
> 
> If someone could give me some advice, I would be very grateful.

Well, I would think that the first step is to join the XFree86 beta 
team (:->).  If you want to be able to pull from that group of experts,
send email to xfree86@physics.su.oz.au.

Adding a new SVGA card is not that hard.  We'll deal with the other subjects
later.  You can generally figure out most of what you need to do from the
existing drivers in vga256/drivers/*, with the generic vga code in vga256/vga.
I suggest that you get aquainted with the existing driver(s) before you
tackle writing a new one.

Anyone who is interested in understanding SVGA operations should get a copy
of the following book:

	Programmer's Guide to the EGA and VGA cards, 2nd ed.
	Richard F. Ferraro
	Addison-Wesley, 1990
	ISBN 0-201-57025-4

You also need the technical reference manual for your chipset, which has
all of the register definitions.  Another good resource is VGAKIT, which
is a package of DOS-based software (in source) for manipulating SVGA
chipsets.  It is BIOS-oriented, and hence is not directly usable for
Unix, but it has a lot of good information.  Check with the Archie
service for the latest version; I believe that it can always be found
on wuarchive.wustl.edu.

Basically an SVGA driver consists of the following functions:

	- An identification function (which just returns as string that
	  uniquely identifies the chipset)
	- A clock-setting function, which selects an available dot-clock
	  given its index
	- A probe function, that returns TRUE if the SVGA installed is
	  the chipset supported by the driver, and FALSE otherwise.  It
	  also probes the chipset for other information (such as clocks
	  and memory), if the user hasn't supplied the info already.
	- A VT-switch function that enables access to the SVGA registers
	  when the server VT is activated, and removes the access when
	  the server VT is deactivated.
	- A mode restore function, which loads an SVGA mode (i.e. sets
	  up all the registers).
	- A mode save function, which saves a copy of the current SVGA
	  mode (i.e. register settings).
	- A mode initialization function, which fills in a data structure
	  with all of the necessary register settings to activate a
	  specified mode.
	- A viewport-setting function that sets the displayed portion of
	  the VGA memory inside the virtual screen.
	- Bank-setting functions to activate the portion of the SVGA 
	  memory that is accesible to the host.  A good SVGA chipset
	  will have two bank registers - a read bank, and a write bank.
	  There are functions to set each, and one to set them to the
	  same value.  XFree86 also supports single-bank chipsets (in
	  which case a flag is set in the driver.c file, and all three
	  bank functions do the same thing).  The Trident driver is a
	  single-bank driver; compar it to the others for a clear
	  understanding of what's going on here.

Most of this is fairly straightforward, as you basically only have to
worry about extended registers (i.e. not common VGA registers).  The
vga/vgaHW.c file has functions that do the vast majority of the work
for you.

Once you have all of these functions implemented, create a directory
vga256/drivers/MyDriver, and create the driver.c and bank.s files.  Copy
one of the other driver's Imakefile, and modify it as appropriate.
Then go to mit/config, and add your new driver to the X386Vga256Drivers
definition.  Then perform the following steps to build your new driver:

	- In mit/config, do 'make Makefiles'
	- In mit/server, do 'make Makefile'
	- In mit/ddx/x386, do 'make Makefile; make Makefiles depend all'
	- In mit/server, do 'make loadX386'

You can verify that your driver was correctly linked it by executing
'./X386 -showconfig', which will show all of the configured drivers.
The string from your Ident() function should be listed, along with the
other drivers from X386Vga256Drivers.

After your color driver is working, make whatever changes might be necessary
for the monochrome server (again, use the existing drivers as examples).
Create a directory vga2/drivers/MyDriver, and create an Imakefile in
it (the driver.c and bank.s files will be symbolically linked from
the vga256 directory).  The do as above, except that you add your
driver name to X386Vga2Drivers, and do 'make loadX386mono'.

A good way to learn about a new chipset is to work with a DOS mode-setting
program (most, if not all, SVGA's come with one), and write a program
that reads the various registers and prints them out.  This will help you
understand what registers you need to be concerned with.

When hacking display drivers it is a VERY good idea to have a dumb terminal
or a network connection to your machine.  You are very likely to screw up
your display, and it's nice to be able to recover from this without having
to hit the BRS (Big Red Switch).

> 
> Also, the card has a BitBLT engin, line drawing engin, hardware graphics
> cursor, and support for tiling.  I presume that there is no way to take
> advantage of these without extensive modifications of the server.
> 

Yes, extensive modifications are required.  The reason is that these
types of operations involve significant changes to the frame-buffer code
in the server.  As far as I know, there is no really good documentation
on how to do this type of programming.  And I'm certainly in no position
to give more than hints, since I've never done it.  However, there are
currently beta-level servers that support 8514/A and S3 chipsets, based
on the stock X11R5 code (not on XFree86).  And at least one person is
working on merging the S3 support back into XFree86 (I can't comment
on when that will be available).

Here are the contacts I know about (you guys can tell me that you don't
want to deal with this any more, and I will remove you from this list
before this file goes out with XFree86 1.2.  If I've left anyone off who
wants to be included, please let me know).  Note that there is no
connection between these guys and the XFree86 Core Team, other than the
fact that some of them are on our beta-test team, and are merging some
of their work into our work.

	Amancio Hasty <hasty@netcom.com> - Author of XS3, the X11R5-based
		S3 server.  Supplies binaries for 386BSD (and X8514, too,
		I believe).
	Kevin Martin <martin@cs.unc.edu> - Author of X8514, the X11R5-based
		8514 server (the "grandaddy" - basis for XS3, although XS3
		has evolved considerably since then).  I'm not sure if
		Kevin is doing any work in this area any more.
	Jon Tombs <jon@robots.ox.ac.uk> - Working on integrating XS3 with
		XFree86.  Don't bug him about when this will be done.  But
		he is familiar with the S3 support.

> How does one go about adding support for a new graphics card to the server?
> 
> Thank you in advance for any help!
> 

I hope this was helpful to you.

> Mark Montague
> plph@caen.engin.umich.edu
> -------------------------
> P.S.  If anyone else out there has a QVision, please contact me!

Can you send me contact information, so I can obtain the technical reference
for this chipset?  I'm trying to build a library.

--
David Wexelblat <dwex@mtgzfs3.att.com>  (908) 957-5871
AT&T Bell Laboratories, 200 Laurel Ave - 3F-428, Middletown, NJ  07748

"The meaning of life?  That's simple.  Try to be happy, try not to hurt
 other people, and hope to fall in love."  -- Mallory Keaton