Guide to debugging DRI installation

The first order of business is to enumerate all the components that take part in accelerated 3d.

3d acceleration: components
Component	Where to find	Description
agpgart	part of Linux kernel	agpgart is needed to make use of your AGP connector. It is motheboard specific. To enable turn on agpgart support for your motherboard in Linux kernel.
mtrr	part of Linux kernel	mtrr is needed to tell cpu that certain memory address ranges (namely the framebuffer and register apertures of your video card) need to be treated differently from usual RAM. This dramatically accelerates 2d perfomance and is recommended for hardware 3d.
drm	part of XFree86	drm stands for direct rendering manager. It is a kernel module responsible for mediating access to video hardware. It is video card specific. Though Linux kernel usually includes drm modules so far they were couple of versions behind so if you are installing a recent version of XFree you will likely need a more recent module. Note that compiled (binary) drm modules are kernel specific.
XFree86	part of XFree 4.x.x	XFree86 is the Xserver binary that comes with 4.x.x distributions of XFree. Unless you got a static server (very unlikely) this binary will want to load various modules which usually reside in /usr/X11R6/lib/modules
video driver module(s)	part of XFree 4.x.x	For ati cards these are ati_drv.o, atimisc_drv.o, r128_drv.o and radeon_drv.o. These binary files usually reside in /usr/X11R6/lib/modules/drivers
dri driver module	part of XFree 4.x.x	For ati cards these are r128_dri.so and radeon_dri.so. These usually reside in /usr/X11R6/lib/modules/dri
glx module	part of XFree 4.x.x	provides glx extension support for XFree86. Can usually be found as /usr/X11R6/lib/modules/extensions/libglx.a
dri module	part of XFree 4.x.x	provides core dri support for XFree86. Can usually be found as /usr/X11R6/lib/modules/extensions/libdri.a
GLcore module	part of XFree 4.x.x	provides core GL support for XFree86. Can usually be found as /usr/X11R6/lib/modules/extensions/libGLcore.a
GL/GLU library	part of XFree 4.x.x	these are the libraries used by user applications. They are usually named libGL.so and libGLU.so. Beware ! - they are often distributed standalone with software-only GL support. Only the version that came with XFree 4.x.x is capable of hardware GL. (with the exception of Voodoo (glide) cards).
application		your application that uses GL. unless it uses the right GL library it will not try to do hardware acclerated 3d.

Now that we know all the components of accelerated 3d let us list the tools to debug your installation:

Tools and resources
Tool/Resource	Where to find	Comment
Kernel log	run: dmesg	Linux kernel log contains many messages. Watch it for information from agpgart, mtrr and drm.
XFree log	/var/log/XFree86.0.log	XFree86 log contains a lot of useful information including paths from which modules are being loaded and versions of modules being loaded. Also in the very end it will tell you whether dri has been enabled or not.
glxinfo	Run: glxinfo	This program will connect to Xserver and provide information about glx from a perspective of user application. It will generally tell you whether direct rendering is enabled or not. This program uses GL/GLU libraries - which sometimes lie about whether direct rendering is really being used.
glxgears	Run: glxgears	this is a sample GL app. It should display 3 rotating gears. If it works things aren't so bad.
ldd	Run: ldd any_program	ldd is a part of dynamic loader. It will tell you which shared libraries will be loaded when your application will try to run. It is very useful to find out which GL libraries exactly are being used.
ldconfig	Run as root: ldconfig -v	ldconfig is part of dynamic loader and is usually used to configure shared libraries. The -v option produces a lot of output telling which libraries of which versions are being used.
strace	Run: strace any_program >& a.log	strace will print out a lot of info describing interaction of any program with linux kernel. In particular, in the very beginning there will be a lot of open() calls from dynamic loader looking and loading shared libraries. This will tell you which libraries are being loaded. Keep in mind that some GL apps like to look for GL libraries themselves (as opposed to using dynamic loader). strace is then the only way to find out which library is being used
LD_PRELOAD	Run in bash: export LD_PRELOAD=/path/your_lib.so	This environment variable can be used to force dynamic linker to load certain library first, even if a different version of the same library exists someplace else. Handy to try loading different GL libraries. For more information see man ld.so
lsmod	Run: /sbin/lsmod	This utility will print out all kernel modules currently loaded

Now we can write a checklist for debugging DRI installation:

• Install XFree 4.x.x. Make sure it works. Backup !
• Check kernel messages to make sure agpgart and mtrr are being loaded and work.
• Start XFree 4.x.x. Check /var/log/XFree86.0.log for messages about dri. Does it say "dri enabled" in the end ?
• make sure that your cards drm module (r128.o or radeon.o) is being loaded by the kernel. If not, try modprobe or recompile linux kernel.
• Start XFree 4.x.x again. Does the log say "dri enabled" in the end ? Check dmesg do you see output of drm module ? Does XFree log complain about wrong drm module version ? If so obtain a newer drm module, compile it and install. Try again.
• By this time XFree log file should say "dri enabled". Open a terminal and run glxgears. It will print out a frames per second count each 5 seconds. If you are using hardware GL it should give you at least 500 FPS. With software 3d you are unlikely to get more than 300 FPS. Both figures, of course, depend on video card and cpu.
• If glxgears shows small frame rates try using ldd glxgears to find out which GL library is being used. If it is the wrong one move it out of the way and run ldconfig.

• While hardware 3d is active nothing except your Xserver should be accessing your video card - or your system will lockup hard. In particular, frame grabber cards that write directly to video memory should be turned off. If you want to use these cards try out v4l module in XFree 4.x.x.
  For developers: as was pointed out to me by Jens Owen, this explanation is oversimplified. The concept of direct rendering is that the client program has direct access to the hardware which is mediated by the dri architecture. So for register based programming the currently active GL program can also access the card without inducing a lockup. For cards that use DMA to upload 3d commands (like Rage 128 and Radeon) the user program simply writes data into main memory.
• If you are compiling XFree yourself keep in mind that it is often the case that compilation of some library or module will fail (silently) and when you install not all libraries/modules will be replaced. This can cause a lot of "Unresolved symbol" errors. Go back to XFree tree examine world.log and install.log, recompile and reinstall
• More documentation can be found on DRI main website.