<!doctype linuxdoc system>
<article>

<!-- Title information -->

<title>ATI boards README
<author>Marc Aurele La France
<date>1 January 1995
<abstract>
This is the README for the XFree86 ATI VGA Wonder driver used in the XF86_Mono,
XF86_VGA16 and XF86_SVGA servers.
Users of ATI boards based on the Mach8, Mach32 or Mach64 accelerators should be
using the accelerated servers (XF86_Mach8, XF86_Mach32 or XF86_Mach64).  The
unaccelerated servers (XF86_Mono, XF86_VGA16 and XF86_SVGA) still work, but are
a waste of capabilities.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->


<sect> What is the ATI VGA Wonder driver?<p>
The ATI VGA Wonder driver is a 256-colour, 16-colour and monochrome driver for
XFree86.  The driver is intended for all ATI video adapters except those that
do not provide SuperVGA functionality (such as some early Mach8 and Mach32
boards).  The following approximate maximum resolutions (based on the Golden
Ratio of x/y = (1 + sqrt(5))/2) are possible depending on the video memory
available on the board (and the capabilities of your monitor):
<p>
<verb>
    256k    640x409x256    896x585x16
    512k    896x585x256   1280x819x16
    1M     1280x819x256  1824x1149x16
</verb>
<p>
Maximum monochrome resolutions are the same as those for 16-colour mode,
because the monochrome server uses a maximum of one fourth of the available
video memory.
<p>

<sect> What is the ATI VGA Wonder driver *not*?<p>
This driver does not yet support more than 8 bits of pixel depth.  Even if your
manual says that your graphics adapter supports modes using more than 256
colours, the ATI VGA Wonder driver will not use these modes.
<p>
The ATI VGA Wonder driver is not an accelerated driver.  If your board is based
on the Mach8, Mach32 or Mach64 video controllers, this driver will not use the
accelerated functions of the hardware.  It will only use the VGA Wonder
hardware (which, for Mach32's and Mach64's, is integrated into the
accelerator).  This can make opaque moves, for example, quite jerky.
<p>

<sect> What video adapters will the driver work with?<p>
Most boards harbouring the following ATI video controller chips will work with
this driver:
<p>
<quote>
<bf>VGA Wonder series:</bf>  18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6
</quote><quote>
<bf>    Mach32 series:</bf>      68800-3, 68800-6, 68800AX, 68800LX
</quote><quote>
<bf>    Mach64 series:</bf>      88800
</quote><p>
Some early Mach32 boards will not work with this driver because they do not
provide VGA Wonder functionality.  Also, early Mach8 boards will not work for
the same reason, unless the board also has a video controller from the VGA
Wonder series (or is connected to one through the VGA passthrough connector).
<p>
These boards are available with a variety of clock generators and RAMDACs.  See
the XF86Config section below for details.  These boards are available with or
without a mouse.  When they do have a mouse (ISA boards only), it is either a
proprietary ATIXL busmouse, or one that uses the Logitech busmouse protocol.
<p>
VGA Wonder V3 boards use a 18800 video controller and generate dot clocks with
crystals.  VGA Wonder V4 boards have a 18800-1 and also use crystals.  VGA
Wonder V5 boards also use a 18800-1, but have a 18810 clock generator.  VGA
Wonder+ boards use a 28800-2 and a 18810.  Other than these, ATI's board naming
convention (if it can be said that one exists) starts to fall apart.
<p>
<sect>What should I put in my XF86Config file?
<p>
The chipset will be automatically detected.  The chipset name for this driver
is "vgawonder".  If you specify "ati" or "mach64" instead, any clocks
specification in XF86Config will be ignored (which means the clocks will be
probed).  This is done to ensure you are aware that the clocks specification
for previous versions of the driver is not supported by this version.
<p>
The clocks line to be specified in your XF86Config depends on what the board
uses to generate dot clocks.
<p>
For all boards, one of the following clocks specifications (or an initial
subset thereof) can be used depending on what the board uses to generate dot
clocks:
<p>
Crystals (VGA Wonder V3 and V4 boards only):
<p>
<verb>
  Clocks  50.175  56.644   0.000  44.900  44.900  50.175   0.000  36.000
          25.088  28.322   0.000  22.450  22.450  25.088   0.000  18.000
          16.725  18.881   0.000  14.967  14.967  16.725   0.000  12.000
          12.544  14.161   0.000  11.225  11.225  12.544   0.000   9.000
