Contents
1. Building the DRI with X.org and Mesa
This is a basic guide to building DRI from source. This guide only covers building the client-side 3D drivers. Since the transition to the modular X.org build, building an X-server and 2D drivers is beyond the scope of this document. That information can be found in the X.org Modular Developer Guide. An important aspect is to compile X-server with the --with-mesa-source=/path/to/mesa option, to include glx/OpenGL support. You will most probably need to (re)compile also at least the keyboard and mouse drivers, in addition to a video card 2D driver.
KDrive servers are not supported at this time. Please report any problems with these instructions on the dri-users mailing list or on IRC.
The 2D drivers with DRI support, server-side GLX support and the GL library capable of loading DRI 3D drivers are developed in X.org's CVS. The 3D drivers, though, live in the Mesa tree, so you will have to check out the Mesa git tree. You should also get the DRM git tree for up-to-date kernel modules. The following instructions will guide you through the process step by step.
Warning: In case you didn't notice, you are about to compile and install experimental software. This will allow you to test the latest features and bug fixes. It may, however, also introduce new bugs. Be prepared for problems every now and then.
1.1. Dependencies
You need a current version (7.4, ie. xserver 1.5 as of this writing) of X.org (core and development packages) installed on your system. In particular, you need these X.org components:
proto/glproto 1.4.9 or git://anongit.freedesktop.org/git/xorg/proto/glproto
proto/xf86vidmodeproto git://anongit.freedesktop.org/git/xorg/proto/xf86vidmodeproto
lib/libXxf86vm git://anongit.freedesktop.org/git/xorg/lib/libXxf86vm
lib/libXmu git://anongit.freedesktop.org/git/xorg/lib/libXmu
dri2proto http://xorg.freedesktop.org/releases/individual/proto/dri2proto-1.1.tar.gz
1.1.1. On Debian/Ubuntu
If you are using Debian or Ubuntu you only have to install the dri2proto package manually, the rest can be installed with:
apt-get build-dep libdrm mesa apt-get install linux-headers-`uname -r` apt-get install libxi-dev libxmu-dev x11proto-xf86vidmode-dev apt-get install git-core autoconf automake libtool
1.2. Getting the latest source trees
Get the source trees using two git commands. These commands should be run in the same directory. When they've run, you will have two new subdirectories: mesa, and drm.
1.2.1. Getting DRM and libdrm
The clean DRM source tree takes about 4MB of disk space.
git clone git://anongit.freedesktop.org/git/mesa/drm
1.2.2. Getting Mesa
The clean Mesa source tree takes about 32MB of disk space.
git clone git://anongit.freedesktop.org/git/mesa/mesa
1.3. Building libdrm
The Mesa drivers now require libdrm to be installed. Do the following to build libdrm:
cd drm ./autogen.sh
Note: libdrm installs to /usr/local/lib by default. To install in /usr/lib run:
./configure --prefix=/usr
Then as root, to install:
make install
1.4. Building Mesa 3D drivers on Linux
The DRI 3D drivers are now built from the Mesa source. Choose the right 'make' target depending on the hardware architecture you're compiling for. linux-dri should work for all architectures. linux-dri-x86 includes x86-specific assembler optimizations. linux-dri-x86-64 is for the AMD x86-64 architecture.
Next, optionally edit the architecture configuration files. mesa/configs/linux-dri is for Linux. mesa/configs/freebsd-dri is for FreeBSD. The first line defines some compiler optimization/debugging flags. If you don't know what to put here you can leave it out as there are reasonable default settings. The second line can be used to trim the build even further by compiling only the drivers you need.
OPT_FLAGS = <compiler flags> DRI_DIRS = <dri drivers>
(Previous versions of this document suggested that you might also need to set DRM_SOURCE_PATH in configs/default. This is no longer true since libdrm is a properly installed library now.)
The full set of supported drivers is currently:
DRI_DIRS = i810 i830 i915 mach64 mga r128 r200 radeon s3v \
savage sis tdfx trident unichrome r300Note: The i830 driver is deprecated in X.org. Use i915 instead.
Note: You will need to install libdrm for Mesa to build properly. You should have done that at step 1.5 when doing the "make install".
Note: You will need to update PKG_CONFIG_PATH if you installed libdrm in /usr/local/lib. For example, export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH.
Now you're ready to compile it. For x86 you would type:
make linux-dri-x86
1.5. Building Mesa 3D drivers on BSD
The BSD instructions are the same as above, but with configuration names "freebsd-dri", "freebsd-dri-x86", and "freebsd-dri-amd64". Also, you must use gmake to build due to gmake-specific bits in the Makefiles.
1.6. Installing the 3D drivers
After compiling the Mesa tree, the 3D drivers can be found in mesa/lib. There are two ways of using them: installing them in the destined place, or telling X where to find them.
1. Copy the drivers to /usr/X11R6/lib/modules/dri:
cp lib/*_dri.so /usr/X11R6/lib/modules/dri/
Under some newer distributions, like Ubuntu 7.04, the drivers need to be copied to /usr/lib/dri instead:
cp lib/*_dri.so /usr/lib/dri/
Note: You need to copy the rest of files, like libGL.so.1.2, from mesa/lib to the correct directories too. Usually to /usr/lib.
Note: In case you previously did a mv /usr/X11R6/lib/modules /usr/X11R6/lib/modules.old, you may need to do a mkdir -p /usr/X11R6/lib/modules/dri before the cp command.
Note: If you use an x86-64 architecture, then you'll need instead:
cp lib64/*_dri.so /usr/X11R6/lib/modules/dri/
2. Or set the environment variable LIBGL_DRIVERS_PATH to point to <path to Mesa>/lib, and also preload the newly built libGL.so:
export LIBGL_DRIVERS_PATH=<path to Mesa>/lib export LD_PRELOAD=<path to Mesa>/lib/libGL.so.1
To make these settings persistent, you'll have to add them to .bashrc or a similar login script.
1.7. Building the DRM on Linux
You need a configured kernel source tree installed. Make sure you have run at least make dep on your kernel tree or the build will fail. Make sure that your kernel has CONFIG_DRM disabled or built as a module (precompiled kernels that come with Linux distributions usually have DRM compiled as a module). If necessary, disable CONFIG_DRM and recompile your kernel before you proceed.
If you're building for Linux 2.4, change to the drm/linux/ directory in the DRM tree. For Linux 2.6 builds, change to the drm/linux-core directory. Note that the latest features and new drivers are only available in drm/linux-core for Linux 2.6. Note: The new savage drm (v2.0.0+) is only available on 2.6 kernels.
To compile the DRM run:
make
If the previous command could not find your kernel source tree or if you want to build against another kernel:
make LINUXDIR=/path/to/kernel/source
You may optionally tell make to only generate a subset of the modules:
make DRM_MODULES="i810 radeon"
Copy the resulting *.ko (2.6.x kernel) or *.o (2.4.x kernel) modules into the kernel module tree, usually /lib/modules/$KERNEL/kernel/drivers/char/drm, where $KERNEL is the kernel you built against. On 2.6.x kernels make sure that you also copy drm.ko. Finally, run depmod -a, or depmod -a $KERNEL if you built against a different kernel.
For example, do the following as root to install the just built DRM 2.6 kernel modules:
mkdir -p /lib/modules/$KERNEL/kernel/drivers/char/drm cp *.ko /lib/modules/$KERNEL/kernel/drivers/char/drm depmod -a $KERNEL
1.8. Building the DRM on FreeBSD
The DRM is shipped with the kernel, so you shouldn't need to build it. If you choose to, simply run "make && make install" from the drm/bsd-core directory.
1.9. Finishing up
There are two things you have to do if you compiled X.org for the first time and were using XFree86 before. There should be a symbolic link /etc/X11/X that points to /usr/X11R6/bin/XFree86. You should make that link point to /usr/X11R6/bin/Xorg.
cd /etc/X11 mv X X.backup ln -s /usr/X11R6/bin/Xorg X
Copy your XF86Config-4 or XF86Config to xorg.conf, and in this file change the keyboard driver from keyboard to kbd.
Section "Input"
# ...
Driver "kbd"
# ...
EndSectionIn order to activate 3D acceleration make sure your xorg.conf is set up right. In particular, make sure the GLX and DRI modules are being loaded:
Section "Module"
# ...
Load "glx"
Load "dri"
# ...
EndSectionand set the permissions for DRI appropriately. To allow anyone to use DRI, do:
Section "DRI"
Mode 0666
EndSectionTo restrict DRI access to a certain group, find on your system the name of the group that is for video hardware access. (Have a look in /etc/group. It is often called video.) Add the users that may access the video hardware to that group. Then put this into xorg.conf:
Section "DRI"
Group "video"
Mode 0660
EndSectionOn Linux 2.4.x make sure the agpgart kernel module is loaded before you start X. On Linux 2.6.x make sure both agpgart and the agp chipset specific driver for your motherboard (via_agp, intel_agp, et al.) are loaded before you start X. To make the agp modules load automatically add these lines to your modules.conf:
2.4.x kernels:
pre-install <drm module> /sbin/modprobe "-k" "agpgart"
2.6.x kernels:
pre-install <drm module> /sbin/modprobe "-k" "agpgart" pre-install agpgart /sbin/modprobe "-k" "<agp chipset driver>"
Replace <drm module> with the name of the drm module for your video card (e.g., radeon, mga, savage, etc.). Replace <agp chipset driver> with the name of the agp driver for your motherboard (e.g., via_agp, intel_agp, etc.).
For all kernels, make sure the DRM module is loaded before you start X.
Remember to restart X so the server will use the new modules.
2. Troubleshooting
If your issue isn't covered here, please report it on #dri on IRC or on the dri-users mailing list. This section only covers build-time troubleshooting; for run-time issues see DriTroubleshooting.
2.1. I cannot load my new DRM module on Linux Kernel 2.6.1
FATAL: Error inserting via (/lib/modules/2.6.1/kernel/ drivers/char/drm/<module name>.ko): Unknown symbol in module, or unknown parameter (see dmesg)
This error occurs because there are some missing symbols in the 2.6.1 kernel source. One way to get around this problem is to upgrade your kernel to a newer version... (You *might* be able to patch the DRM code to avoid this... Not sure about this, though!)
2.2. Can't find 'X11/Xlibint.h'
You need to have the headers for your current X version installed. How you install these depends on how you installed X in the first place:
If you downloaded a binary from xfree86.org, the headers are in Xprog.tgz.
For Slackware the package is called xfree86-devel.
Redhat/Fedora and SuSE users should install the appropriate XFree86-devel package.
Mandrake calls this package libxfree86-devel for some reason.
Debian users should use xlibs-dev.
Gentoo users only need to make sure xfree or xorg-x11 have already been emerged.
2.3. Compilation fails when building the kernel modules
When building the kernel modules, the compilation might fail for some modules. In a recent CVS snapshot, I got the following:
savage_drv.c: In function `savage_alloc_continuous_mem': savage_drv.c:106: warning: passing arg 1 of `remap_page_range_Rc414bdc2' makes pointer from integer without a cast savage_drv.c:106: incompatible type for argument 4 of `remap_page_range_Rc414bdc2' savage_drv.c:106: too few arguments to function `remap_page_range_Rc414bdc2' savage_drv.c: In function `savage_get_physics_address': savage_drv.c:170: warning: implicit declaration of function `pte_offset' savage_drv.c:170: warning: assignment makes pointer from integer without a cast make[2]: *** [savage_drv.o] Error 1
You can avoid this problem by only building the modules you need. See the DRM section above for the bit about the DRM_MODULES variable.
2.4. xf86cfg doesn't compile/link
xf86cfg requires libXaw (and appropriate headers) to be installed in order to build. You can either install the relevant packages for your distribution, or else add the line:
#define BuildXFree86ConfigTools NO
to your config/cf/host.def and rerun make World.
ToDo: fill this in with package names, as above.
2.5. I'm using Gentoo and...
Gentoo has its own How-To on their website -- http://www.gentoo.org/doc/en/dri-howto.xml
For those who enabled DRI via the instructions here...
There is a known issue with Gentoo's OpenGL package switch; when the opengl-update package is installed, Gentoo places OpenGL libraries and header files under /usr/lib/opengl and uses symlinks to make everything appear in the normal place. As a result the normal install process doesn't always work.
Try setting up a "fake" OpenGL package, and switch into it:
cd /usr/lib/opengl mkdir mesa-cvs cd mesa-cvs ln -s ../../../local/lib ln -s ../../../local/include ln -s ../xorg-x11/extensions opengl-update mesa-cvs
This assumes you installed Mesa (including libGL) into /usr/local, which is the default. Also, you may like to remove everything in /usr/local/lib from Mesa that isn't either libGL.* or libGLU.* -- things like libGLw.* can cause problems.
If you set things up differently, a way to check whether you are affected by opengl-update is to strace any OpenGL based program (for example: glxgears) and to see which libGL.so it loads. Despite all symlinks it should load /usr/lib/libGL.so.1.2. If it doesn't correct the symlinks in /usr/lib to point to /usr/lib/libGL.so.1.2. After that don't run opengl-update -- it will only break things.
3. References
- Old DRI building guide http://dri.sourceforge.net/cgi-bin/moin.cgi/RecentChanges