TrixX's Journal: Hardware accelerated 3D in Linux

Recently, I tried to enable hardware 3D acceleration in some Linux machines. As my previous video configuring experiences were on machines with no 3D hardware or with 3D hardware that was automatically configured (by the nvidia-installer in one occasion, and by ubuntu and mandriva in others), I had no idea how to do this manually.

Documentation for this sucks quite badly. There are several components that must work together for 3D to work, but this is mentioned almost nowhere. There is documentation for each one of the components, but no global map to know which ones you need, of if you are missing some element that you should know about but don't. So I hope this account of my experience helps. I will also try to explain how to debug to know if each component is working

The whole list is something like: The DRM (a kernel module)for your card, your X server with the GLX and DRI extensions, properly setup /dev/dri/* character devices, OpenGL libraries, a video driver supporting 3D, and an the video driver DRI module. Any of these missing can result in no hardware acceleration and no clue about what is missing. Let's see one by one.

The DRM consists in a couple of kernel modules. One of them, 'drm', is generic. The other one is specific for your video chipset family (For example, you have 'i810.ko', 'radeon.ko', 'sis.ko', etc.). Most of them depend on the 'agpgart' module. Normally

modprobe myvideo

should do the work. To know what choice for video families you have check the /lib/modules/your-kernel-version/kernel/drivers/char/drm. The stock kernels include support for some cards, but if there is no support for your card you should get it separately. The nvidia installer compiles the DRM for nvidia cards; in ubuntu you also have the nvidia-kernel package (or the linux-restricted-...-nvidia-legacy for older nvidia cards).

If you have no package, you will probably need to compile it yourself. Check it out with

cvs -z3 -d:pserver:[e-mail]:/cvs/dri co drm

To compile, run

LINUXDIR=/usr/src/source-tree-path make

; you need the linux source tree properly configured (i.e., after make *config). If you have a i386 kernel (like ubuntu has) a check in the makefile for the CONFIG_CMPXCHG variable will fail. Disabling that check worked for me (I only tried the VIA and Intel 810 drivers; perhaps other drivers really need that). After that you copy it to the right place (.../kernel/drivers/char/drm) and run depmod -ae.

More details about drm: http://dri.freedesktop.org/wiki/DRM

If everything when fine, modprobe of your video module should succeed, and dmesg should show a message saying that the driver detected and was enabled for your card. For example:

[drm] Initialized via 2.9.0 20060111 on minor 0: VIA Technologies, Inc. VT8378 [S3 UniChrome] Integrated Video

Once everything is properly setup, you will not need to load the kernel module manually, it will be automatically requested by your X server. If you have something like devfs or hotplug which makes the device nodes for you, after inserting the module you also should have

$ ls -l /dev/dri/
total 0
crw-rw-rw- 1 root root 226, 0 2006-02-11 11:39 card0

You should make sure you have installed the Mesa 3d libraries, an implementation of OpenGL. There are a hanful of "flavors"of mesa, for different uses, and you will need a variant that runs as an OpenGL renderer in X. Most new Xorg install by default what you need. Older XFree based distributions require a "mesa for X package"; for example debian sarge has "xlibmesa-gl" and "xlibmesa-glu". You should have /usr/lib/libGL.so.1 and /usr/lib/libGLU.so.1.

After that, you should configure the X server, enabling the GLX and DRI modules (these are X modules, not kernel modules). GLX alone enables 3D operations on the X server (you need it even for software rendering). The DRI extension is the component of X which talks to the kernel module that we just set up. Both modules come with XFree or Xorg, you have to enable them:

Section "Module"
...
Load "dri"
Load "glx"
...
EndSection

If the GLX module was properly loaded, running 'glxinfo' from X will show a lot of information... if the GLX module is not loaded you will get a message (or several) indicating "extension GLX missing on display". Among the messages you will get if GLX is successfully enabled is "OpenGL version string: 1.4 Mesa 5.0.2" and "direct rendering: No". With that you can run 3D applications, with software rendering (slow). If you happened to have the rest of the video drivers needed perhaps you already have hardware acceleration working at this point. In that case The above messages will say "direct rendering: Yes" and "OpenGL renderer string: Mesa DRI i810 20050818" (note the DRI word, and the name of the card, in this case i810, in the message)

When the GLX module fails to load, check the xserver log, you should find lines saying

(II) LoadModule: "glx"
...
(II) Loading extension GLX

Any error message should be around those lines. A possible problem (beside errors in the config file) is that you are lacking the Mesa libraries mentioned above, or that they don't match your X server.

At this time, you should be able to run 3d apps, although perhaps quite slowly. Besides the important "direct rendering: yes/no" output, you can check that with the glxgears demo program. It is also useful to know how much acceleration do you get, because it prints the frames-per-second to stdout. On ubuntu, the FPS printing has been removed by default, so you need to run it as glxgears -iacknowledgethatthistoolisnotabenchmark. You will probably get between 50-100fps at the default window size for software rendering. You should get a few hundred on a cheap on-board video card, or even more than a thousand on a high-end graphics card.

Now is time to check that the DRI extension is working ok. On newer Xs, you have a tool 'xdriinfo' to know that. It outputs things like 'Xlib: extension "XFree86-DRI" missing on display ":0.0"' if DRI was not properly loaded. It outputs "screen 0: none" if DRI was enabled, but no kernel support for your card was found. It outputs "screen 0: drivername" if a proper DRM module was found.

(II) LoadModule: "dri"
...
(II) LoadModule: "drm"
...
(II) Loading extension XFree86-DRI

And error messages around. Not having those lines indiates an error in the X config file.

If the extension was loaded successfully, and you have the kernel module setup correctly, the X log will have several messages labeled '[dri]' and '[drm]', usually ending with

(II) I810(0): [DRI] installation complete
(II) I810(0): direct rendering: Enabled

(the driver name I810 will probably be different, and you may have some lines between the above two messages). Note that the "direct rendering: Enabled" may not match the "direct rendering: yes/no" output of glxinfo. This message in the X log indicates that the X server could negotiate with the kernel the operations needed for 3d; however, without the proper video driver you could have this step succesfully done, and still "direct rendering: No" in the output of glxinfo (and thus, no 3d acceleration). One usual cause of this, besides lack of video driver, is lack of proper permissions on the DRI device. This will be the case if you have 3d working as root but no as other users. The permissions of the DRI device are, weirdly enough, managed directly from X, with a section in the config file:

Section "DRI"
Mode 0666
EndSection

These are normal unix permissions and you may also use an specific user and/or group to restrict 3d usage to a specific set of users. In the example above, any user can use the 3d hardware.

The last step is setting the right video drivers. There are two drivers required: one is for normal X clients (desktop apps), and other extends it for 3d acceleration. The first one is selected by the Driver "foo" in the "Device" section of the X config file. It is looked up at /usr/X11R6/lib/modules/drivers/foo_drv.o (or .so if you have a recent Xorg). The DRI driver is loaded by the first one, and is located at /usr/X11R6/lib/modules/dri, or /usr/lib/dri in some distributions. The name of the second driver usually ends in _dri.so; the prefix is related to your video card model, but it does not always match the name of the 2D driver. For example, via_drv.o (for VIA graphic chipsets) matches with unichrome_dri.so. i810_drv.o (for Intel graphic chipsets), may load the i810_dri.so or i830_dri.so depending on which specific chipset you have. As you may guess now, you need a 2D driver compiled to look for and load the proper 3D driver, so if you have only the 2D driver adding the 3D one will usually do nothing.

With every XFree/Xorg distribution you get a bunch of 2D and 3D drivers that may be just what you need. In some distributions the 3D drivers come in a separate package (In Debian: xlibmesa-dri). However, your X distribution may not have included the driver for your card, or may have included just a not 3d-aware 2d driver. In that case, you may have luck getting external drivers. The safest way is compile, but that requires the source code for your X system, and quite a lot of work. A simpler way, although with varying chances of success, is to try precompiled modules; you can find some of them at http://dri.freedesktop.org/snapshots/ . You should get a version of a date similar to your X server. You can get the package specific for your video card, and copy the _drv and _dri files to the correct directories and check if they work. Always backup your old files, of course, just in case X stops working. If you have problems related to library versions, the "common" package available at the same URL provides a libGL that should work with that drivers (you will have to rename your old libGL and libGLU). Choose a "common" package from the same date of the library.

Driver problems should be diagnosed by checking the X log. I would paste the messages to indicate success/failure but they seem to vary from driver to driver.

With different subsets of the above instructions (depending on what had been automatically setup and what was missing), I was able to get working every 3D card I could get a hand on in the last weeks, except for a SIS630 (on a Debian system where I decided not to risk breaking the 3D libraries installing the dri snapshot). The result was generally quite good, except for an ATI Rage Mobility in an old laptop where hardware acceleration gave me less than 10% of improvement.