A few comments about the Mach32 driver.

Warning I got a few reports about AST systems with onboard Mach32.
They do feature an incompatible EEPROM setup, but I think I got around
that. Nevertheless on none of the systems I heard of , svgalib-mach32 works.
Since original ATI Mach32 demos and tools don't works as well I've to claim
that the Mach32 on these AST systems does not conform to ATI's Mach32 docs.
I have no idea and docs on how to make these work, sorry. If you find
patches how to make svgalib-mach32 run on your AST on motherboard Mach32
tell me, I'll happily include them. Otherwise, sorry I tried allready
everything I could think off but to no avail.

[HH: If is there is a problem with the particular card you have, compile
and run the utility in the Mach32/ directory that reports all information
stored in the EEPROM of the card.  Send the output to Michael.  This is
also useful if you need a lot of options (e.g. clocks on new models?) to
get it to work so that this can be done automatically in future versions.]

WARNING! The Mach32 driver needs to know correct clock frequencies for graceful
DAC configuration.  Wrong clocks may damage your card!  However this version
contains code for automatic clock detection.  Since clock detection is time
critical, please do it on a completely idle system.  Then put the printed
out clocks line in your libvga.config.  The driver can do this for you too.
After that you can restart whatever svgalib program you used and you are
set.  If you already put a clocks line in your config by hand, comment it
out to have the driver check your clocks.

Since clock probing is time critical, values differ from time to time, you
may try it multiple times and see which values seem to be most exact.  You
can also compare them with the standard clock chips for Mach32 cards in
README.config

Some statements are copied from Xfree86.  The clock detection code is almost
just copied.  So I repeat here the copyright statements for these parts:

Copyright 1992 by Orest Zborowski <obz@Kodak.com>
Copyright 1993 by David Wexelblat <dwex@goblin.org>

Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the names of Orest Zborowski and David Wexelblat 
not be used in advertising or publicity pertaining to distribution of 
the software without specific, written prior permission.  Orest Zborowski
and David Wexelblat make no representations about the suitability of this 
software for any purpose.  It is provided "as is" without express or 
implied warranty.

OREST ZBOROWSKI AND DAVID WEXELBLAT DISCLAIMS ALL WARRANTIES WITH REGARD 
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND 
FITNESS, IN NO EVENT SHALL OREST ZBOROWSKI OR DAVID WEXELBLAT BE LIABLE 
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.
Copyright 1993 by Kevin E. Martin, Chapel Hill, North Carolina.

Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of Thomas Roell not be used in
advertising or publicity pertaining to distribution of the software without
specific, written prior permission.  Thomas Roell makes no representations
about the suitability of this software for any purpose.  It is provided
"as is" without express or implied warranty.

THOMAS ROELL, KEVIN E. MARTIN, AND RICKARD E. FAITH DISCLAIM ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHORS
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Author:  Thomas Roell, roell@informatik.tu-muenchen.de

Rewritten for the 8514/A by Kevin E. Martin (martin@cs.unc.edu)
Modified for the Mach-8 by Rickard E. Faith (faith@cs.unc.edu)
Rewritten for the Mach32 by Kevin E. Martin (martin@cs.unc.edu)

And here is my own copyright:

This driver is free software; you can redistribute it and/or
modify it without any restrictions. This library is distributed
in the hope that it will be useful, but without any warranty.

Copyright 1994 by Michael Weller

Email addresses as of this writing:

eowmob@exp-math.uni-essen.de mat42b@aixrs1.hrz.uni-essen.de
eowmob@pollux.exp-math.uni-essen.de

MICHAEL WELLER DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL MICHAEL WELLER BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Anyway the driver should allow you to use any of the graph-modes
your Mach32 card supports.  Note that there is no support for
<8bpp modes and that I won't ever implement that because I don't see
any reason for doing so.  All standard VGA-modes are of course 
supported.. (by using of the standard VGA driver routines).

If you configured your Mach32 for a memory aperture and it is
at least as big as the memory of your card (that is, not a 1MB
memory aperture for a 2MB card) support for linear frame buffer
access of svgalib is given.

