diff options
Diffstat (limited to 'xorg-server/hw/xfree86/doc/README.DRIcomp')
| -rw-r--r-- | xorg-server/hw/xfree86/doc/README.DRIcomp | 556 |
1 files changed, 556 insertions, 0 deletions
diff --git a/xorg-server/hw/xfree86/doc/README.DRIcomp b/xorg-server/hw/xfree86/doc/README.DRIcomp new file mode 100644 index 000000000..89f40a759 --- /dev/null +++ b/xorg-server/hw/xfree86/doc/README.DRIcomp @@ -0,0 +1,556 @@ + DRI Compilation Guide + + VA Linux Systems, Inc. Professional Services - Graphics. + + 21 April 2001 + +1. Preamble + +1.1 Copyright + +Copyright 2000-2001 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 and Radeon is a registered trademark of ATI Technolo- +gies, Inc. All other trademarks mentioned are the property of their respec- +tive owners. + +2. Introduction + +This document describes how to download, compile and install the DRI. The +DRI provides 3D graphics hardware acceleration for the XFree86 project. This +information is intended for experienced Linux developers. Beginners are +probably better off installing precompiled packages. + +Edits, corrections and updates to this document may be mailed to <brian@tung- +stengraphics.com>. + +Last updated on 13 February 2002 by Brian Paul. + +3. Prerequisites + +You'll need the following: + + o An installation of XFree86 4.1 or later. The DRI tree has been pruned + down to minimize its size. But in order to build the DRI tree you need + to have recent X header files, etc. already installed. If you don't + have XFree86 4.1 (or later) installed you can probably install it from + RPMs (or another package format). Or, you can download XFree86 as + sources and compile/install it yourself. + + o At least 200MB of free disk space. If you compile for debugging (the -g + option) then you'll need about 600MB. + + o GCC compiler and related tools. + + o ssh (secure shell) if you're a DRI developer and don't want to use + anonymous CVS download. + + o A 2.4.x Linux Kernel. See below for details. + + o FreeBSD support is not currently being maintained and may not work. + +The DRI 3D drivers generally work on systems with Intel or AMD CPUs. How- +ever, limited support for Alpha and PowerPC support is underway. + +For 3dfx Voodoo hardware, you'll also need the Glide3 runtime library +(libglide3-v3.so for Voodoo3 or libglide3-v5.so for Voodoo4/5). These can be +downloaded from the DRI website. You can compile them yourself, but it's +often a painful process. + +For Matrox G200/G400, Intel i810/i830 or ATI Rage128/Radeon hardware, you'll +also need AGP support in your Linux kernel, either built-in or as a loadable +module. + +4. Linux Kernel Preparation + +Only the Linux 2.4.x kernels are currently supported by the DRI hardware +drivers. 2.5.x kernels may work, but aren't tested. + +Most of the DRI drivers require AGP support and using Intel Pentium III SSE +optimizations also requires an up-to-date Linux kernel. Configuring your +kernel correctly is very important, as features such as SSE optimizations +will be disabled if your kernel does not support them. Thus, if you have a +Pentium III processor, you must configure your kernel for the Pentium III +processor family. + +Building a new Linux kernel can be difficult for beginners but there are +resources on the Internet to help. This document assumes experience with +configuring, building and installing Linux kernels. + +Linux kernels can be downloaded from www.kernel.org + +Here are the basic steps for kernel setup. + + o Download the needed kernel and put it in /usr/src. Create a directory + for the source and unpack it. For example: + + cd /usr/src + rm -f linux + mkdir linux-2.4.x + ln -s linux-2.4.x linux + bzcat linux-2.4.x.tar.bz2 | tar xf - + + It is critical that /usr/src/linux point to your new kernel sources, + otherwise the kernel headers will not be used when building the DRI. + This will almost certainly cause compilation problems. + + o Read /usr/src/linux/Documentation/Changes. This file lists the minimum + requirements for all software packages required to build the kernel. + You must upgrade at least gcc, make, binutils and modutils to at least + the versions specified in this file. The other packages may not be + needed. If you are upgrading from Linux 2.2.x you must upgrade your + modutils package for Linux 2.4.x. + + o Configure your kernel. You might, for example, use make menuconfig and + do the following: + + o Go to Code maturity level options + + o Enable Prompt for development and/or incomplete code/drivers + + o hit ESC to return to the top-level menu + + o Go to Processor type and features + + o Select your processor type from Processor Family + + o hit ESC to return to the top-level menu + + o Go to Character devices + + o Disable Direct Rendering Manager (XFree86 DRI support) since we'll + use the DRI code from the XFree86/DRI tree and will compile it + there. + + o Go to /dev/agpgart (AGP Support) (EXPERIMENTAL) (NEW) + + o Hit SPACE twice to build AGP support into the kernel + + o Enable all chipsets' support for AGP + + o It's recommended that you turn on MTRRs under Processor type and + Features, but not required. + + o Configure the rest of the kernel as required for your system (i.e. Eth- + ernet, SCSI, etc) + + o Exit, saving your kernel configuration. + + o Edit your /etc/lilo.conf file. Make sure you have an image entry as + follows (or similar): + + image=/boot/vmlinuz + label=linux.2.4.x + read-only + root=/dev/hda1 + + The important part is that you have /boot/vmlinuz without a trailing + version number. If this is the first entry in your /etc/lilo.conf AND + you haven't set a default, then this will be your default kernel. + + o Compile the new kernel. + + cd /usr/src/linux-2.4.x + make dep + make bzImage + make modules + make modules_install + make install + + Note that last make command will automatically run lilo for you. + + o Now reboot to use the new kernel. + +5. CPU Architectures + +In general, nothing special has to be done to use the DRI on different CPU +architectures. There are, however, a few optimizations that are CPU-depen- +dent. Mesa will determine at runtime which CPU-dependent optimizations +should be used and enable them where appropriate. + +5.1 Intel Pentium III Features + +The Pentium III SSE instructions are used in optimized vertex transformation +functions in the Mesa-based DRI drivers. On Linux, SSE requires a recent +kernel (such as 2.4.0-test11 or later) both at compile time and runtime. + +5.2 AMD 3DNow! Features + +AMD's 3DNow! instructions are used in optimized vertex transformation func- +tions in the Mesa-based DRI drivers. 3DNow! is supported in most versions of +Linux. + +5.3 Alpha Features + +On newer Alpha processors a significant performance increase can be seen with +the addition of the -mcpu= option to GCC. This option is dependent on the +architecture of the processor. For example, -mcpu=ev6 will build specifi- +cally for the EV6 based AXP's, giving both byte and word alignment access to +the DRI/Mesa drivers. + +To enable this optimization edit your xc/config/host.def file and 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 http://www.sup- +port.compaq.com/alpha-tools/software/index.html + +Once installed, you can add this line to your host.def to build with the CPML +libraries: + +#define UseCompaqMathLibrary YES + +The host.def file is explained below. + +6. Downloading the XFree86/DRI CVS Sources + +The DRI project is hosted by SourceForge. The DRI source code, which is a +subset of the XFree86 source tree, is kept in a CVS repository there. + +The DRI CVS sources may be accessed either anonymously or as a registered +SourceForge user. It's recommended that you become a registered SourceForge +user so that you may submit non-anonymous bug reports and can participate in +the mailing lists. + +6.1 Anonymous CVS download: + + 1. Create a directory to store the CVS files: + + cd ~ + mkdir DRI-CVS + + You could put your CVS directory in a different place but we'll use + ~/DRI-CVS/ here. + + 2. Check out the CVS sources: + + cd ~/DRI-CVS + cvs -d:pserver:anonymous@cvs.dri.sourceforge.net:/cvsroot/dri login + (hit ENTER when prompted for a password) + cvs -z3 -d:pserver:anonymous@cvs.dri.sourceforge.net:/cvsroot/dri co xc + + The -z3 flag causes compression to be used in order to reduce the down- + load time. + +6.2 Registered CVS download: + + 1. Create a directory to store the CVS files: + + cd ~ + mkdir DRI-CVS + + You could put your CVS directory in a different place but we'll use + ~/DRI-CVS/ here. + + 2. Set the CVS_RSH environment variable: + + setenv CVS_RSH ssh // if using csh or tcsh + export CVS_RSH=ssh // if using sh or bash + + 3. Check out the CVS sources: + + cd ~/DRI-CVS + cvs -z3 -d:ext:YOURID@cvs.dri.sourceforge.net:/cvsroot/dri co xc + + Replace YOURID with your CVS login name. You'll be prompted to enter + your sourceforge password. + + The -z3 flag causes compression to be used in order to reduce the down- + load time. + +6.3 Updating your CVS sources + +In the future you'll want to occasionally update your local copy of the DRI +source code to get the latest changes. This can be done with: + + cd ~/DRI-CVS + cvs -z3 update -dA xc + +The -d flag causes any new subdirectories to be created and -A causes most +recent trunk sources to be fetched, not branch sources. + +7. Mesa + +Most of the DRI 3D drivers are based on Mesa (the free implementation of the +OpenGL API). The relevant files from Mesa are already included in the +XFree86/DRI source tree. There is no need to download or install the Mesa +source files separately. + +Sometimes a newer version of Mesa will be available than the version included +in XFree86/DRI. Upgrading Mesa within XFree86/DRI is not always straightfor- +ward. It can be an error-prone undertaking, especially for beginners, and is +not generally recommended. The DRI developers will upgrade Mesa when appro- +priate. + +8. Compiling the XFree86/DRI tree + +8.1 Make a build tree + +Rather than placing object files and library files right in the source tree, +they're instead put into a parallel build tree. The build tree is made with +the lndir command: + + cd ~/DRI-CVS + ln -s xc XFree40 + mkdir build + cd build + lndir -silent -ignorelinks ../XFree40 + +The build tree will be populated with symbolic links which point back into +the CVS source tree. + +Advanced users may have several build trees for compiling and testing with +different options. + +8.2 Edit the host.def file + +The ~/DRI-CVS/build/xc/config/cf/host.def file is used to configure the +XFree86 build process. You can change it to customize your build options or +make adjustments for your particular system configuration + +The default host.def file will look something like this: + + #define DefaultCCOptions -Wall + (i386) #define DefaultGcc2i386Opt -O2 + (Alpha) #define DefaultGcc2AxpOpt -O2 -mcpu=ev6 (or similar) + #define LibraryCDebugFlags -O2 + #define BuildServersOnly YES + #define XF86CardDrivers vga tdfx mga ati i810 + #define LinuxDistribution LinuxRedHat + #define DefaultCCOptions -ansi GccWarningOptions -pipe + #define BuildXF86DRI YES + /* Optionally turn these on for debugging */ + /* #define GlxBuiltInTdfx YES */ + /* #define GlxBuiltInMga YES */ + /* #define GlxBuiltInR128 YES */ + /* #define GlxBuiltInRadeon YES */ + /* #define DoLoadableServer NO */ + #define SharedLibFont NO + +The ProjectRoot variable specifies where the XFree86 files will be installed. +We recommend installing the DRI files over your existing XFree86 installation +- it's generally safe to do and less error-prone. This policy is different +than what we used to recommend. + +If XFree86 4.x is not installed in /usr/X11R6/ you'll have to add the follow- +ing to the host.def file: + + #define ProjectRoot pathToYourXFree86installation + +Note the XF86CardDrivers line to be sure your card's driver is listed. + +If you want to enable 3DNow! optimizations in Mesa and the DRI drivers, you +should add the following: + + #define MesaUse3DNow YES + +You don't have to be using an AMD processor in order to enable this option. +The DRI will look for 3DNow! support and runtime and only enable it if appli- +cable. + +If you want to enable SSE optimizations in Mesa and the DRI drivers, you must +upgrade to a Linux 2.4.x kernel. Mesa will verify that SSE is supported by +both your processor and your operating system, but to build Mesa inside the +DRI you need to have the Linux 2.4.x kernel headers in /usr/src/linux. If +you enable SSE optimizations with an earlier version of the Linux kernel in +/usr/src/linux, Mesa will not compile. You have been warned. If you do have +a 2.4.x kernel, you should add the following: + + #define MesaUseSSE YES + +If you want to build the DRM kernel modules as part of the full build pro- +cess, add the following: + + #define BuildXF86DRM YES + +Otherwise, you'll need to build them separately as described below. + +8.3 Compilation + +To compile the complete DRI tree: + + cd ~/DRI-CVS/build/xc/ + make World >& world.log + +Or if you want to watch the compilation progress: + + cd ~/DRI-CVS/build/xc/ + make World >& world.log & + tail -f world.log + +With the default compilation flags it's normal to get a lot of warnings dur- +ing compilation. + +Building will take some time so you may want to go check your email or visit +slashdot. + +WARNING: do not use the -j option with make. It's reported that it does not +work with XFree86/DRI. + +8.4 Check for compilation errors + +Using your text editor, examine world.log for errors by searching for the +pattern ***. + +After fixing the errors, run make World again. Later, you might just compile +parts of the source tree but it's important that the whole tree will build +first. + +If you edited your host.def file to enable automatic building of the DRI ker- +nel module(s), verify that they were built: + + cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel + ls + +Otherwise, build them now by running + + cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel + make -f Makefile.linux + +For the 3dfx Voodoo, you should see tdfx.o. For the Matrox G200/G400, you +should see mga.o. For the ATI Rage 128, you should see r128.o. For the ATI +Radeon, you should see radeon.o. For the Intel i810, you should see i810.o. + +If the DRI kernel module(s) failed to build you should verify that you're +using the right version of the Linux kernel. The most recent kernels are not +always supported. + +If your build machine is running a different version of the kernel than your +target machine (i.e. 2.2.x vs. 2.4.x), make will select the wrong kernel +source tree. This can be fixed by explicitly setting the value of LINUXDIR. +If the path to your kernel source is /usr/src/linux-2.4.x, + + cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel + make -f Makefile.linux LINUXDIR=/usr/src/linux-2.4.x + +or alternatively, edit Makefile.linux to set LINUXDIR before the ifndef LIN- +UXDIR line. + +8.5 DRI kernel module installation + +The DRI kernel modules will be in ~/DRI-CVS/build/xc/pro- +grams/Xserver/hw/xfree86/os-support/linux/drm/kernel/. + +To load the appropriate DRM module in your running kernel you can either use +ismod and restart your X server or copy the kernel module to /lib/mod- +ules/2.4.x/kernel/drivers/char/drm/ then run depmod and restart your X +server. + +Make sure you first unload any older DRI kernel modules that might be already +loaded. + +Note that some DRM modules require that the agpgart module be loaded first. + +9. Normal Installation and Configuration + +Most users will want to install the new X server and use it in place of their +old X server. This section explains how to do that. + +Developers, on the other hand, may just want to test the X server without +actually installing it as their default server. If you want to do that, skip +to the next section. + +9.1 Installation + +Here are the installation commands: + + su + cd ~/DRI-CVS/build/xc + make install + +9.2 Update the XF86Config File + +You may need to edit your XF86Config file to enable the DRI. The config file +is usually installed as /etc/X11/XF86Config-4. See the DRI User Guide for +details, but basically, you need to load the "glx" and "dri" modules and add +a "DRI" section. + +On the DRI web site, in the resources section, you'll find example XF86Config +files for a number of graphics cards. These configuration files also setup +DRI options so it's highly recommended that you look at these examples. + +The XFree86 4.x server can generate a basic configuration file itself. Sim- +ply do this: + + cd /usr/X11R6/bin + ./XFree86 -configure + +A file named /root/XF86Config.new will be created. It should allow you to +try your X server but you'll almost certainly have to edit it. For example, +you should add HorizSync and VertRefresh options to the Monitor section and +Modes options to the Screen section. Also, the ModulePath option in the +Files section should be set to /usr/X11R6/lib/modules. + +9.3 Start the New X Server + +The new X server should be ready to use now. Start your X server in your +usual manner. Often times the startx command is used: + + startx + +10. Testing the Server Without Installing It + +As mentioned at the start of section 9, developers may want to simply run the +X server without installing it. This can save some time and allow you to +keep a number of X servers available for testing. + +10.1 Configuration + +As described in the preceding section, you'll need to create a configuration +file for the new server. Put the XF86Config file in your ~/DRI- +CVS/build/xc/programs/Xserver directory. + +Be sure the ModulePath option in your XF86Config file is set correctly. + +10.2 A Startup Script + +A simple shell script can be used to start the X server. Here's an example. + + #!/bin/sh + export DISPLAY=:0 + ./XFree86 -xf86config XF86Config & \ + sleep 2 + fvwm2 & + xset b off + xmodmap -e "clear mod4" + xsetroot -solid "#00306f" + xterm -geometry 80x40+0+0 + +You might name this script start-dri. Put it in your ~/DRI-CVS/build/xc/pro- +grams/Xserver directory. + +To test the server run the script: + + cd ~/DRI-CVS/build/xc/programs/Xserver + ./start-dri + +For debugging, you may also want to capture the log messages printed by the +server in a file. If you're using the C-shell: + + ./start-dri >& log + +11. Where To Go From Here + +At this point your X server should be up and running with hardware-acceler- +ated direct rendering. Please read the DRI User Guide for information about +trouble shooting and how to use the DRI-enabled X server for 3D applications. + + Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRIcomp.sgml,v 1.19 dawes Exp $ + + |