</verb><p>
ATI 18810 clock generator:
<verb>
  Clocks  30.240  32.000  37.500  39.000  42.954  48.771   0.000  36.000
          40.000  56.644  75.000  65.000  50.350  56.640   0.000  44.900
          15.120  16.000  18.750  19.500  21.477  24.386   0.000  18.000
          20.000  28.322  37.500  32.500  25.175  28.320   0.000  22.450
          10.080  10.667  12.500  13.000  14.318  16.257   0.000  12.000
          13.333  18.881  25.000  21.667  16.783  18.880   0.000  14.967
           7.560   8.000   9.375   9.750  10.739  12.193   0.000   9.000
          10.000  14.161  18.750  16.250  12.586  14.160   0.000  11.225
</verb><p>
ATI 18811-0 and ATI 18812-0 clock generators:
<verb>
  Clocks  30.240  32.000 110.000  80.000  42.954  48.771  92.400  36.000
          39.910  44.900  75.000  65.000  50.350  56.640   0.000  44.900
          15.120  16.000  55.000  40.000  21.477  24.386  46.200  18.000
          19.955  22.450  37.500  32.500  25.175  28.320   0.000  22.450
          10.080  10.667  36.667  26.667  14.318  16.257  30.800  12.000
          13.303  14.967  25.000  21.667  16.783  18.880   0.000  14.967
           7.560   8.000  27.500  20.000  10.739  12.193  23.100   9.000
           9.978  11.225  18.750  16.250  12.588  14.160   0.000  11.225
</verb><p>
ATI 18811-1 and ATI 18811-2 clock generators:
<verb>
  Clocks 135.000  32.000 110.000  80.000 100.000 126.000  92.400  36.000
          39.910  44.900  75.000  65.000  50.350  56.640   0.000  44.900
          67.500  16.000  55.000  40.000  50.000  63.000  46.200  18.000
          19.955  22.450  37.500  32.500  25.175  28.320   0.000  22.450
          45.000  10.667  36.667  26.667  33.333  42.000  30.800  12.000
          13.303  14.967  25.000  21.667  16.783  18.880   0.000  14.967
          33.750   8.000  27.500  20.000  25.000  31.500  23.100   9.000
           9.978  11.225  18.750  16.250  12.588  14.160   0.000  11.225
</verb><p>
Mach32 and Mach64 owners should only specify up to the first 32 frequencies.
<p>
The possibilities for Mach64 boards also include the newer ATI 18818 clock
generator chip.  At bootup, video BIOS initialization can set up the 18818 to
generate two slightly different sets of dot clocks.  A way to duplicate this
behaviour in the driver has not yet been found.  In the meantime, one of the
following clocks specification can be used:
<p>
ATI 18818 clock generator (primary BIOS setting):
<verb>
  Clocks   0.000 110.000 126.000 135.000  50.350  56.644  63.000  72.000
           0.000  80.000  75.000  65.000  40.000  44.900  49.500  50.000
           0.000  55.000  63.000  67.500  25.175  28.322  31.500  36.000
           0.000  40.000  37.500  32.500  20.000  22.450  24.750  25.000
</verb><p>
ATI 18818 clock generator (alternate BIOS setting):
<verb>
  Clocks   0.000 110.000 126.000 135.000  25.175  28.322  31.500  36.000
           0.000  80.000  75.000  65.000  40.000  44.900  49.500  50.000
           0.000  55.000  63.000  67.500  12.588  14.161  15.750  18.000
           0.000  40.000  37.500  32.500  20.000  22.450  24.750  25.000