Auto detection of the Mach32 seems not to work on all cards.  That's
really strange since I got the code from the X people.  It should be OK
regardless of my docs.  Well, I fixed that (hopefully).  Actually
the bug was found by Daniel Lee Jackson (djackson@ichips.intel.com).
(Thanks again.. It was so silly...  I would have never found it)
If you still have problems just put a chipset Mach32 in your config file.

Note that at least my VRAM card seems to be peculiar about logical
linewidths.  From my experience a multiple of 64 pels is needed.
Your mileage may vary.  Use the config file options to adjust it
and tell me if your card needs a different value.  Include the name and
model number of the card and what the correct numbers should be.  This
is so that I can correct the autoconfig driver.

If some svgalib application has problems, note that you can
force the logical linewidth to the default value from the
configfile.  Probably this will lead to glitches in some 800x600
resolutions.  You can inhibit these resolutions from the configfile
as well.  Apropos glitches, I found no guidelines as to what clockrates
to use due to memory restrictions.  I adjusted the driver, so that
I get a stable pic in all resolutions.  However sometimes the screen
is disturbed by heavy video memory accesses.  If you don't like that,
reduce the clocks used with the maxclock16 or maxclock24 command, resp.
This may of course lead to none of the predefined modes being used.
Then you can try to define your own mode via the define command.

If you get some flicker or heavy noise on your screen, some fine tuning may
be needed.  My docs didn't give me hints as to what each card can stand.
Especially DRAM cards may give problems (I've VRAM).  In that case, use the
fine tuning config commands and send me your results along with the output
of Mach32info.  Then I can include them in my next release.

Fine-tuning commands:

First you should think about the maxclock commands to reduce pixel clocks
used for each mode depth.

Especially important for DRAM cards is the video FIFO depth used to queue
memory values for writing to the screen.  Here is a command to set this
value for the 8bpp modes:

vfifo8 number

where number is 0-15.  The default is 6 now.

Since vfifo is of some impact to the speed of the card, tell me the
lowest setting that satisfies your card.

For 16/24/32 modes, there are non-zero values preset from internal tables and
the EEPROM, however you can enforce minimal vfifo values with:

vfifo16 number
vfifo24 number
vfifo32 number

blank number

where number is 4*pixel_delay+blank_adjust.
where pixel_delay and blank_adjust are 0..3.  Pixel_delay delays pixels
before they are sent to the DAC and blank_adjust adjusts the blank pulse
for type 2 DAC's.  blank should be set correctly for each DAC type
automatically.  So use it only as a last resort.

latch number

where number is the sum of one or more of:

  128: VRAM serial delay latch enable, DRAM latch bits 63:0 enable.
 4096: Latch video memory data.
 8192: Memory data delay latch enable for data bits 63:0
16384: Memory full clock pulse enable

Default is to switch all settings on. (they are on on my card by default anyway..)

Note that these commands may vanish again once they are no longer needed for
debugging purposes.

There is no 320x200 mode in the EEPROM of the Mach32 at all, however
I defined one in the default config file for you.  This is the best
thing I could get up on my card/screen.  Note that it will probably
have big borders on your screen, and black lines in between the lines.
This is because of the lack of low clocks <16 on the Mach32 and the
lack of a line doubling mode as VGA has.  The Mach32 is not intended
for such low resolutions.  If you find a better mode or have an idea
please let me know.

Ah yes, and apropos EEPROM, I figured out how to read out the Mach32
EEPROM.  I did it by disassembling the BIOS routine mentioned in the
docs.  I then redid it in C.  The driver will use everything it finds
there.

Use the Mach32 install tools (they should have reached you together with
your Mach32 VGA card) to setup your card/monitor combo correctly.
The monitor setting from the config file (or default of 35kHz or something)
will be obeyed by the driver anyway (for safety!).

As you probably know already, accessing the EEPROM causes some screen
flickering.  If this annoys you (or even worse your monitor) have a look
at the mach32eeprom command.  This allows you to put the data from the
EEPROM into a file and which can be read whenever it is required.
Give a filename where the EEPROM contents are once
saved and then just read out.

Don't even think about changing the contents of the file.  (There is
an easyly faked checksum in it.)  Anyway the driver ensures (hopefully)
that no damage can be caused.

