Guide to debugging DRI installation

Unless your system came with DRI preinstalled and everything works perfectly chances are you'll run into problems getting your accelerated 3d to work. This webpage aims to help you getting your card to work.

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

3d acceleration: components
ComponentWhere to findDescription
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 and 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 and 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/ResourceWhere to findComment
Kernel log run:
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:
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:
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/
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
lsmod Run:
This utility will print out all kernel modules currently loaded

Now we can write a checklist for debugging DRI installation:

And some miscellaneous advice: