R6.6 is the Xorg base-lineXORG-MAIN

1 files changed, 464 insertions, 0 deletions

diff --git a/README.ati.sgml b/README.ati.sgml
new file mode 100644
index 0000000..24ec214
--- /dev/null
+++ b/README.ati.sgml
@@ -0,0 +1,464 @@
+<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN">
+<article>
+
+<!-- Title information -->
+
+<title>ATI Adapters README file
+<author>Marc Aurele La France
+<date>1998 January 28
+<abstract>
+This is the README for the XFree86 ATI driver included in this release.
+</abstract>
+
+<!-- Table of contents -->
+<toc>
+
+<!-- Begin the document -->
+
+<sect>Statement of intent<p>
+Generally speaking, the driver is intended for all ATI video adapters,
+providing maximum video function within hardware limitations.
+The driver is also intended to optionally provide the same level of support for
+generic VGA or 8514/A adapters.
+This driver is still being actively developed, meaning that it currently does
+not yet fully meet these goals.<p>
+The driver will provide
+<itemize>
+<item>accelerated support if an ATI accelerator is detected <it>and</it> the
+user has not requested that this support be disabled;  otherwise
+<item>accelerated support if a non-ATI 8514/A-capable adapter is detected
+<it>and</it> the user has requested such support;  otherwise
+<item>unaccelerated SuperVGA support if an ATI VGA-capable adapter is detected;
+otherwise
+<item>generic VGA support if a non-ATI VGA-capable adapter is detected
+<it>and</it> the user has requested such support.
+</itemize>
+Thus, the support provided not only depends on what the driver detects in the
+system, but also, on what the user specifies in the XF86Config file.
+See the "XF86Config specifications" section below for details.<p>
+If none of the above conditions are met, the ATI driver will essentially
+disable itself to allow other drivers to examine the system.<p>
+<sect>A note on acceleration<p>
+The meaning of "acceleration", as used in this document, needs to be clarified.
+Two of the many components in an accelerator are the CRT controller (CRTC) and
+the Draw Engine.
+This is in addition to another CRTC that, generally, is also present in the
+system (often in the same chip) and typically provides EGA, VGA or SuperVGA
+functionality.<p>
+A CRTC is the component of a graphics controller that is responsible for
+reading video memory for output to the screen.
+A Draw Engine is an accelerator component that can be programmed to manipulate
+video memory contents, thus freeing the CPU for other tasks.<p>
+When the VGA CRTC is used, all drawing operations into video memory are the
+responsibility of the system's CPU, i.e. no Draw Engine can be used.
+On the other hand, if the accelerator's CRTC is chosen to drive the screen,
+the Draw Engine can also be used for drawing operations, although the CPU can
+still be used for this purpose if it can access the accelerator's video
+memory.<p>
+Video acceleration refers to the programming of an accelerator's Draw Engine to
+offload drawing operations from the CPU, and thus also implies the use of the
+accelerator's CRTC.<p>
+<sect>Current implementation for ATI adapters<p>
+The driver currently supports the SuperVGA capabilities of all ATI adapters
+except some early Mach8 and Mach32 adapters that do not provide the required
+functionality.
+This support works for monochrome, 16-colour and 256-colour video modes, if one
+of the following ATI graphics controller chips is present:
+<verb>
+VGAWonder series:  18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6
+   Mach32 series:  68800-3, 68800-6, 68800AX, 68800LX
+   Mach64 series:  88800GX-C, 88800GX-D, 88800GX-E, 88800GX-F, 88800CX,
+                   264CT, 264ET, 264VT, 264GT (a.k.a. 3D Rage), 264VT-B,
+                   264VT3, 264GT-B (a.k.a. 3D Rage II), 264GT3 (a.k.a.
+                   3D Rage Pro)</verb>
+There is some support for the 264LT (ATI's recent entry into the laptop
+world), but it is untested.<p>
+The driver also supports 32K, 64K and 16M-colour modes on the 264xT series of
+adapters using the accelerator CRTC (but not the VGA CRTC).
+This support is as yet unaccelerated.<p>
+Adapters based on the above chips have been marketed under a rather large
+number of names over the years.  Among them are:
+<verb>
+VGAWonder series:  VGAWonder V3, VGAWonder V4, VGAWonder V5, VGAWonder+,
+                   VGAWonder XL, VGAWonder XL24, VGA Basic 16, VGA Edge,
+                   VGA Edge 16, VGA Integra, VGA Charger, VGAStereo F/X,
+                   VGA 640, VGA 800, VGA 1024, VGA 1024D, VGA 1024 XL,
+                   VGA 1024 DXL, VGA 1024 VLB
+    Mach8 series:  Graphics Ultra, Graphics Vantage, VGAWonder GT
+                   (None of the 8514/Ultra and 8514 Vantage series is
+                    supported at this time)
+   Mach32 series:  Graphics Ultra+, Graphics Ultra Pro, Graphics Wonder,
+                   Graphics Ultra XLR, Graphics Ultra AXO, VLB mach32-D,
+                   PCI mach32-D, ISA mach32
+   Mach64 series:  Graphics Xpression, Graphics Pro Turbo, Win Boost,
+                   Win Turbo, Graphics Pro Turbo 1600, Video Xpression,
+                   3D Xpression, Video Xpression+, 3D Xpression+,
+                   All-In-Wonder, All-In-Wonder PRO, 3D Pro Turbo, ATI-TV,
+                   XPERT@Play, XPERT@Work, XPERT XL</verb>
+VGAWonder, Mach8 and Mach32 ISA adapters are available with or without a
+mouse.<p>
+These adapters are available with a variety of clock generators and RAMDACs.
+The 264xT series of chips are integrated controllers, meaning that they include
+a programmable clock generator and a RAMDAC.
+See the "XF86Config specifications" section below for details.<p>
+This driver still does not provide support for accelerated drawing to the
+screen.
+This means that all drawing is done by the CPU, rather than by any accelerator
+present in the system.
+This can make opaque moves, for example, quite "jerky".
+Thus, given that IBM 8514/A and ATI Mach8 do not allow CPU access to their
+frame buffer, the driver will currently ignore these accelerators.
+Most Mach32 adapters provide both accelerated function and VGA functionality,
+but the driver currently only uses the VGA.<p>
+The driver *does* however support the accelerator CRTC present in all ATI
+Mach64 adapters.
+For 256-colour, and higher depth modes, this support will be used by default,
+although an XF86Config option can be specified to use the SuperVGA CRTC
+instead.
+A linear video memory aperture is also available in 256-colour and higher depth
+modes and enabled by default if a 264xT controller is detected or, on 88800
+controllers, if the accelerator CRTC is used.
+XF86Config options are available to disable this aperture, or (on non-PCI
+adapters) enable it or move it to some other address.<p>
+<sect>Current implementation of generic VGA support for non-ATI adapters<p>
+Support for generic VGA with non-ATI adapters is also implemented, but has
+undergone only limited testing.
+The driver will intentionally disallow the use of this support with ATI
+adapters.
+This support must be explicitly requested through an XF86Config ChipSet
+specification.
+This prevents the current generic driver from being disabled.<p>
+This driver's generic VGA support is intended as an extension of that provided
+by the current generic driver.
+Specifically, within the architectural bounds defined by IBM's VGA standard,
+this driver will allow the use of any 256-colour mode, and any dot clock
+frequencies both of which allow for many more mode possibilities.<p>
+The driver will enforce the following limitations derived from IBM's original
+VGA implementation:
+<itemize>
+<item>There can only be a set of four (non-programmable) clocks to choose from.
+<item>Video memory is limited to 256kB in monochrome and 16-colour modes.
+<item>Video memory is limited to 64kB in 256-colour modes.
+<item>Interlaced modes are not available.
+</itemize>
+<sect>XF86Config specifications<p>
+Except for clocks, the driver does not require any XF86Config specifications
+of its own for default operation.
+The driver's behaviour can however be modified by the following
+specifications.<p>
+<sect1>ChipSet "name"<p>
+The default ChipSet name for this driver is "ati".<p>
+If "ativga" is specified instead, the driver will not use any ATI accelerator
+CRTC it detects, relying instead on any detected ATI VGA CRTC to provide the
+screen image.<p>
+A ChipSet name of "ibmvga" enables the driver's generic VGA support, but only
+for non-ATI adapters.
+If an ATI adapter is detected, the driver will operate as if "ativga" had been
+specified instead.<p>
+For compatibility with other XFree86 servers, both past and present, that
+support ATI adapters, the driver also recognizes "vgawonder", "mach8", "mach32"
+and "mach64" as chipset names.
+In this version of the driver, all such names are equivalent to "ati".
+In some future release, each name will have a different meaning to be
+documented at that time.<p>
+<sect1>Clocks<p>
+For the purpose of specifying a clock line in your XF86Config, one of four
+different situations can occur, as follows.<p>
+Those configuring the driver's generic VGA support for a non-ATI adapter,
+can skip ahead to the "Clocks for non-ATI adapters" section below.
+Those <it>not</it> trying to configure the driver for a Mach64 adapter, can
+skip ahead to the "Clocks for fixed clock generators on ATI adapters" section
+below.<p>
+The very earliest Mach64 adapters use fixed (i.e. non-programmable) clock
+generators.
+Very few of these (mostly prototypes) are known to exist, but if you have one
+of these, you can also skip ahead to the "Clocks for fixed clock generators on
+ATI adapters" section below.<p>
+The two cases that are left deal with programmable clock generators, which are
+used on the great majority of Mach64 adapters.<p>
+If you are uncertain which situation applies to your adapter, you can run a
+clock probe with the command "X -probeonly".<p>
+<sect2>Clocks for supported programmable clock generators<p>
+At bootup, video BIOS initialization programmes an initial set of frequencies.
+Two of these are reserved to allow the setting of modes that do not use a
+frequency from this initial set.
+One of these reserved slots is used by the BIOS mode set routine, the other by
+the particular driver used (e.g. MS-Windows, AutoCAD, X, etc.).
+The clock numbers reserved in this way are dependent on the particular clock
+generator used by the adapter.<p>
+The driver currently supports all programmable clock generators known to exist
+on Mach64 adapters.
+In this case, the driver will completely ignore any XF86Config clock
+specification, and programme the clock generator as needed by the modes used
+during the X session.<p>
+<sect2>Clocks for unsupported programmable clock generators<p>
+This case is unlikely to occur, but is documented for the sake of
+completeness.<p>
+In this situation, the driver will probe the adapter for clock frequencies
+unless XF86Config clocks are already specified.
+In either case, the driver will then attempt to normalize the clocks to one of
+the following specifications:
+<verb>
+BIOS setting 1:
+
+  Clocks   0.000 110.000 126.000 135.000  50.350  56.640  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.180  28.320  31.500  36.000
+           0.000  40.000  37.500  32.500  20.000  22.450  24.750  25.000</verb>
+<verb>
+BIOS setting 2:
+
+  Clocks   0.000 110.000 126.000 135.000  25.180  28.320  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.590  14.160  15.750  18.000
+           0.000  40.000  37.500  32.500  20.000  22.450  24.750  25.000</verb>
+<verb>
+BIOS setting 3:
+
+  Clocks   0.000   0.000   0.000   0.000  25.180  28.320   0.000   0.000
+           0.000   0.000   0.000   0.000   0.000   0.000   0.000   0.000
+           0.000   0.000   0.000   0.000  12.590  14.160   0.000   0.000
+           0.000   0.000   0.000   0.000   0.000   0.000   0.000   0.000</verb>
+If the driver matches the clocks to the third setting above, functionality will
+be *extremely* limited (assuming the driver works at all).<p>
+<sect2>Clocks for fixed clock generators on ATI adapters<p>
+This section applies to all ATI adapters except all but the very earliest
+Mach64's.<p>
+One of the following clocks specifications (or an initial subset thereof) can
+be used depending on what the adapter uses to generate dot clocks:
+<verb>
+Crystals (VGA Wonder V3 and V4 adapters only):
+
+  Clocks  50.000  56.644   0.000  44.900  44.900  50.000   0.000  36.000
+          25.000  28.322   0.000  22.450  22.450  25.000   0.000  18.000
+          16.667  18.881   0.000  14.967  14.967  16.667   0.000  12.000
+          12.500  14.161   0.000  11.225  11.225  12.500   0.000   9.000</verb>
+<verb>
+ATI 18810 clock generator:
+
+  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>
+<verb>
+ATI 18811-0 and ATI 18812-0 clock generators:
+
+  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>
+<verb>
+ATI 18811-1 and ATI 18811-2 clock generators:
+
+  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>
+Mach32 and Mach64 owners should only specify up to the first 32 frequencies.<p>
+Other clock generators that have been used on ATI adapters (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, although the driver will reorder
+the clocks if it deems it appropriate to do so.
+Mach32 and Mach64 owners should note that this order is different than what
+they would use for the accelerated servers.<p>
+<sect2>Clocks for non-ATI adapters<p>
+If no clocks are specified in the XF86Config, the driver will probe for four
+clocks, the second of which will be assumed to be 28.322MHz.
+You can include up to four clock frequencies in your XF86Config to specify the
+actual values used by the adapter.
+Any more will be ignored.<p>
+<sect1>Option "nolinear"<p>
+By default, the driver will enable a linear video memory aperture for
+256-colour and higher depth modes if it is also using a Mach64 accelerator CRTC
+or an integrated Mach64 graphics chip.
+This option disables this linear aperture.
+Currently, this also disables support for more than 256 colours.<p>
+<sect1>MemBase address<p>
+This specification is only effective for non-PCI Mach64 adapters, and is used
+to override the CPU address at which the adapter will map its video memory.
+Normally, for non-PCI adapters, this address is set by a DOS install utility
+provided with the adapter.
+The MemBase option can also be used to enable the linear aperture in those
+cases where ATI's utility was not, or can not be, used.<p>
+For PCI adapters, this address is determined at system bootup according to the
+PCI Plug'n'Play specification which arbitrates the resource requirements of
+most devices in the system.
+This means the driver can not easily change the linear aperture address.<p>
+<sect1>Modelines<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>Known problems and limitations<p>
+There are several known problems or limitations related to the XFree86 ATI
+driver.
+They include:<p>
+<itemize>
+<item>A number of system lockups and blank screens have been reported when
+using PCI Mach64 adapters.
+The great majority of these problems have been found to be due to system
+aspects that are unrelated to this driver.
+As of this writing, these problems can be divided into three general areas:<p>
+Improper mouse protocol specification with some recent mice.
+Try different protocol specifications or another mouse.<p>
+A system conflict with APM.
+This problem is Linux-specific.
+There is a bug in kernels 2.0.31 or earlier that prevents proper APM operation.
+Upgrade to a more recent kernel or disable APM support.<p>
+The TV port on some Mach64 adapters needs to be disabled using an ATI utility
+that might or might not be supplied with the adapter.
+This problem is currently under investigation.
+<item>When using a Mach64's accelerator CRTC, the virtual resolution must be
+less than 8192 pixels wide.
+The VGA CRTC further limits the virtual resolution width to less than 4096
+pixels, or to less than 2048 pixels for adapters based on 18800's (with 256kB
+of memory) and on Mach64 integrated controllers.
+These are hardware limits that cannot be circumvented.
+<item>Virtual resolutions requiring more than 1MB of video memory (256kB in the
+monochrome case) are not supported by the VGA CRTC on 88800GX and 88800CX
+adapters.
+This is a hardware limit that cannot be circumvented.
+<item>Due to hardware limitations, doublescanned modes are not supported by the
+accelerator CRTC in 88800GX, 88800CX, 264CT and 264ET adapters.
+<item>Monochrome interlaced modes are not supported on 18800-x and 28800-x when
+using a virtual resolution that is 2048 pixels or wider.
+This is yet another hardware limitation that cannot be circumvented.
+<item>Video memory banking does not work in monochrome and 16-colour modes on
+18800 and 18800-1 adapters.
+This appears to be another hardware limit, but this conclusion cannot be
+confirmed at this time.
+The driver's default behaviour in this case is to limit video memory to 256kB.
+<item>The default mode does not work on the more recent Mach64 adapters.
+This problem is caused by the driver's attempt to use an incorrect dot clock
+for the mode.
+This will be fixed in a future release by reading the programmable clock
+generator's registers to determine the actual clock used by the mode.
+<item>Most XFree86 servers assume that the video state on entry to the server
+is a text mode.
+This assumption is known to cause problems on operating systems which invoke
+the server from a graphics mode.
+DBCS versions of OS/2, primarily used in Asia, are examples of such operating
+systems.
+The solution, for now, is to somehow coerce the OS to invoke the server from a
+text mode.
+This driver has been changed to simply assume the mode on entry uses the
+adapter's VGA CRTC (in text or graphics modes).
+While this action alleviates the problem somewhat, it does not completely solve
+it, as the server could still be invoked from an accelerator mode.
+To properly fix this problem for all XFree86 servers is a large project, and
+will probably not get done anytime soon.
+<item>Video memory corruption can still occur during mode switches on 18800 and
+18800-1 adapters.
+Symptoms of this problem include garbled fonts on return to text mode, and
+various effects (snow, dashed lines, etc) on initial entry into a graphics
+mode.
+In the first case, the workaround is to use some other means of restoring the
+text font.
+On Linux, this can be accomplished with the kbd or svgalib packages.
+In the second case, xrefresh(1) will usually clean up the image.
+No solution to this problem is currently known.
+<item>There is some controversy over what the maximum allowed clock frequency
+should be on 264xT adapters.
+For now, clocks will, by default, be limited to 135MHz, 170MHz, 200MHz or
+230MHz, depending on the specific controller.
+This limit can only be increased (up to a driver-calculated absolute maximum)
+through the DACSpeed specification in XF86Config.
+Be aware however that doing so is untested and might damage the adapter.
+<item>Except as in the previous item, clocks are limited to 80MHz on most
+adapters, although many are capable of higher frequencies.
+This will be fixed in a future release.
+</itemize>
+Support for the following will be added in a future release:
+<itemize>
+<item>Mach32 accelerator's CRTC.
+This support is the first step towards accelerated support for Mach32's,
+Mach8's, 8514/A's and other clones.
+<item>Colour depth greater than 8, where permitted by the hardware.
+<item>Mach64, Mach32, Mach8 and 8514/A Draw Engines.
+<item>Hardware cursors.
+</itemize>
+Support, through this driver, for 3D acceleration, "TV in a window" and video
+capture, as implemented in some ATI adapters, is still in exploratory stages.
+There is currently no framework within an XFree86 server for these functions,
+although one is in the final stages of development.
+Also, ATI has not yet released a register-level specification for these, except
+under non-disclosure agreements.<p>
+<sect>Reporting problems<p>
+If you are experiencing problems that are not already recorded in this
+document, first ensure that you have the latest current release of this driver
+and XFree86.
+Check the server's stderr output and <htmlurl
+name="ftp://ftp.xfree86.org/pub/XFree86"
+url="ftp://ftp.xfree86.org/pub/XFree86"> if you are uncertain.<p>
+Secondly, please check XFree86's doc directory for additional information.<p>
+Thirdly, do not forget to read <htmlurl name="http://www.xfree86.org/FAQ"
+url="http://www.xfree86.org/FAQ">.<p>
+Fourth, a scan through the comp.windows.x.i386unix and comp.os.linux.x
+newsgroups using your favorite archiving service can also prove useful in
+resolving problems.<p>
+If you are still experiencing problems, you can send me e-mail at
+<it>tsi@ualberta.ca</it>.
+Please be as specific as possible when describing the problem(s), and include
+an unedited copy of the server's stderr and the XF86Config file used.<p>
+<sect>Driver history<p>
+The complete history of the driver is rather cloudy.
+The following is more than likely to be incomplete and inaccurate.<p>
+Apparently, Per Lindqvist first got a driver working with an early ATI adapter
+under X386 1.1a.
+This original driver might have actually been based on a non-functional ATI
+driver written by Thomas Roell (currently of Xi Graphics).<p>
+Then Doug Evans (<it>dje@cygnus.com</it>) added support for the ATI VGA Wonder
+XL, trying in the process to make the driver work with all other ATI adapters
+available at the time.<p>
+Rik Faith (<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 (Marc Aurele La France) took over development and maintenance of the driver
+in the fall of 1993 after Rik got rid of his VGA Wonder card.<p>
+<sect>Driver versions<p>
+Due to the introduction of loadable drivers in an upcoming XFree86 release, it
+has become necessary to track driver versions separately.
+With this release of the driver, I am introducing the following version
+numbering scheme.<p>
+Version 1 of this driver is the one I inherited from Rik Faith.
+This is the version found in XFree86 2.0 and 2.1.<p>
+Version 2 is my first rewrite of this code which only ended up being a
+partially unsuccessful attempt at generalizing the driver for all VGA Wonder,
+Mach32, and early Mach64 adapters.
+Various releases of this version of the driver can be found in XFree86 2.1.1,
+3.1, 3.1.1 and 3.1.2.<p>
+Version 3 represents my second rewrite (although a rather lame one as rewrites
+go).
+Into version 3, I introduced clock programming for Mach64 adapters and merged
+in the old ati_test debugging tool.
+This is the version found in XFree86 3.2, 3.3 and 3.3.1.<p>
+Version 4 is a rather major restructuring of version 3, which became larger
+than I could comfortably handle in one source file.
+This version will make it quite a bit easier to introduce new function such as
+acceleration, additional colour depths, and so on.
+This is the version found in XFree86 3.3.2.<p>
+<verb>
+$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/ati.sgml,v 3.15.2.2 1998/02/01 16:04:54 robin Exp $
+
+
+
+
+
+$Xorg: ati.sgml,v 1.3 2000/08/17 19:51:06 cpqbld Exp $
+</verb>
+</article>