This is also true for clock probing (in fact at a much higher impact)
Probed clocks have to be given in the libvga.config file. The driver is
able to do the clock probing and saving in the config file itself
(usually).

Also if some mode is not well aligned on your screen or you don't like
it's sync frequency, consider using the Mach32 install utility (setup for
custom monitor) and set one up interactively.  If there is no valid faster
(higher VSYNC) standard mode given in the EEPROM the driver will use
that mode.. you will find that this is fun compared with calculating video
timings for Xconfig / svgalib.config. 

However the install utility does restrict the maximum pixel depth for
custom modes sometimes unneeded hard and the driver obeys that
(Hmm.. actually it should be smart enough to decide itself which pixel
depth it can use in that mode..).
Since usually the standard modes are only slightly shifted to one side
a file with the config commands representing the standard modes is given
in mach32 mach32.std-modes. You can use these as a starting point.

But here are some real problems:

EEPROM woes:
I got 2 reports of people having problems with incorrect EEPROM checksums.
Both had motherboards with onboard Mach32 VGA's from AST.  I guessed a checksum
algorithm from those reports and put this in the code in addition to the
standard ATI style.  Still I got a report of someone whose EEPROM was completely
empty.  If you have problems with checksums send me the output of Mach32 and
I'll see what I can do.

By default svgalib writes a complaining message and ignores the contents.
You can have svgalib ignore the checksum and contents with the config command:

mach32eeprom ignore

Then you can decide to use the partial info that is still in it.  Use:

mach32eeprom ignore usetimings

To use the videomodes that are defined in the EEPROM (if none better are
known by the driver).  This is usually safe, because the driver knows
which modes are safe for your hardware (if clocks, monitor and dac are
configured correctly).  You can also allow the driver to use the
configuration for the linear frame buffer in the EEPROM:

mach32eeprom ignore useaperture         (or)
mach32eeprom ignore usetimings useaperture

However I discourage this because the driver will enable what the EEPROM
says about the aperture.  Use mach32info to check this is safe.  It may be
better to use 'setuplinear' to set up a 4MB aperture at a free address range.

Due to poor design, Xfree86 insists on setting up the aperture itself.  It
doesn't reset the original settings at a VC switch once it runs.  You
should not start X for the first time after a boot as long as an svgalib
application is running.  This will result in pre X values being restored at a VC
switch by svgalib.  If you use svgalib and XF86_Mach32 together, run X first or
at least do not start it while any svgalib appl. is still running.  After X was
started once you can use svgalib and X in all combinations w/o any problems.  Xfree
uses whatever address is given in MEM_CFG for a 4MB aperture.  This is IMHO
a dangerous bug as some systems may work only with a 1MB aperture.

However, usage of a correct EEPROM circumvents any such problems. If you
cannot use that, use mach32info to find the address in MEM_CFG.  Then, IF
IT IS A SENSEABLE SETTING FOR YOUR SYSTEM, enable an 4MB aperture at that
address with 'setuplinear'.  ENSURE THAT NO OTHER CARD OR MEMORY USES THE
ADDRESS RANGE YOU CHOOSE.

This version now has support for all accelerator functions of svgalib.
However they were intended for use with the cirrus chips.  It may happen
that at runtime they find they cannot emulate the function actually
requested.  Then you should disable the corresponding blit function
(at least for that application) with the blit config command.

Data transfer between the host and the Mach32 is normally via I/O.  This
proved to be pretty slow.  If a big enough aperture is available, a simple
memory copy is used instead.  This is usually much faster.  You can change
which method is used with the blit command.  This I/O option affects only
'imageblt'.  The other functions are incredible fast.

For type 2 DACS, there is support for 8 bit per color (instead of the normal 6)
in the RGB triple in the color lookup table of the 256 color modes.  This
can be enabled by an application, if it supports it.  The 'testaccel'
demo uses it if supported by your hardware.

