ATI Adapters README file Marc Aurele La France 1999 June 23 Abstract This is the README for the XFree86 ATI driver included in this release. 1. Statement of intent Generally speaking, the driver is intended for all ATI video adapters, pro- viding 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. The driver will provide o accelerated support if an ATI accelerator is detected and the user has not requested that this support be disabled; otherwise o accelerated support if a non-ATI 8514/A-capable adapter is detected and the user has requested such support; otherwise o unaccelerated SuperVGA support if an ATI VGA-capable adapter is detected; otherwise o generic VGA support if a non-ATI VGA-capable adapter is detected and the user has requested such support. 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. If none of the above conditions are met, the ATI driver will essentially dis- able itself to allow other drivers to examine the system. 2. A note on acceleration The meaning of "acceleration", as used in this document, needs to be clari- fied. 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, gener- ally, is also present in the system (often in the same chip) and typically provides EGA, VGA or SuperVGA functionality. 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 accelera- tor component that can be programmed to manipulate video memory contents, thus freeing the CPU for other tasks. 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. 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. 3. Current implementation for ATI adapters 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 pre- sent: 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 (3D Rage), 264VT-B, 264VT3, 264VT4, 264GT-B (3D Rage II), 3D Rage IIc, 3D Rage Pro, 3D Rage LT, 3D Rage LT Pro, 3D Rage XL, 3D Rage XC, 3D Rage Mobility The driver also supports 32K, 64K and 16M-colour modes on the 264xT and 3D Rage series of adapters using the accelerator CRTC (but not the VGA CRTC). This support is as yet unaccelerated. The newer Rage 128 chips are not yet supported. Adapters based on the above chips have been marketed under a rather large number of names over the years. Among them are: VGAWonder series: VGAWonder V3, VGAWonder V4, VGAWonder V5, VGAWonder+, VGAWonder XL, VGAWonder XL24, VGAWonder VLB, VGA Basic, 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, WinBoost, WinTurbo, Graphics Pro Turbo 1600, Video Xpression, 3D Xpression, Video Xpression+, 3D Xpression+, 3D Charger, Video Charger, WinCharger, All-In-Wonder, All-In-Wonder PRO, 3D Pro Turbo, XPERT@Play, XPERT@Play 98, XPERT@Work, XPERT 98, XPERT LCD, XPERT XL VGAWonder, Mach8 and Mach32 ISA adapters are available with or without a mouse. These adapters are available with a variety of clock generators and RAMDACs. The 264xT and 3D Rage 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. 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 acceler- ators. Most Mach32 adapters provide both accelerated function and VGA func- tionality, but the driver currently only uses the VGA. 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 or 3D Rage 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. 4. Current implementation of generic VGA support for non-ATI adapters 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. This driver's generic VGA support is intended as an extension of that pro- vided 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. The driver will enforce the following limitations derived from IBM's original VGA implementation: o There can only be a set of four (non-programmable) clocks to choose from. o Video memory is limited to 256kB in monochrome and 16-colour modes. o Video memory is limited to 64kB in 256-colour modes. o Interlaced modes are not available. 5. XF86Config specifications Except for clocks, the driver does not require any XF86Config specifications of its own for default operation. The driver's behaviour can however be mod- ified by the following specifications. 5.1 ChipSet "name" The default ChipSet name for this driver is "ati". 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. 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. 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. 5.2 Clocks For the purpose of specifying a clock line in your XF86Config, one of four different situations can occur, as follows. 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 not trying to configure the driver for a Mach64 adapter, can skip ahead to the "Clocks for fixed clock generators on ATI adapters" section below. 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. The two cases that are left deal with programmable clock generators, which are used on the great majority of Mach64 adapters. If you are uncertain which situation applies to your adapter, you can run a clock probe with the command "X -probeonly". 5.2.1 Clocks for supported programmable clock generators At bootup, video BIOS initialization programmes an initial set of frequen- cies. 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. 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. 5.2.2 Clocks for unsupported programmable clock generators This case is unlikely to occur, but is documented for the sake of complete- ness. 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 specifica- tions: 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 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 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 If the driver matches the clocks to the third setting above, functionality will be *extremely* limited (assuming the driver works at all). 5.2.3 Clocks for fixed clock generators on ATI adapters This section applies to all ATI adapters except all but the very earliest Mach64's. One of the following clocks specifications (or an initial subset thereof) can be used depending on what the adapter uses to generate dot clocks: 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 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 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 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 VGAWonder VLB, VGA 1024 VLB, Mach32 and Mach64 owners should only specify up to the first 32 frequencies. 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. 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. 5.2.4 Clocks for non-ATI adapters 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. 5.3 Option "nolinear" 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. 5.4 MemBase address 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. 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. 5.5 Modelines 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. 6. Known problems and limitations There are several known problems or limitations related to the XFree86 ATI driver. They include: o 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: Improper mouse protocol specification with some recent mice. Try dif- ferent protocol specifications or another mouse. 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. o 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 inte- grated controllers. These are hardware limits that cannot be circum- vented. o 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. o Due to hardware limitations, doublescanned modes are not supported by the accelerator CRTC in 88800GX, 88800CX, 264CT and 264ET adapters. o 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. o 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. o 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. o 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 com- pletely solve it, as the server could still be invoked from an accelera- tor mode. To properly fix this problem for all XFree86 servers is a large project, and will probably not get done anytime soon. o 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. o There is some controversy over what the maximum allowed clock frequency should be on 264xT and 3D Rage 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. o 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. Support for the following will be added in a future release: o Mach32 accelerator's CRTC. This support is the first step towards accelerated support for Mach32's, Mach8's, 8514/A's and other clones. o Colour depth greater than 8, where permitted by the hardware. o Mach64, Mach32, Mach8 and 8514/A Draw Engines. o Hardware cursors. 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 development. Also, ATI has not yet released a register- level specification for these, except under non-disclosure agreements. 7. Reporting problems If you are experiencing problems that are not already recorded in this docu- ment, first ensure that you have the latest current release of this driver and XFree86. Check the server's stderr output and ftp://ftp.xfree86.org/pub/XFree86 if you are uncertain. Secondly, please check XFree86's doc directory for additional information. Thirdly, do not forget to read http://www.xfree86.org/FAQ. Fourth, a scan through the comp.windows.x.i386unix and comp.os.linux.x news- groups using your favourite archiving service can also prove useful in resolving problems. If you are still experiencing problems, you can send me e-mail at tsi@ual- berta.ca. 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. 8. Driver history The complete history of the driver is rather cloudy. The following is more than likely to be incomplete and inaccurate. 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). Then Doug Evans (dje@cygnus.com) 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. Rik Faith (faith@cs.unc.edu) obtained the X11R4 driver from Doug Evans in the summer of 1992 and ported the code to the X386 part of X11R5. This subse- quently became part of XFree86. 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. 9. Driver versions 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. 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. Version 2 is my first rewrite of this code which only ended up being a par- tially 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. 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. 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, addi- tional colour depths, and so on. This is the version found in XFree86 3.3.2, 3.3.3, 3.3.3.1, 3.3.3.2, 3.3.4, 3.3.6 and 3.3.6. Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/ati.sgml,v 3.15.2.6 1999/12/11 15:28:32 hohndel Exp $ $XConsortium: ati.sgml /main/9 1996/10/19 18:03:54 kaleb $