</verb><p>
Other clock generators that have been used on ATI boards (which can all be said
to be clones of one of the above) might generate non-zero frequencies for those
that are zero above, or vice-versa.
<p>
The order of the clocks *is* very important.  Mach32 and Mach64 owners should
note that this order is different than what they would use for the accelerated
servers.
<p>
A clock probe, done with the command "X -probeonly", will help you decide which
of the above to use for your particular board.  If the server consistently
reports that it has detected an unknown clock generator, please e-mail me the
stderr output.
<p>
Modes can be derived from the information in XFree86's doc directory.  If you
do not specify a "modes" line in the display subsection of the appropriate
screen section of your XF86Config, the driver will generate a default mode and
attempt to use it.  The timings for the default mode are derived from the
timings of the mode (usually a text mode) in effect when the server is started.
<p>
<sect> Upgrading from other releases<p>
If you have an Xconfig for XFree86 versions earlier than 2.1.1, or for the
alpha Mach64 server, you will need to change it to use it for this version.
Specifically, you should run the server with the -probeonly flag and the
the XF86Config derived from the Xconfig you used with the older XFree86.  This
will cause the clocks to be probed.  You should replace the XF86Config clocks
with the clocks reported by the probe.  You should then change the chipset
specification to "vgawonder".
<p>
You should not need to change your mode definitions except for those that are
already driving your monitor close to its tolerance limits.  You might need to
change the dot clock used to one with the next lower (or higher) frequency.
<p>

<sect> What is the history of the driver?<p>
The complete history of the driver is rather cloudy.  The following is probably
incomplete and inaccurate.
<p>
Apparently, <bf>Per Lindqvist</bf> (<it>pgd@compuram.bbt.se</it>)
first got an ATI driver working
with an early ATI card under X386 1.1a.  This original driver may have actually
been based on an non-functional ATI driver written by <bf>Roell</bf>.  Then
<bf>Doug Evans</bf>
(<it>dje@cygnus.com</it>) ported the driver to the ATI XL, trying in the process to make
the driver work with all other ATI cards.
<p>
<bf>Rik Faith</bf> (<it>faith@cs.unc.edu</it>) obtained the X11R4 driver from
Doug Evans in the
summer of 1992, and ported the code to the X386 part of X11R5.  This
subsequently became part of XFree86.
<p>
I (<bf>Marc La France</bf>) have since taken the driver over after Rik got
 rid of his
VGA Wonder card.
<p>
The major reference that was used was a manual from ATI:
<p>
"VGA WONDER Programmer's Reference"
<it>ATI Technologies</it>, 1991.
Release 1.3 -- Reference &num PRG28800-13
<p>
However, Chapter 11 (ATI 18800 ATI VGAWONDER) of George Sutty and Steve
Blair's "<em>Advanced Programmer's Guide to SuperVGAs</em>"
(Brady/Simon &amp; Schuster,
1990) was also useful.  Further, someone e-mailed Rik a random document from
the ATI BBS which was dated 3Jul91 and which may have been named
PROGINFO.DOC.
<p>

<sect> Miscellaneous notes<p>
There is still a problem with some 512k boards that causes a resolution that
uses more than 256k to be scrambled.
<p>
Dot clocks greater than 80MHz cannot be used as a way still needs to be
discovered to make the VGA Wonder controller do pixel multiplexing.
<p>
Support for more than 8bpp colour depth is pending proper RAMDAC handling.
<p>
Support for the ATI 18818 clock generator needs to be cleaned up.
<p>
Support for modes that use more than 1M of video memory is still incomplete.
<p>
Please e-mail any bug reports, comments, etc. to <bf>Marc Aurele La France
</bf>,
<it>tsi@ualberta.ca</it>
<p>

<verb>
$XConsortium: ati.sgml,v 1.1 95/01/06 20:29:55 kaleb Exp $
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/ati.sgml,v 3.2 1995/01/04 04:40:33 dawes Exp $
</verb>

</article>