Type 1 and 4 Dacs need different clock frequencies for high colormodes.
For 32K/64K colormodes the frequencies have to be doubled and for
16M colors (type 4 only) they have to be tripled.  I followed the ATI scheme
and did this internally.  However this means that for 32K/64K you can use
only clocks for which the doubled frequencies can be generated as well.

In addition (in complete contrast to my original ATI docs) RAMDAC 4 does not support
RGB with blue first but only with red first. This required special handling and me
adding a bunch of funcs to all modules of svgalib and vgagl. The added functions are
of lower performance than the usual functions. However most data has to be completely
mangled, so I doubt that it will go much faster. Sorry. In addition since I may have
forgotten to port some parts or even confused things. About bugs in the gl and drawing
libs, please ask Harm. But then I'm able to emulate a BGR ramdac on my card, so I may
even be able to reproduce your problems. Sigh...

This is no hard restriction as the 16 clocks of the Mach32 can be divided by 2.
Thus if you setup some mode yourself try to use the divided clocks.
It is some restriction for 16M colors.  ATI themself only support 25MHz
(640x480) here by use of a 75MHz clock.  Depending on your clock chip other
values may be usable as well.  Even the doubled/tripled clocks have to be less
than the magic 80 MHz.  However the driver does all this himself.  It may just
happen that some of the predefined or one of your handmade mode-timings
can't be used because the clock that is used cannot be doubled/tripled.
Even though there is already some tolerance in the driver you may fix that by
slighty changing the clock values that you set with the clocks command.  But
note that this will as well affect the ability of the driver to calculate
video timings and thus it ability to check the monitor and DAC safety
restrictions.

I heard about a bug in some ATI chipsets returning wrong memory amounts
configs. (But cannot confirm that)

Note that you can enforce correct identification from the config file.
Have a look at mach32.h for correct values.

Some programs (that set the correct flag) will show a

Using Mach32 #0 (#1M at #2M (#3), #4K mem, DAC #5)

line.  This will show up in testlinear.. etc.. but will probably scroll
away when you use vgatest.

In this line:
"#0" is the version of the driver (as of my counting, not the svgalib
     version).
"#1" is the size of the memory aperture.  It can be 1 or 4 (1 will lead
     to not using the linear aperture if your card has more than 1MB
     memory, however applications can still use the 1MB aperture and page 
     the video memory through it in 1MB steps).  "#1" can also be "no"
     if no aperture is setup at all.
"#2" is the base address of the aperture in MB.
"#3" is "autodetect" if the aperture was setup this way already when the
     program started.  It is "setup" when the the setting was enforced with a
     setuplinear config command.  It is "EEPROM" when no aperture was detected
     but parameters to set it up were found in the EEPROM.
"#4" is the amount of memory the card reported to have.
"#5" is the type of the DAC (0-5 are known) that was detected.
If #4, #5 and/or the chipset were enforced with "chipset" from the config-file
or the appropriate application function call a "forced" will be appended to
the line.

A final word: I have an ATI ULTRA PRO/2MB/EISA with a Type 2 DAC.
My monitor is an EIZO F550i-M.  Everything I tried worked on it like
a charm.  However I couldn't try it with other machines myself and esp.
other DAC's.  Fortunately the Type 2 DAC is the worst to code.  So I
will probably have gotten the other DAC's right.  But please be warned!

I did my very best to code the driver to support the other DAC's by
just reading the docs.  BUT I CAN'T DEFINITELY GIVE ANY GUARANTEE FOR
IT TO WORK OR EVEN NOT DAMAGING YOUR HARDWARE.  SO PLEASE BE CAREFUL!

Note that you will have to set the environment variable SVGALIB_MACH32
to ILLTRYIT if your DAC is not type 0, 2 or 4.  This will of course change
if no one with DAC not equal 0, 2 or 4 has serious problems.  If you have
a different DAC, making patches to support your card will be much more
helpful instead of just complaining.
If you have a different DAC that works well tell me as well sucht that I
can remove the need for SVGALIB_MACH32 in the next release.

Thank you for your audience and wishes you will enjoy this driver,

Michael Weller

eowmob@exp-math.uni-essen.de