Add information about Compaq's funding for AGP accelerated read/draw pixelsX_4_0_99_1-20010319-preimport

support in the MGA driver.

1 files changed, 1102 insertions, 115 deletions

diff --git a/xc/programs/Xserver/hw/xfree86/doc/README.DRI b/xc/programs/Xserver/hw/xfree86/doc/README.DRI
index 85048b17d..b5e78abc9 100644
--- a/xc/programs/Xserver/hw/xfree86/doc/README.DRI
+++ b/xc/programs/Xserver/hw/xfree86/doc/README.DRI
@@ -1,115 +1,1102 @@
-Direct Rendering Infrastructure Alpha release
----------------------------------------------
-
-Patches for the final sample implementation (SI) of Precision Insight's
-Direct Rendering Infrastructure (DRI) have been submitted to XFree86.
-
-
-
-Please direct all comments about this release to glx@xfree86.org.
-
-
-
-
-* What comes with this release?
-
-  There are four main parts of this patch:
-
-  1. the client- and server-side DRI,
-  2. a 2D DDX driver for 3Dlabs' GMX2000,
-  3. an OpenGL client side direct rendering driver for the GMX2000, and
-  4. a generic kernel driver for Linux 2.2.x (x <= 10) and Linux 2.3.y (y
-     <= 8).
-
-  The DRI handles the communication and synchronization between the X
-  server, the client driver and the kernel driver.
-
-  The 3Dlabs XFree86 DDX driver has been enhanced to support the
-  GMX2000.  It has also been extended to communicate with and provide
-  callbacks for the DRI.
-
-  The client driver implements a subset of OpenGL.  The subset required
-  for id Software's Quake 2 was chosen to demonstrate the capabilities
-  of the DRI.  This driver communicates with the device by filling DMA
-  buffers and sending them to the kernel driver.  Note that the Gamma
-  chip implements OpenGL 1.1 in hardware, and therefore, does not use
-  the Mesa internals at this time.  However, support for the majority of
-  current generation of 3D hardware devices will require integration
-  with Mesa, so an example DRI driver using the Mesa software-only
-  pipeline was implemented (and is mostly complete for the alpha
-  release).
-
-  The generic kernel driver handles the allocation of the DMA buffers,
-  distribution of the buffers to the clients, sending the buffers to the
-  device, and the management of synchronization between the client
-  driver, the X server, and the kernel driver (this includes the device
-  lock and a shared memory region).  Note that hardware that does not
-  support DMA or that does support special synchronization methods will
-  only make use of a subset of these capabilities.
-
-* What changed between the alpha release and the sample implementation?
-
-  - Dynamic loading of the OpenGL client driver is implemented
-  - 3D client death while holding the drawable lock does not cause deadlock
-  - The kernel module works with Linux 2.2.x [x <= 10] and 2.3.y [y <= 8]
-  - A better authentication mechanism has been implemented
-  - XF86Config options for the DRI are supported
-
-* What are the known problems and/or limitations of the sample
-  implementation? 
-
-  Here are other problems that we did not have time to fix for the SI.
-  However, we and other open source developers could continue developing
-  and extending the DRI in follow-on projects.
-
-  - The X server seg faults due to a context switching bug when there
-    are 10 or more 3D clients running simultaneously
-  - A better DMA buffer queuing algorithm needs to be implemented
-  - A device specific shared memory region needs to be added to SAREA
-  - The DRI protocol request for the framebuffer layout needs to be
-    extended to support FB width and depth information (for 24 vs. 32
-    bpp, 8+24 layouts, etc)
-  - Direct rendering to a pixmap is not supported
-  - A more sophisticated texture management routine is required to
-    handle texture swapping efficiently
-  - Multi-threaded OpenGL clients are not supported
-  - glXCopyContext and glXUseXFont are not supported in the DRI
-  - SwapBuffers does not wait on vertical retrace
-  - Support wait for vertical retrace in kernel driver
-  - Handling overlays is not currently supported
-  - Integrate with DBE
-  - Completing the software-only Mesa example driver
-  - Completing the other OpenGL paths for the GMX2000
-  - Support for video modes other than 640x480 in both the GMX2000 2D
-    DDX driver and the 3D client driver
-  - More than minimal 2D acceleration of the GMX2000 2D DDX driver
-    should be implemented
-  - Implement finer grained locking scheme in X server to improve
-    interactivity
-  - Only grab the drawable lock and update the drawable stamp when a 3D
-    window is altered
-  - The viewport does not scale properly when a 3D window is resized
-  - Double buffered 3D windows are not clipped to the screen
-  - glXSwapBuffers is not clipped to the client's viewport
-  - Only one client is allowed to use texture memory
-  - glFinish does not wait until the HW completes processing the
-    outstanding DMA buffers
-  - Version numbers of the DDX and kernel driver are not verified
-  - Make lock available during SIGSTOP
-  - Make drmFinish work while holding the device lock
-  - Improve /proc/drm
-  - Improve documentation
-  - Improve example device-specific kernel driver (not used for SI)
-
-* Where can I get more information?
-
-  We have made our design and implementation documents available on our
-  website:
-
-      http://www.precisioninsight.com/piinsights.html
-
-  More documentation will be available with the SI release.
-
-* Where should I send comments?
-
-  Please send all comments and questions to the glx@xfree86.org list
+                               DRI User Guide
+
+          VA Linux Systems, Inc. Professional Services - Graphics.
+
+                              20 November 2000
+
+1.  Preamble
+
+1.1  Copyright
+
+Copyright © 2000 by VA Linux Systems, Inc.  All Rights Reserved.
+
+Permission is granted to make and distribute verbatim copies of this document
+provided the copyright notice and this permission notice are preserved on all
+copies.
+
+1.2  Trademarks
+
+OpenGL is a registered trademark and SGI is a trademark of Silicon Graphics,
+Inc.  Unix is a registered trademark of The Open Group.  The `X' device and X
+Window System are trademarks of The Open Group.  XFree86 is a trademark of
+The XFree86 Project.  Linux is a registered trademark of Linus Torvalds.
+Intel is a registered trademark of Intel Corporation.  3Dlabs, GLINT, and
+Oxygen are either registered trademarks or trademarks of 3Dlabs Inc. Ltd.
+3dfx, Voodoo3, Voodoo4, and Voodoo5 are registered trademarks of 3dfx Inter-
+active, Incorporated.  Matrox is a registered trademark of Matrox Electronic
+Systems Ltd.  ATI Rage is a registered trademark of ATI Technologies, Inc.
+All other trademarks mentioned are the property of their respective owners.
+
+2.  Introduction
+
+With XFree86 4.0 and the Direct Rendering Interface (DRI), hardware acceler-
+ated 3D graphics can be considered a standard feature on Linux workstations.
+Support for other operating systems, such as FreeBSD, is underway.
+
+This document describes how to use the DRI system and troubleshoot problems
+which may occur.  Readers should have a basic understanding of Linux, X and
+OpenGL.  See the resources section at the end for more documentation and
+software downloads.
+
+This document does not cover compilation or installation of XFree86 4.0.  It
+is assumed that you've already installed a Linux distribution which includes
+XFree86 4.0 or that you're an experienced Linux developer who has compiled
+the DRI for himself.  DRI download, compilation and installation instructions
+can be found at http://dri.sourceforge.net/DRIcompile.html
+
+Edits, corrections and updates to this document may be mailed to brianp@val-
+inux.com.
+
+3.  Supported Architectures & Hardware
+
+     "
+
+3.1  Architectures
+
+     "
+
+The Architectures currently supported by the DRI have grown from the initial
+Intel i386 based machines to now include, the Alpha Processor and the Sun
+SPARC machines.
+
+The build environment for both of these new architectures have a pre-build
+environment that will correctly build the DRI drivers and Mesa meaning no
+extra configuration is necessary to build the DRI for these architectures.
+
+3.1.1  Alpha Features
+
+     "
+
+On newer Alpha processors, it should be noted that a significant performance
+increase can be seen with the addition of the -mcpu= command that should be
+passed to GCC upon compilation. Dependent of the architecture of the proces-
+sor, for example -mcpu=ev6 will build specifically for the EV6 based AXP's,
+giving both byte and word alignment access to the DRI/Mesa drivers.
+
+Use this as an example of compiling with this extra speed.  In your host.def
+file that should reside in the xc/config directory, add the line.
+
+#define DefaultGcc2AxpOpt -O2 -mcpu=ev6
+
+Additional speed improvements to 3D rendering can be achieved by installing
+Compaq's Math Libraries (CPML) which can be obtained from the following URL.
+
+http://www.support.compaq.com/alpha-tools/software/index.html
+
+Once installed, you can set this option in your host.def to build against the
+CPML libraries.
+
+#define UseCompaqMathLibrary YES
+
+3.2  Graphics Hardware
+
+     "
+
+XFree86 4.0 (or later versions) includes 3D acceleration for the following
+graphics hardware:
+
+NOTE: This is a complete list of graphics hardware supported. It may not be
+supported on your platform.
+
+   o 3dfx:
+
+        o Voodoo5 5500
+
+        o Voodoo3 3500 TV
+
+        o Voodoo3 3000 AGP
+
+        o Voodoo3 3000 PCI
+
+        o Voodoo3 2000 AGP
+
+        o Voodoo3 2000 PCI
+
+        o Voodoo Banshee
+
+        o Velocity 100/200
+
+     There are many configurations of 3dfx cards on the market.  Not all have
+     been tested.
+
+   o Matrox:
+
+        o Matrox G200
+
+        o Matrox G400
+
+   o Intel i810
+
+        o i810
+
+        o i810-dc100
+
+        o i810e
+
+   o ATI Rage 128
+
+        o Rage Fury AGP
+
+        o Rage Magnum AGP
+
+        o XPERT 2000 AGP
+
+        o XPERT 128 AGP
+
+        o XPERT 99 AGP
+
+        o All-in-Wonder 128 AGP
+
+     The PCI versions of these cards also have minimal support.  Note that
+     there are also Rage 128 Pro based boards on the market, and these are
+     not yet supported.
+
+   o 3Dlabs Oxygen GMX 2000 (MX/Gamma based)
+
+Support for other hardware is underway.
+
+4.  Prerequisite Software
+
+   o The DRI is available in XFree86 4.0 and later.
+
+   o Some hardware drivers require specific versions of the Linux kernel for
+     AGP support, etc.  See section 10 for specifics.
+
+   o You DO NOT need to install Mesa separately.  The parts of Mesa needed
+     for hardware acceleration are already in the XFree86/DRI project.
+
+5.  Kernel Modules
+
+    "
+
+3D hardware acceleration requires a DRI kernel module that's specific to your
+graphics hardware.
+
+The DRI kernel module version must exactly match your running kernel version.
+Since there are so many versions of the kernel, it's difficult to provide
+precompiled kernel modules.
+
+While the Linux source tree includes the DRI kernel module sources, the lat-
+est DRI kernel sources will be found in the DRI source tree.
+
+See the DRI Compilation Guide for information on compiling the DRI kernel
+modules.
+
+XFree86 4.0.1 added automatic kernel module loading to the X server.  On
+Linux, the X server uses modprobe to load kernel modules.  In Linux 2.4.x the
+DRM kernel modules should be kept in /lib/modules/2.4.x/ker-
+nel/driver/char/drm/ for automatic loading to work.
+
+Optionally, DRM kernel modules can be loaded manually with insmod prior to
+starting the X server.
+
+You can verify that the kernel module was installed with lsmod, checking the
+X server startup log, and checking that /proc/dri/0 exists.
+
+6.  XF86Config file
+
+      "
+
+The XFree86 configuration file is usually found in /etc/X11/XF86Config.  This
+section describes the parts which must be specially set for the DRI.
+
+First, the XF86Config file must load the GLX and DRI modules:
+
+          Section "Module"
+          ...
+          # This loads the GLX module
+              Load       "glx"
+          # This loads the DRI module
+              Load       "dri"
+          EndSection
+
+Next, the DRI section can be used to restrict access to direct rendering.
+
+If you want all of the users on your system to be able to use direct-render-
+ing, then use a simple DRI section:
+
+          Section "DRI"
+               Mode 0666
+          EndSection
+
+This section will allow any user with a current connection to the X server to
+use direct rendering.
+
+If you want to restrict the use of direct-rendering to a certain group of
+users, then create a group for those users by editing the /etc/group file on
+your system.  For example, you may want to create a group called xf86dri and
+place two users (e.g., fred and jane) in that group.  To do that, you might
+add the following line to /etc/group:
+
+             xf86dri:x:8000:fred,jane
+
+You have to be careful that the group id (8000 in this example) is unique.
+
+Then you would use the following DRI section:
+
+             Section "DRI"
+                  Group "xf86dri"
+                  Mode 0660
+             EndSection
+
+This would limit access to direct-rendering to those users in the xf86dri
+group (fred and jane in this example).  When other users tried to use direct
+rendering, they would fall back to unaccelerated indirect rendering.
+
+[Note that there is a known bug in XFree86 4.0 that prevents some changes to
+the DRI section from taking effect.  Until this bug is fixed, if you change
+the DRI section, please also remove the /dev/dri directory with the rm -rf
+/dev/dri command.]
+
+Finally, the XF86Config file needs Device and Screen sections specific to
+your hardware.  Look in section 10: Hardware-Specific Information and Trou-
+bleshooting for details.
+
+7.  Memory usage
+
+Using the 3D features of a graphics card requires more memory than when it's
+just used as a 2D device.  Double buffering, depth buffering, stencil
+buffers, textures, etc. all require extra graphics memory.  These features
+may require four times the memory used for a simple 2D display.
+
+If your graphics card doesn't have a lot of memory (less than 16MB, for exam-
+ple), you may have to reduce your screen size and/or color depth in order to
+use 3D features.  Reducing the screen resolution will also leave more space
+for texture images, possibly improving 3D performance.  If, for example, you
+play Quake3 at 1024x768 but start your display at 1600x1200 you might con-
+sider restarting X at 1024x768 in order to maximize your texture memory
+space.
+
+The documentation included with your card should have information about maxi-
+mum screen size when using 3D.
+
+8.  Using 3D Acceleration
+
+This section describes how to link your application with libGL.so and verify
+that you are in fact using 3D acceleration.
+
+8.1  libGL.so
+
+Your OpenGL program must link with the libGL.so.1.2 library provided by
+XFree86 4.0.  The libGL.so.1.2 library contains a GLX protocol encoder for
+indirect/remote rendering and DRI code for accessing hardware drivers.  In
+particular, be sure you're not using libGL.so from another source such as
+Mesa or the Utah GLX project.
+
+Unless it was built in a special way, the libGL.so library does not contain
+any 3D hardware driver code.  Instead, libGL.so dynamically loads the appro-
+priate 3D driver during initialization.
+
+Most simple OpenGL programs also use the GLUT and GLU libraries.  A source
+for these libraries is listed in the Resources section below.
+
+8.2  Compiling and linking an OpenGL program
+
+A simple GLUT/OpenGL program may be compiled and linked as follows:
+
+             gcc program.c -I/usr/local/include -L/usr/local/lib -L/usr/X11R6/lib -lglut -lGLU -lGL -o program
+
+The -I option is used to specify where the GL/glut.h (and possibly the
+GL/gl.h and GL/glu.h) header file may be found.
+
+The -L options specify where the libglut.so and the X libraries are located.
+libGL.so and libGLU.so should be in /usr/lib, as specified by the
+Linux/OpenGL ABI standard.
+
+The -lglut -lGLU -lGL arguments specify that the application should link with
+the GLUT, GLU and GL libraries, in that order.
+
+8.3  Running your OpenGL program
+
+Simply typing ./program in your shell should execute the program.
+
+If you get an error message such as
+
+             gears: error in loading shared libraries: libGL.so.1: cannot
+             open shared object file: No such file or directory
+
+if means that the libGL.so.1 file is not the right location.  Proceed to the
+trouble shooting section.
+
+8.4  libOSMesa.so
+
+OSMesa (Off-Screen Mesa) is an interface and driver for rendering 3D images
+into a user-allocated block of memory rather than an on-screen window.  It
+was originally developed for Mesa before Mesa became part of the XFree86/DRI
+project.  It can now be used with the XFree86/DRI libGL.so as well.
+
+libOSMesa.so implements the OSMesa interface and it must be linked with your
+application if you want to use the OSMesa functions.  You must also link with
+libGL.so.  For example:
+
+             gcc osdemo.c -lOSMesa -lGLU -lGL -o osdemo
+
+In stand-alone Mesa this interface was compiled into the monolithic libGL.so
+(formerly libMesaGL.so) library.  In XFree86 4.0.1 and later this interface
+is implemented in a separate library.
+
+8.5  glxinfo
+
+glxinfo is a useful program for checking which version of libGL you're using
+as well as which DRI-based driver.  Simply type glxinfo and examine the
+OpenGL vendor, renderer, and version lines.  Among the output you should see
+something like this:
+
+               OpenGL vendor string: Precision Insight, Inc.
+               OpenGL renderer string: Mesa DRI Voodoo3 20000224
+               OpenGL version string: 1.2 Mesa 3.3 beta
+
+or this:
+
+               OpenGL vendor string: Precision Insight, Inc.
+               OpenGL renderer string: Mesa GLX Indirect
+               OpenGL version string: 1.2 Mesa 3.3 beta
+
+The first example indicates that the 3dfx driver is using Voodoo3 hardware.
+The second example indicates that no hardware driver was found and indirect,
+unaccelerated rendering is being used.
+
+If you see that indirect rendering is being used when direct rendering was
+expected, proceed to the troubleshooting section.
+
+glxinfo also lists all of the GLX-enhanced visuals available so you can
+determine which visuals are double-bufferd, have depth (Z) buffers, stencil
+buffers, accumulation buffers, etc.
+
+8.6  Environment Variables
+
+The libGL.so library recognizes three environment variables.  Normally, none
+of them need to be defined.  If you're using the csh or tcsh shells, type
+setenv VARNAME value to set the variable.  Otherwise, if you're using sh or
+bash, type export VARNAME=value.
+
+  1.  LIBGL_DEBUG, if defined will cause libGL.so to print error and diagnos-
+      tic messages.  This can help to solve problems.  Setting LIBGL_DEBUG to
+      verbose may provide additional information.
+
+  2.  LIBGL_ALWAYS_INDIRECT, if defined this will force libGL.so to always
+      use indirect rendering instead of hardware acceleration.  This can be
+      useful to isolate rendering errors.
+
+  3.  LIBGL_DRIVERS_PATH can be used to override the default directories
+      which are searched for 3D drivers.  The value is one or more paths sep-
+      arated by colons.  In a typical XFree86 installation, the 3D drivers
+      should be in /usr/X11R6/lib/modules/dri/ and LIBGL_DRIVERS_PATH need
+      not be defined.  Note that this feature is disabled for set-uid pro-
+      grams.  This variable replaces the LIBGL_DRIVERS_DIR env var used in
+      XFree86 4.0.
+
+  4.  MESA_DEBUG, if defined, will cause Mesa-based 3D drivers to print user
+      error messages to stderr.  These are errors that you'd otherwise detect
+      by calling glGetError.
+
+Mesa-based drivers (this includes most of the drivers listed above) also
+observe many of the existing Mesa environment variables.  These include the
+MESA_DEBUG and MESA_INFO variables.
+
+9.  General Trouble Shooting
+
+This section contains information to help you diagnose general problems.  See
+below for additional information for specific hardware.
+
+9.1  The X Server
+
+  1.  Before you start the X server, verify the appropriate 3D kernel module
+      is installed.  Type lsmod and look for the appropriate kernel module.
+      For 3dfx hardware you should see tdfx, for example.
+
+  2.  Verify you're running XFree86 4.0 (or newer) and not an older version.
+      If you run xdpyinfo and look for the following line near the top:
+
+                       vendor release number:    4000
+
+  3.  Verify that your XF86Config file (usually found at /etc/X11/XF86Config)
+      loads the glx and dri modules and has a DRI section.
+
+      See the Software Resources section below for sample XF86Config files.
+
+  4.  Examine the messages printed during X server startup and check that the
+      DRM module loaded.  Using the Voodoo3 as an example:
+
+                   (==) TDFX(0): Write-combining range (0xf0000000,0x2000000)
+                   (II) TDFX(0): Textures Memory 7.93 MB
+                   (0): [drm] created "tdfx" driver at busid "PCI:1:0:0"
+                   (0): [drm] added 4096 byte SAREA at 0xc65dd000
+                   (0): [drm] mapped SAREA 0xc65dd000 to 0x40013000
+                   (0): [drm] framebuffer handle = 0xf0000000
+                   (0): [drm] added 1 reserved context for kernel
+                   (II) TDFX(0): [drm] Registers = 0xfc000000
+                   (II) TDFX(0): visual configs initialized
+                   (II) TDFX(0): Using XFree86 Acceleration Architecture (XAA)
+                           Screen to screen bit blits
+                           Solid filled rectangles
+                           8x8 mono pattern filled rectangles
+                           Indirect CPU to Screen color expansion
+                           Solid Lines
+                           Dashed Lines
+                           Offscreen Pixmaps
+                           Driver provided NonTEGlyphRenderer replacement
+                           Setting up tile and stipple cache:
+                                   10 128x128 slots
+                   (==) TDFX(0): Backing store disabled
+                   (==) TDFX(0): Silken mouse enabled
+                   (0): X context handle = 0x00000001
+                   (0): [drm] installed DRM signal handler
+                   (0): [DRI] installation complete
+                   (II) TDFX(0): direct rendering enabled
+
+  5.  After the X server has started, verify that the required X server
+      extensions are loaded.  Run xdpyinfo and look for the following entries
+      in the extensions list:
+
+                  GLX
+                  SGI-GLX
+                  XFree86-DRI
+
+9.2  Linking, running and verifying 3D acceleration
+
+After you've verified that the X server and DRI have started correctly it's
+time to verify that the GL library and hardware drivers are working cor-
+rectly.
+
+  1.  Verify that you're using the correct libGL.so library with ldd.  The
+      /usr/lib and /usr/X11R6/lib directories are expected locations for
+      libGL.so.
+
+      Example:
+
+                   % ldd /usr/local/bin/glxinfo
+                           libglut.so.3 => /usr/local/lib/libglut.so.3 (0x40019000)
+                           libGLU.so.1 => /usr/local/lib/libGLU.so.1 (0x40051000)
+                           libGL.so.1 => /usr/lib/libGL.so.1 (0x40076000)
+                           libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x402ee000)
+                           libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x40301000)
+                           libm.so.6 => /lib/libm.so.6 (0x40309000)
+                           libc.so.6 => /lib/libc.so.6 (0x40325000)
+                           libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40419000)
+                           libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x404bd000)
+                           libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x40509000)
+                           libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x40512000)
+                           libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40529000)
+                           libvga.so.1 => /usr/lib/libvga.so.1 (0x40537000)
+                           libpthread.so.0 => /lib/libpthread.so.0 (0x4057d000)
+                           /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+
+  2.  You may also double check that libGL.so is in fact DRI-capable.  Run
+      strings libGL.so.1.2 | grep DRI and look for symbols prefixed with
+      "XF86DRI", such as "XF86DRIQueryExtension".
+
+  3.  To be safe one should run ldconfig after installing libGL.so to be sure
+      the runtime loader will find the proper library.
+
+  4.  Verify that the appropriate 3D driver is in /usr/X11R6/lib/modules/dri/
+      For example, the 3dfx driver will be named tdfx_dri.so.
+
+  5.  Set the LIBGL_DEBUG environment variable.  This will cause libGL.so to
+      print an error message if it fails to load a DRI driver.  Any error
+      message printed should be self-explanatory.
+
+  6.  Run glxinfo.  Note the line labeled "OpenGL renderer string".  It
+      should have a value which starts with "Mesa DRI" followed by the name
+      of your hardware.
+
+  7.  Older Linux OpenGL applications may have been linked against Mesa's GL
+      library and will not automatically use libGL.so.  In some cases, making
+      symbolic links from the Mesa GL library to libGL.so.1 will solve the
+      problem:
+
+                   ln -s libGL.so.1 libMesaGL.so.3
+
+      In other cases, the application will have to be relinked against the
+      new XFree86 libGL.so.
+
+      It is reported that part of the problem is that running ldconfig will
+      silently rewrite symbolic links based on the SONAME field in libraries.
+
+If you're still having trouble, look in the next section for information spe-
+cific to your graphics card.
+
+10.  Hardware-Specific Information and Troubleshooting
+
+This section presents hardware-specific information for normal use and trou-
+bleshooting.
+
+10.1  3dfx Voodoo3 Series
+
+10.1.1  Dependencies
+
+The Voodoo3 DRI driver requires a special versions of the 3dfx Glide library.
+It can be downloaded from the DRI website.
+
+10.1.2  Configuration
+
+Your XF86Config file's device section must specify the tdfx device:
+
+             Section "Device"
+                 Identifier  "Voodoo3"
+                 VendorName  "3dfx"
+                 Driver      "tdfx"
+             EndSection
+
+The Screen section should then reference the Voodoo3 device:
+
+          Section "Screen"
+              Identifier  "Screen 1"
+              Device      "Voodoo3"
+              Monitor     "High Res Monitor"
+              DefaultDepth 16
+              Subsection "Display"
+               Depth       16
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+             EndSection
+
+The kernel module for the Voodoo3 is named tdfx.o and should be installed in
+/lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the Voodoo3 should be in /usr/X11R6/lib/mod-
+ules/dri/tdfx_dri.so.  This will be automatically loaded by libGL.so.
+
+10.1.3  Troubleshooting
+
+   o If you try to run an OpenGL application and see an error message similar
+     to
+
+                gd error (glide): gd error (glide): grSstSelect:  non-existent SSTgd error (glide): grSstSelect:  non-existent SSTS
+
+     it means that you have the wrong version of the Glide library for your
+     hardware.
+
+   o 3D acceleration for Voodoo3 is only supported in the 16 bit/pixel screen
+     mode.  Use xdpyinfo to verify that all your visuals are depth 16.  Edit
+     your XF86Config file if needed.
+
+   o The /dev/3dfx device is not used for DRI; it's only for Glide on older
+     3dfx hardware.
+
+10.1.4  Performance
+
+   o Normally, buffer swapping in double-buffered applications is synchro-
+     nized to your monitor's refresh rate.  This may be overridden by setting
+     the FX_GLIDE_SWAPINTERNVAL environment variable.  The value of this
+     variable indicates the maximum number of swap buffer commands can be
+     buffered.  Zero allows maximum frame rate.
+
+   o The glTexEnv mode GL_BLEND is not directly supported by the Voodoo3
+     hardware.  It can be accomplished with a multipass algorithm but it's
+     not implemented at this time.  Applications which use that mode, such as
+     the Performer Town demo, may become sluggish when falling back to soft-
+     ware rendering to render in that mode.
+
+   o The Voodoo3/Banshee driver reverts to software rendering under the fol-
+     lowing conditions:
+
+        o Setting GL_LIGHT_MODEL_COLOR_CONTROL to GL_SEPARATE_SPECULAR_COLOR.
+
+        o Enabling line stippling or polygon stippling.
+
+        o Enabling point smoothing or polygon smoothing.
+
+        o Enabling line smoothing when line width is not 1.0.  That is,
+          antialiased lines are done in hardware only when the line width is
+          1.0.
+
+        o Using 1-D or 3-D texture maps.
+
+        o Using the GL_BLEND texture environment.
+
+        o Using stencil operations.
+
+        o Using the accumulation buffer.
+
+        o Using glBlendEquation(GL_LOGIC_OP).
+
+        o Using glDrawBuffer(GL_FRONT_AND_BACK).
+
+        o Using glPolygonMode(face, GL_POINT) or glPolygonMode(face,
+          GL_LINE).
+
+        o Using point size attenuation (i.e. GL_DISTANCE_ATTENUATION_EXT).
+
+        o Using glColorMask(r, g, b, a) when r!=g or g!=b.
+
+10.1.5  Known Problems
+
+   o The Glide library cannot be used directly; it's only meant to be used
+     via the tdfx DRI driver.
+
+   o SSystem has problems because of poorly set near and far clipping planes.
+     The office.unc Performer model also suffers from this problem.
+
+   o The lowest mipmap level is sometimes miscolored in trilinear- sampled
+     polygons.
+
+10.2  3dfx Voodoo5 Series
+
+10.2.1  Dependencies
+
+The Voodoo5 DRI driver requires a special versions of the 3dfx Glide library,
+different than that used for Voodoo3 hardware.  It can be downloaded from the
+DRI website.
+
+10.2.2  Configuration
+
+Your XF86Config file's device section must specify the tdfx device:
+
+             Section "Device"
+                 Identifier  "Voodoo5"
+                 VendorName  "3dfx"
+                 Driver      "tdfx"
+             EndSection
+
+The Screen section should then reference the Voodoo3 device:
+
+          Section "Screen"
+              Identifier  "Screen 1"
+              Device      "Voodoo5"
+              Monitor     "High Res Monitor"
+              DefaultDepth 24
+              Subsection "Display"
+               Depth       16
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+              Subsection "Display"
+               Depth       24
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+             EndSection
+
+The kernel module for the Voodoo5 is named tdfx.o and should be installed in
+/lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the Voodoo5 should be in /usr/X11R6/lib/mod-
+ules/dri/tdfx_dri.so.  This will be automatically loaded by libGL.so.
+
+The Voodoo5 supports 3D rendering in 16 and 32 bpp modes.  When running in
+32bpp mode an 8-bit stencil buffer and 24-bit Z (depth) buffer are offered.
+When running in 16bpp mode only a 16-bit Z (depth) buffer is offered and
+stencil is implemented in software.
+
+A software-based accumulation buffer is available in both 16 and 32bpp modes.
+
+10.2.3  Troubleshooting
+
+   o The /dev/3dfx device is not used for DRI; it's only for Glide on older
+     3dfx hardware.
+
+   o Different versions of Glide are needed for Voodoo3 and Voodoo5.  See the
+     DRI website's resources page to download the right version of Glide.
+
+10.2.4  Performance
+
+   o Normally, buffer swapping in double-buffered applications is synchro-
+     nized to your monitor's refresh rate.  This may be overridden by setting
+     the FX_GLIDE_SWAPINTERNVAL environment variable.  The value of this
+     variable indicates the maximum number of swap buffer commands can be
+     buffered.  Zero allows maximum frame rate.
+
+   o Rendering with 16-bit per texel textures is faster than using 32-bit per
+     texel textures.  The internalFormat parameter to glTexImage2D can be
+     used to control texel size.
+
+   o The Voodoo5 driver reverts to software rendering under the same condi-
+     tions Voodoo3 with three exceptions.  First, stencil operations are
+     implemented in hardware when the screen is configured for 32 bits/pixel.
+     Second, the GL_BLEND texture env mode is fully supported in hardware.
+     Third, glColorMask is fully supported in hardware when the screen is
+     configured for 32 bits/pixel.
+
+10.2.5  Known Problems
+
+   o The Glide library cannot be used directly; it's only meant to be used
+     via the tdfx DRI driver.
+
+   o 24bpp screen modes are supported by the hardware but not by the current
+     driver.  32bpp is fully supported.
+
+   o As of October, 2000 the second VSA-100 chip on the Voodoo5 is not yet
+     operational.  Therefore, the board isn't being used to its full capac-
+     ity.  The second VSA-100 chip will allow Scan-Line Interleave (SLI) mode
+     for full-screen applications and games, potentially doubling the sys-
+     tem's fill rate.
+
+10.3  Intel i810
+
+        "
+
+10.3.1  Dependencies
+
+          "
+
+A Linux kernel with AGP GART support is required.  The 2.2.x kernel series
+does not have AGP GART support.  The 2.4.x test kernels have AGP GART and
+have been tested with the i810.
+
+10.3.2  Configuration
+
+          "
+
+Your XF86Config file's device section must specify the i810 device, and spec-
+ify a usable amount of video ram to reserve.
+
+             Section "Device"
+                 Identifier  "i810"
+                 VendorName  "Intel"
+                 Driver      "i810"
+              VideoRam    10000
+             EndSection
+
+The Screen section should then reference the i810 device:
+
+          Section "Screen"
+              Identifier  "Screen 1"
+              Device      "i810"
+              Monitor     "High Res Monitor"
+              DefaultDepth 16
+              Subsection "Display"
+               Depth       16
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+             EndSection
+
+The kernel module for the i810 is named i810.o and should be installed in
+/lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the i810 should be in /usr/X11R6/lib/mod-
+ules/dri/i810_dri.so.  This will be automatically loaded by libGL.so.
+
+10.3.3  Troubleshooting
+
+   o 3D acceleration for the i810 is only available in the 16 bit/pixel
+     screen mode at this time.  32bpp acceleration is not supported by this
+     hardware.  Use xdpyinfo to verify that all your visuals are depth 16.
+     Edit your XF86Config file if needed.
+
+   o The i810 uses system ram for video and 3d graphics.  The X server will
+     ordinarily reserve 4mb of ram for graphics, which is too little for an
+     effective 3d setup.  To tell the driver to use a larger amount, specify
+     a VideoRam option in the Device section of your XF86Config file.  A num-
+     ber between 10000 and 16384 seems adequate for most requirements.  If
+     too little memory is available for DMA buffers, back and depth buffers
+     and textures, direct rendering will be disabled.
+
+10.4  Matrox G200 and G400
+
+      "
+
+10.4.1  Dependencies
+
+        "
+
+A Linux kernel with AGP GART support (such as the 2.4.x test kernels) is
+needed.
+
+10.4.2  Configuration
+
+        "
+
+Your XF86Config file's device section must specify the mga device:
+
+             Section "Device"
+                 Identifier  "MGA"
+                 VendorName  "Matrox"
+                 Driver      "mga"
+              VideoRam    32768
+             EndSection
+
+The Screen section should then reference the MGA device:
+
+          Section "Screen"
+              Identifier  "Screen 1"
+              Device      "MGA"
+              Monitor     "High Res Monitor"
+              DefaultDepth 16
+              Subsection "Display"
+               Depth       16
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+             EndSection
+
+To use a 32bpp screen mode, use this Screen section instead:
+
+          Section "Screen"
+              Identifier  "Screen 1"
+              Device      "MGA"
+              Monitor     "High Res Monitor"
+              DefaultDepth 24
+                 DefaultFbBpp 32
+              Subsection "Display"
+               Depth       24
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+             EndSection
+
+The kernel module for the G200/G400 is named mga.o and should be installed in
+/lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the G200/G400 should be in /usr/X11R6/lib/mod-
+ules/dri/mga_dri.so.  This will be automatically loaded by libGL.so.
+
+10.4.3  Performance
+
+Software rendering will be used under any of the following conditions:
+
+   o Using glDrawBuffer(GL_FRONT_AND_BACK).
+
+   o Using point, line, or triangle smoothing.
+
+   o Using glLogicOp.
+
+   o Using glPolygonStipple or glLineStipple.
+
+   o Using 1D or 3D textures.
+
+   o Using the accumulation buffer.
+
+Compaq has funded the implementation of AGP acclerated ReadPixels and
+DrawPixels in this driver.  With this implementation, on a G400
+drawing directly from AGP memory (exported to the client), throughput
+of up to 1 GB/sec has been measured.
+
+Additionally their funding has produced several new extensions in
+Mesa, including one (packed_depth_stencil_MESA) which enables
+Read/DrawPixels functionality to operate directly on the packed 24/8
+depth/stencil buffers of this hardware.
+
+In order to access this functionality, the application must ensure
+that all pixel processing operations are disabled.  There are in
+addition a fairly complex set of rules regarding which
+packing/unpacking modes must be used, and which data formats are
+supported.  See the files in lib/GL/mesa/src/drv/mga/DOCS for a
+summary of these.  The extension definitions are included in the Mesa
+3.4 source distribution.
+
+10.4.4  IRQ Assignment
+
+There have been problems in the past with the MGA driver being very sluggish
+when the DRI is enabled (to the point of being unusable.)  This is caused by
+the graphics card not having an interrupt assigned to it.  The current DRI
+trunk will attempt to detect this condition and bail out gracefully.
+
+The solution to the above problem is to assign an interrupt to your graphics
+card.  This is something you must turn on in your system BIOS configuration.
+Please consult your system BIOS manual for instructions on how to enable an
+interrupt for your graphics card.
+
+10.4.5  MGA HAL lib
+
+MGAHALlib.a is a binary library Matrox has provided for use under Linux to
+expose functionality for which they can not provide documentation.  (For
+example TV-Out requires MacroVision be enabled on the output.)  This binary
+library also sets the pixel/memory clocks to the optimal settings for your
+Matrox card.
+
+Currently the MGAHAL library is required for the G450 to work.  You can down-
+load this from the driver section on Matrox's website: www.matrox.com/mga
+
+Here modifications to the DRI build instructions which make the mga ddx
+driver use the MGAHAL library:
+
+            1.Put the following define in your host.def file
+                 #define UseMatroxHal YES
+            2. Place mgaHALlib.a in the following directory
+                 xc/programs/Xserver/hw/xfree86/drivers/mga/HALlib/
+
+You can use DualHead on the G400/G450 DH cards by creating two device sec-
+tions which both point to the same BusID.  For most AGP devices the BusID
+will be "PCI:1:0:0".  Configure your screen section as you would normally
+configure XFree86 4.x Multihead.  It should be noted that currently the sec-
+ond head does not support direct rendering.
+
+10.4.6  Known Problems
+
+None.
+
+10.5  ATI Rage 128
+
+      "
+
+10.5.1  Dependencies
+
+        "
+
+A Linux kernel with AGP GART support (such as the 2.4.x test kernels) is
+needed.
+
+10.5.2  Configuration
+
+        "
+
+Your XF86Config file's device section must specify the r128 device:
+
+             Section "Device"
+                 Identifier  "Rage128"
+                 VendorName  "ATI"
+                 Driver      "r128"
+             EndSection
+
+The Screen section should then reference the Rage 128 device:
+
+          Section "Screen"
+              Identifier  "Screen 1"
+              Device      "Rage128"
+              Monitor     "High Res Monitor"
+              DefaultDepth 16
+              Subsection "Display"
+               Depth       16
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+              Subsection "Display"
+               Depth       32
+               Modes       "1280x1024" "1024x768" "800x600" "640x480"
+               ViewPort    0 0
+              EndSubsection
+             EndSection
+
+The kernel module for the Rage 128 is named r128.o and should be installed in
+/lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
+by the Xserver if needed.
+
+The DRI 3D driver for the Rage 128 should be in /usr/X11R6/lib/mod-
+ules/dri/r128_dri.so.  This will be automatically loaded by libGL.so.
+
+You may also set your screen depth to 32 for 32bpp mode.
+
+10.5.3  Performance
+
+While PCI Rage 128 based cards are supported, they do not yet support PCI
+GART, so they will not perform as well as their AGP counterparts.
+
+10.5.4  Known Problems
+
+DGA is not yet supported in the ATI Rage 128 X server.  This feature will be
+added in a future release.
+
+10.6  3DLabs Oxygen GMX 2000
+
+The driver for this hardware was experimental and is no longer being devel-
+oped or supported.
+
+11.  General Limitations and Known Bugs
+
+11.1  OpenGL
+
+The following OpenGL features are not supported at this time: overlays,
+stereo, hardware-accelerated indirect rendering.
+
+OpenGL-like functionality is provided with the Mesa library.  XFree86 4.0.1
+uses Mesa 3.3.  Subsequent releases of XFree86 will use newer versions of
+Mesa.  When newer versions of Mesa are available, the 3D drivers can be
+updated without reinstalling XFree86 or libGL.so.
+
+11.2  GLX
+
+The GLX 1.3 API is exported but none of the new 1.3 functions are opera-
+tional.
+
+The new glXGetProcAddressARB function is fully supported.
+
+GLXPixmap rendering is only supported for indirect rendering contexts.  This
+is a common OpenGL limitation.  Attempting to use a direct rendering context
+with a GLXPixmap will result in an X protocol error.
+
+11.3  Debugging
+
+Debugging DRI drivers with gdb can be difficult because of the locking
+involved.  When debugging OpenGL applications, you should avoid stepping
+inside the GL functions.  If you're trying to debug a DRI driver it's recom-
+mended that you do so remotely, from a second system.
+
+11.4  Scheduling
+
+When you run multiple GL applications at once you may notice poor time slic-
+ing.  This is due to an interaction problem with the Linux scheduler which
+will be addressed in the future.
+
+11.5  libGL.so and dlopen()
+
+A number of popular OpenGL applications on Linux (such as Quake3, HereticII,
+Heavy Gear 2, etc) dynamically open the libGL.so library at runtime with
+dlopen(), rather than linking with -lGL at compile/link time.
+
+If dynamic loading of libGL.so is not implemented carefully, there can be a
+number of serious problems.  Here are the things to be careful of in your
+application:
+
+   o Specify the RTLD_GLOBAL flag to dlopen().  If you don't do this then
+     you'll likely see a runtime error message complaining that _glapi_Con-
+     text is undefined when libGL.so tries to open a hardware-specific
+     driver.  Without this flag, nested opening of dynamic libraries does not
+     work.
+
+   o Do not close the library with dlclose() until after XCloseDisplay() has
+     been called.  When libGL.so initializes itself it registers several
+     callbacks functions with Xlib.  When XCloseDisplay() is called those
+     callback functions are called.  If libGL.so has already been unloaded
+     with dlclose() this will cause a segmentation fault.
+
+   o Your application should link with -lpthread.  On Linux, libGL.so uses
+     the pthreads library in order to provide thread safety.  There is appar-
+     ently a bug in the dlopen()/dlclose() code which causes crashes if the
+     library uses pthreads but the parent application doesn't.  The only
+     known work-around is to link the application with -lpthread.
+
+Some applications don't yet incorporate these procedures and may fail.  For
+example, changing the graphics settings in some video games will expose this
+problem.  The DRI developers are working with game vendors to prevent this
+problem in the future.
+
+11.6  Bug Database
+
+The DRI bug database which includes bugs related to specific drivers is at
+the SourceForge DRI Bug Database
+
+Please scan both the open and closed bug lists to determine if your problem
+has already been reported and perhaps fixed.
+
+12.  Resources
+
+12.1  Software
+
+A collection of useful configuration files, libraries, headers, utilities and
+demo programs is available from http://dri.source-
+forge.net/resources/resources.html
+
+12.2  Documentation
+
+   o General OpenGL information is available at the OpenGL Home Page
+
+   o XFree86 information is available at the XFree86 Home Page
+
+   o Information about the design of the DRI is available from Precision
+     Insight, Inc.
+
+   o Visit the DRI project on SourceForge.net for the latest development news
+     about the DRI and 3D drivers.
+
+   o The DRI Compilation Guide explains how to download, compile and install
+     the DRI for yourself.
+
+12.3  Support
+
+   o The DRI-users mailing list at SourceForge is a forum for people to dis-
+     cuss DRI problems.
+
+   o In the future there may be IHV and Linux vendor support resources for
+     the DRI.
+
+     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.15 2000/12/12 18:54:29 dawes Exp $
+
+
+$XFree86: xc/programs/Xserver/hw/xfree86/doc/README.DRI,v 1.12 2000/12/12 19:04:02 dawes Exp $