doc/en/dri-howto.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/dri-howto.xml,v 1.24 2005/07/30 09:47:30 neysx Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/doc/en/dri-howto.xml">
<title>Hardware 3D Acceleration Guide</title>
<author title="Author">
<mail link="spyderous@gentoo.org">Donnie Berkholz</mail>
</author>
<author title="Editor">
<mail link="peesh@gentoo.org">Jorge Paulo</mail>
</author>

<abstract>
This document is a guide to getting 3D acceleration working using X11-DRM 
with Xorg in Gentoo Linux.
</abstract>

<license/>

<version>1.0.13</version>
<date>2005-07-30</date>

<chapter>
<title>Introduction</title>
<section>
<title>What is hardware 3D acceleration and why do I want it?</title>
<body>

<p>
With hardware 3D acceleration, three-dimensional rendering uses the graphics 
processor on your video card instead of taking up valuable CPU resources 
drawing 3D images. It's also referred to as "hardware acceleration" instead of 
"software acceleration" because without this 3D acceleration your CPU is forced
to draw everything itself using the Mesa software rendering libraries, which 
takes up quite a bit of processing power. While Xorg typically supports 2D
hardware acceleration, it often lacks hardware 3D acceleration. 
Three-dimensional hardware acceleration is valuable in situations requiring 
rendering of 3D objects such as games, 3D CAD and modeling.
</p>

</body>
</section>
<section>
<title>How do I get hardware 3D acceleration?</title>
<body>

<p>
In many cases, both binary and open-source drivers exist. Open-source drivers 
are preferable since we're using Linux and open source is one of its underlying
principles. Sometimes, binary drivers are the only option, like with nVidia's 
cards. Binary drivers include media-video/nvidia-kernel and 
media-video/nvidia-glx for nVidia cards, media-video/mgavideo for Matrox cards 
and media-video/ati-drivers for ATI cards. Other open-source drivers include 
media-video/kyro-kernel for KyroII cards and media-video/ati-gatos for ATI 
cards, which aim to support ATI's video capabilities more fully.
</p>

</body>
</section>
<section>
<title>What is DRI?</title>
<body>

<p>
The <uri link="http://dri.freedesktop.org/wiki/">Direct Rendering
Infrastructure</uri>, also known as the DRI, is a framework for allowing direct
access to graphics hardware in a safe and efficient manner. It includes changes
to the X server, to several client libraries and to the kernel. The first major
use for the DRI is to create fast OpenGL implementations.
</p>

</body>
</section>
<section>
<title>What is X11-DRM and how does it relate to regular Xorg?</title>
<body>

<p>
X11-DRM is an <e>enhancement</e> to Xorg that adds 3D acceleration for 
cards by adding the kernel module necessary for direct rendering.
</p>

</body>
</section>
<section>
<title>Purpose</title>
<body>

<p>
This guide is for people who can't get direct rendering working with just Xorg.
X11-DRM works for 3dfx, gamma, i8x0, matrox, rage128, radeon, mach64 and sis300
series drivers. See the <uri link="http://dri.freedesktop.org/">DRI
homepage</uri> for more info and documentation.
</p>

</body>
</section>
<section>
<title>Feedback</title>
<body>

<p>
With suggestions, questions, etc., e-mail <mail 
link="spyderous@gentoo.org">Donnie Berkholz</mail>.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Install Xorg and configure your kernel</title>
<section>
<title>Install Xorg</title>
<body>

<p>
Please read our <uri link="/doc/en/xorg-config.xml">Xorg Configuration
Guide</uri> to get Xorg up and running.
</p>

</body>
</section>
<section>
<title>Configure your kernel</title>
<body>

<p>
Probe for your chipset and enable just that one.
</p>

<pre caption="Checking your AGP chipset">
# <i>emerge pciutils; lspci | grep AGP</i>
# <i>00:01.0 PCI bridge: Intel Corp. 440BX/ZX/DX - 82443BX/ZX/DX AGP bridge (rev 03)</i>
<comment>(Your output may not match the above due to different hardware.)</comment>
</pre>

<p>
If your chipset is not supported by the kernel you might have some succes by
passing <c>agp=try_unsupported</c> as a kernel parameter. This will use Intel's
generic routines for AGP support. To add this parameter, edit your bootloader
configuration file!
</p>

<p>
Most, if not all, kernels should have these options. This was configured using 
gentoo-sources-2.4.20-r5.
</p>

<pre caption="Configuring the kernel">
# <i>ls -l /usr/src/linux </i>
lrwxrwxrwx    1 root     root           22 May 29 18:20 /usr/src/linux -> linux-2.4.20-gentoo-r5
<comment>(Make sure /usr/src/linux links to your current kernel.)</comment>
# <i>cd /usr/src/linux</i>
# <i>make menuconfig</i>
</pre>

<pre caption="make menuconfig options">
Processor type and features ---&gt;
&lt;*&gt; MTRR (Memory Type Range Register) support
Character devices ---&gt;
&lt;M&gt; /dev/agpgart (AGP Support)
[*] Intel 440LX/BX/GX and I815/I820/I830M/I830MP/I840/I845/I850/I860 support
<comment>(Enable your chipset instead of the above.)</comment>
&lt; &gt; Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)
</pre>

<p>
If you use a 2.4 kernel, make sure the Direct Rendering Manager (DRM) is 
<e>off</e>. The X11-DRM package will provide its own. 2.6 kernel users should
<e>enable</e> the Direct Rendering Manager (DRM) as the X11-DRM package
currently does not support 2.6 kernels yet.
</p>

</body>
</section>
<section>
<title>Compile and install your kernel</title>
<body>

<pre caption="Compiling and installing kernel">
# <i>make dep &amp;&amp; make clean bzImage modules modules_install</i>
# <i>mount /boot</i>
# <i>cp arch/i386/boot/bzImage /boot</i>
</pre>

<p>
If you want your kernel to be named something other than bzImage, be sure to 
copy to /boot/yourname instead. Don't forget to set up grub.conf or lilo.conf 
and run /sbin/lilo if you use LILO.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Install X11-DRM and configure direct rendering</title>
<section>
<title>Install X11-DRM</title>
<body>

<warn>
If you are a 2.6 kernel user, skip this section and go to <uri
link="#configure_xorg">Configure Xorg.conf</uri>.
</warn>

<pre caption="Installing X11-DRM">
# <i>emerge x11-drm</i>
</pre>

</body>
</section>
<section id="configure_xorg">
<title>Configure Xorg.conf</title>
<body>

<p>
Some chipsets require you to rebuild <c>xorg-x11</c> with 
<c>USE="insecure-drivers"</c>. This applies to mach64, unichrome and savage 
chipsets on xorg-x11-6.8.2, and to mach64 and unichrome on xorg-x11-6.8.99.x.
Savage users should not try xorg-x11-6.8.99.x as support for the savage there
is broken.
</p>

<pre caption="Rebuilding xorg-x11">
# <i>vim /etc/portage/package.use</i>
<comment>(Add the following line if you use one of the abovementioned chipsets)</comment>
x11-base/xorg-x11 insecure-drivers

# <i>emerge xorg-x11</i>
</pre>

<p>
Open <path>/etc/X11/xorg.conf</path> with your favorite text editor and edit 
it to enable DRI and GLX.
</p>

<pre caption="xorg.conf">
...
Section "Module"
  Load "dri"
  Load "glx"
  ...
EndSection
...
Section "Device"
  Driver "radeon"
  ...
EndSection
...
Section "dri"
  Mode 0666
EndSection
</pre>

<p>
If you are using a different driver, replace "radeon" with yours.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Test 3D acceleration</title>
<section>
<title>Reboot to the new kernel</title>
<body>

<p>
Reboot your computer to your new kernel. It's time to see if you have direct 
rendering and how good it is.
</p>

<pre caption="Testing rendering">
# <i>startx</i>
<comment>(No need to load modules for your driver or agpgart, if you compiled agpgart as a module.)</comment>
<comment>(They will be loaded automatically.)</comment>
# <i>glxinfo | grep rendering</i>
direct rendering: Yes
<comment>(If it says "No," you don't have 3D acceleration.)</comment>
# <i>glxgears</i>
<comment>(Test your frames per second (FPS) at the default size. The number should be )</comment>
<comment>(significantly higher than before installing x11-drm. Do this while the CPU is as idle as possible.)</comment>
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Using the CVS sources</title>
<section>
<body>

<warn>
Don't do this if the package worked.
</warn>

</body>
</section>
<section>
<title>Do you need the CVS?</title>
<body>

<p>
First you have to check whether the x11-drm package works. If it doesn't and 
you have checked your logs to verify it's not a configuration error, you might 
want to consider the CVS sources. There are also daily driver snapshots 
available if you do not wish to build the full CVS.
</p>

</body>
</section>
<section>
<title>Do the CVS sources support your card?</title>
<body>

<p>
Check the DRI <uri link="http://dri.freedesktop.org/wiki/Status">supported
cards list</uri> to see if the CVS supports your card. Even if it doesn't, but
it supports a similar card, try it.
</p>

<!-- I see a couple of 8x AGP stuff on the Internet about vanilla 2.4 kernels;
     is this now available or not? I've commented it out for the time being,
     hoping that this doesn't affect us :)

<warn>
"Linux 2.4 doesn't support agp 8x, so I had to go find a backport. The backport 
works .... it doesn't patch quite properly, and it requires 2.4.21 (I've only 
gotten it to work with vanilla, straight from the tarball (not ebuild)). First 
go get the 2.4.20-2.4.21 patch from kernel.org .... (then get the patch,) It 
was on a mailing list somewhere. It doesn't patch cleanly - - one file fails, 
the pci_ids.h file, but if you actually read the file and the reject list, it's
very easy to fix. But it does load, and it gives me 1600x1200 with video 
(although a bit slow b/c of lack of dga) with xfree-drm." (SanityInAnarchy on 
#gentoo)
</warn>

<impo>
The patch is a little tricky to work with but <uri 
link="http://www.ussg.iu.edu/hypermail/linux/kernel/0302.2/att-1618/01-agp3.diff.bz2">here's 
the link</uri>. If you can disable 8X AGP in your BIOS, change it to 4X and you 
may not need the patch.
</impo>
-->

</body>
</section>
<section>
<title>Follow the CVS Instructions</title>
<body>

<p>
The DRI project has a document about CVS compiling themselves. Please read <uri
link="http://dri.freedesktop.org/wiki/Building">the document</uri> and follow
the instructions up to the <e>Installing for X.org</e> part.
</p>

</body>
</section>
<section>
<title>Install the CVS</title>
<body>

<p>
Verify that the DRI kernel module(s) for your system were built:
</p>

<pre caption="Verification">
# <i>cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel; ls</i>
</pre>

<p>
For the 3dfx Voodoo, you should see <path>tdfx.o</path>. For the Matrox 
G200/G400, you should see <path>mga.o</path>. For the ATI Rage 128, you should 
see <path>r128.o</path>. For the ATI Radeon, you should see 
<path>radeon.o</path>. For the Intel i810, you should see <path>i810.o</path>. 
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.
</p>

<p>
Install over your X.org installation. You may wish to back up xorg-x11.
</p>

<pre caption="Backing up Xorg">
# <i>quickpkg xorg-x11</i>
<comment>(This backs up your Xorg-X11 package.)</comment>
# <i>make install</i>
</pre>

<p>
Follow the "Configure Xorg" section above.
</p>

<p>
To load the appropriate DRM module in your running kernel, copy the kernel 
module to <path>/lib/modules/`uname -r`/kernel/drivers/char/drm/</path> then 
run <c>modules-update</c> and restart your X server. If you're not running the 
kernel you'll be using it in, instead of <c>`uname -r`,</c> use that kernel's 
name.
</p>

<warn>
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.
</warn>

</body>
</section>
</chapter>

<chapter>
<title>Tweak your performance</title>
<section>
<title>Get the most out of direct rendering</title>
<body>

<p>
A few options may increase performance by up to 30 percent (or more) over the 
default. Set them in <path>/etc/X11/xorg.conf</path>.
</p>

<pre caption="xorg.conf">
Section "Device"
  Option     "AGPMode" "4"
  <comment>(This increased FPS from 609 to 618.)</comment>
  Option     "AGPFastWrite" "True"
  <comment>(This had no measurable effect, but it may increase instability of your computer.)</comment>
  <comment>(You may also need to set it in your BIOS.)</comment>
  Option     "EnablePageFlip" "True"
  <comment>(This improved FPS from 618 to 702. It also is "risky" but few people have reported problems.)</comment>
  ...
EndSection
</pre>

<p>
If you want to set even more features, check out the <uri
link="http://dri.freedesktop.org/wiki/FeatureMatrix">feature matrix</uri> on
the DRI web site or the <uri
link="http://dri.sourceforge.net/doc/dri_driver_features.phtml">features
listing</uri> on Sourceforge.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Troubleshooting</title>
<section>
<title>It doesn't work. I just recompiled my kernel or switched to a new one.</title>
<body>

<p>
Whenever you rebuild your kernel or switch to another kernel, you'll have to
rebuild the kernel module.  Note that you don't need to remerge xorg-x11, but
you will need to remerge x11-drm.
</p>

</body>
</section>

<section>
<title>It doesn't work. I don't have rendering, and I can't tell why.</title>
<body>

<p>
Try <c>insmod radeon</c> before you start the X server. Also, try building 
agpgart into the kernel instead of as a module.
</p>

</body>
</section>
<section>
<title>When I startx, I get this error: "[drm] failed to load kernel module agpgart"</title>
<body>

<p>
That's because you compiled agpgart into the kernel instead of as a module. 
Ignore it unless you're having problems.
</p>

</body>
</section>
<section>
<title>Direct rendering doesn't work, and in /var/log/Xorg.0.log I have an error about driver version too low.</title>
<body>

<p>
You aren't using the x11-drm driver. Check if you compiled DRM and the driver 
into the kernel; you shouldn't have.
</p>

</body>
</section>
<section>
<title>I have a Radeon, and I want TV-Out.</title>
<body>

<p>
Check out ati-gatos drivers. <c>emerge -s gatos</c>.
</p>

</body>
</section>
<section>
<title>It doesn't work. My card is so incredibly new and cool that it isn't supported at all.</title>
<body>

<p>
Try out the binary drivers. For ati-drivers, a listing is at 
<uri>http://www.schneider-digital.de/html/download_ati.php</uri>. If those 
don't support it, use fbdev. It's slow, but it works.
</p>

</body>
</section>
<section>
<title>I have a PCI card and it doesn't work.  Help!</title>
<body>

<p>
In section "Device" enable ForcePCIMode. 
</p>

<pre caption="Enabling ForcePCIMode">
Option "ForcePCIMode" "True"
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Acknowledgments</title>
<section>
<body>

<ol>
  <li>
    Christopher Webber for suggesting a troubleshooting question about changing 
    or recompiling kernels
  </li>
  <li>
    Steve, for suggesting consistency between the cases of dri and DRI in 
    XF86Config
  </li>
</ol>

</body>
</section>
</chapter>

<chapter>
<title>References</title>
<section>
<body>

<ol>
  <li><uri>http://forums.gentoo.org/viewtopic.php?t=46681</uri></li>
  <li><uri>http://forums.gentoo.org/viewtopic.php?t=29264</uri></li>
  <li><uri>http://dri.freedesktop.org/</uri></li>
  <li><uri>http://www.retinalburn.net/linux/dri_status.html</uri></li>
</ol>

</body>
</section>
</chapter>
</guide>
1	<?xml version="1.0" encoding="UTF-8"?>
2	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/dri-howto.xml,v 1.24 2005/07/30 09:47:30 neysx Exp $ -->
3	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5	<guide link="/doc/en/dri-howto.xml">
6	<title>Hardware 3D Acceleration Guide</title>
7	<author title="Author">
8	<mail link="spyderous@gentoo.org">Donnie Berkholz</mail>
9	</author>
10	<author title="Editor">
11	<mail link="peesh@gentoo.org">Jorge Paulo</mail>
12	</author>
13
14	<abstract>
15	This document is a guide to getting 3D acceleration working using X11-DRM
16	with Xorg in Gentoo Linux.
17	</abstract>
18
19	<license/>
20
21	<version>1.0.13</version>
22	<date>2005-07-30</date>
23
24	<chapter>
25	<title>Introduction</title>
26	<section>
27	<title>What is hardware 3D acceleration and why do I want it?</title>
28	<body>
29
30	<p>
31	With hardware 3D acceleration, three-dimensional rendering uses the graphics
32	processor on your video card instead of taking up valuable CPU resources
33	drawing 3D images. It's also referred to as "hardware acceleration" instead of
34	"software acceleration" because without this 3D acceleration your CPU is forced
35	to draw everything itself using the Mesa software rendering libraries, which
36	takes up quite a bit of processing power. While Xorg typically supports 2D
37	hardware acceleration, it often lacks hardware 3D acceleration.
38	Three-dimensional hardware acceleration is valuable in situations requiring
39	rendering of 3D objects such as games, 3D CAD and modeling.
40	</p>
41
42	</body>
43	</section>
44	<section>
45	<title>How do I get hardware 3D acceleration?</title>
46	<body>
47
48	<p>
49	In many cases, both binary and open-source drivers exist. Open-source drivers
50	are preferable since we're using Linux and open source is one of its underlying
51	principles. Sometimes, binary drivers are the only option, like with nVidia's
52	cards. Binary drivers include media-video/nvidia-kernel and
53	media-video/nvidia-glx for nVidia cards, media-video/mgavideo for Matrox cards
54	and media-video/ati-drivers for ATI cards. Other open-source drivers include
55	media-video/kyro-kernel for KyroII cards and media-video/ati-gatos for ATI
56	cards, which aim to support ATI's video capabilities more fully.
57	</p>
58
59	</body>
60	</section>
61	<section>
62	<title>What is DRI?</title>
63	<body>
64
65	<p>
66	The <uri link="http://dri.freedesktop.org/wiki/">Direct Rendering
67	Infrastructure</uri>, also known as the DRI, is a framework for allowing direct
68	access to graphics hardware in a safe and efficient manner. It includes changes
69	to the X server, to several client libraries and to the kernel. The first major
70	use for the DRI is to create fast OpenGL implementations.
71	</p>
72
73	</body>
74	</section>
75	<section>
76	<title>What is X11-DRM and how does it relate to regular Xorg?</title>
77	<body>
78
79	<p>
80	X11-DRM is an <e>enhancement</e> to Xorg that adds 3D acceleration for
81	cards by adding the kernel module necessary for direct rendering.
82	</p>
83
84	</body>
85	</section>
86	<section>
87	<title>Purpose</title>
88	<body>
89
90	<p>
91	This guide is for people who can't get direct rendering working with just Xorg.
92	X11-DRM works for 3dfx, gamma, i8x0, matrox, rage128, radeon, mach64 and sis300
93	series drivers. See the <uri link="http://dri.freedesktop.org/">DRI
94	homepage</uri> for more info and documentation.
95	</p>
96
97	</body>
98	</section>
99	<section>
100	<title>Feedback</title>
101	<body>
102
103	<p>
104	With suggestions, questions, etc., e-mail <mail
105	link="spyderous@gentoo.org">Donnie Berkholz</mail>.
106	</p>
107
108	</body>
109	</section>
110	</chapter>
111
112	<chapter>
113	<title>Install Xorg and configure your kernel</title>
114	<section>
115	<title>Install Xorg</title>
116	<body>
117
118	<p>
119	Please read our <uri link="/doc/en/xorg-config.xml">Xorg Configuration
120	Guide</uri> to get Xorg up and running.
121	</p>
122
123	</body>
124	</section>
125	<section>
126	<title>Configure your kernel</title>
127	<body>
128
129	<p>
130	Probe for your chipset and enable just that one.
131	</p>
132
133	<pre caption="Checking your AGP chipset">
134	# <i>emerge pciutils; lspci \| grep AGP</i>
135	# <i>00:01.0 PCI bridge: Intel Corp. 440BX/ZX/DX - 82443BX/ZX/DX AGP bridge (rev 03)</i>
136	<comment>(Your output may not match the above due to different hardware.)</comment>
137	</pre>
138
139	<p>
140	If your chipset is not supported by the kernel you might have some succes by
141	passing <c>agp=try_unsupported</c> as a kernel parameter. This will use Intel's
142	generic routines for AGP support. To add this parameter, edit your bootloader
143	configuration file!
144	</p>
145
146	<p>
147	Most, if not all, kernels should have these options. This was configured using
148	gentoo-sources-2.4.20-r5.
149	</p>
150
151	<pre caption="Configuring the kernel">
152	# <i>ls -l /usr/src/linux </i>
153	lrwxrwxrwx 1 root root 22 May 29 18:20 /usr/src/linux -> linux-2.4.20-gentoo-r5
154	<comment>(Make sure /usr/src/linux links to your current kernel.)</comment>
155	# <i>cd /usr/src/linux</i>
156	# <i>make menuconfig</i>
157	</pre>
158
159	<pre caption="make menuconfig options">
160	Processor type and features --->
161	<*> MTRR (Memory Type Range Register) support
162	Character devices --->
163	<M> /dev/agpgart (AGP Support)
164	[*] Intel 440LX/BX/GX and I815/I820/I830M/I830MP/I840/I845/I850/I860 support
165	<comment>(Enable your chipset instead of the above.)</comment>
166	< > Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)
167	</pre>
168
169	<p>
170	If you use a 2.4 kernel, make sure the Direct Rendering Manager (DRM) is
171	<e>off</e>. The X11-DRM package will provide its own. 2.6 kernel users should
172	<e>enable</e> the Direct Rendering Manager (DRM) as the X11-DRM package
173	currently does not support 2.6 kernels yet.
174	</p>
175
176	</body>
177	</section>
178	<section>
179	<title>Compile and install your kernel</title>
180	<body>
181
182	<pre caption="Compiling and installing kernel">
183	# <i>make dep && make clean bzImage modules modules_install</i>
184	# <i>mount /boot</i>
185	# <i>cp arch/i386/boot/bzImage /boot</i>
186	</pre>
187
188	<p>
189	If you want your kernel to be named something other than bzImage, be sure to
190	copy to /boot/yourname instead. Don't forget to set up grub.conf or lilo.conf
191	and run /sbin/lilo if you use LILO.
192	</p>
193
194	</body>
195	</section>
196	</chapter>
197
198	<chapter>
199	<title>Install X11-DRM and configure direct rendering</title>
200	<section>
201	<title>Install X11-DRM</title>
202	<body>
203
204	<warn>
205	If you are a 2.6 kernel user, skip this section and go to <uri
206	link="#configure_xorg">Configure Xorg.conf</uri>.
207	</warn>
208
209	<pre caption="Installing X11-DRM">
210	# <i>emerge x11-drm</i>
211	</pre>
212
213	</body>
214	</section>
215	<section id="configure_xorg">
216	<title>Configure Xorg.conf</title>
217	<body>
218
219	<p>
220	Some chipsets require you to rebuild <c>xorg-x11</c> with
221	<c>USE="insecure-drivers"</c>. This applies to mach64, unichrome and savage
222	chipsets on xorg-x11-6.8.2, and to mach64 and unichrome on xorg-x11-6.8.99.x.
223	Savage users should not try xorg-x11-6.8.99.x as support for the savage there
224	is broken.
225	</p>
226
227	<pre caption="Rebuilding xorg-x11">
228	# <i>vim /etc/portage/package.use</i>
229	<comment>(Add the following line if you use one of the abovementioned chipsets)</comment>
230	x11-base/xorg-x11 insecure-drivers
231
232	# <i>emerge xorg-x11</i>
233	</pre>
234
235	<p>
236	Open <path>/etc/X11/xorg.conf</path> with your favorite text editor and edit
237	it to enable DRI and GLX.
238	</p>
239
240	<pre caption="xorg.conf">
241	...
242	Section "Module"
243	Load "dri"
244	Load "glx"
245	...
246	EndSection
247	...
248	Section "Device"
249	Driver "radeon"
250	...
251	EndSection
252	...
253	Section "dri"
254	Mode 0666
255	EndSection
256	</pre>
257
258	<p>
259	If you are using a different driver, replace "radeon" with yours.
260	</p>
261
262	</body>
263	</section>
264	</chapter>
265
266	<chapter>
267	<title>Test 3D acceleration</title>
268	<section>
269	<title>Reboot to the new kernel</title>
270	<body>
271
272	<p>
273	Reboot your computer to your new kernel. It's time to see if you have direct
274	rendering and how good it is.
275	</p>
276
277	<pre caption="Testing rendering">
278	# <i>startx</i>
279	<comment>(No need to load modules for your driver or agpgart, if you compiled agpgart as a module.)</comment>
280	<comment>(They will be loaded automatically.)</comment>
281	# <i>glxinfo \| grep rendering</i>
282	direct rendering: Yes
283	<comment>(If it says "No," you don't have 3D acceleration.)</comment>
284	# <i>glxgears</i>
285	<comment>(Test your frames per second (FPS) at the default size. The number should be )</comment>
286	<comment>(significantly higher than before installing x11-drm. Do this while the CPU is as idle as possible.)</comment>
287	</pre>
288
289	</body>
290	</section>
291	</chapter>
292
293	<chapter>
294	<title>Using the CVS sources</title>
295	<section>
296	<body>
297
298	<warn>
299	Don't do this if the package worked.
300	</warn>
301
302	</body>
303	</section>
304	<section>
305	<title>Do you need the CVS?</title>
306	<body>
307
308	<p>
309	First you have to check whether the x11-drm package works. If it doesn't and
310	you have checked your logs to verify it's not a configuration error, you might
311	want to consider the CVS sources. There are also daily driver snapshots
312	available if you do not wish to build the full CVS.
313	</p>
314
315	</body>
316	</section>
317	<section>
318	<title>Do the CVS sources support your card?</title>
319	<body>
320
321	<p>
322	Check the DRI <uri link="http://dri.freedesktop.org/wiki/Status">supported
323	cards list</uri> to see if the CVS supports your card. Even if it doesn't, but
324	it supports a similar card, try it.
325	</p>
326
327	<!-- I see a couple of 8x AGP stuff on the Internet about vanilla 2.4 kernels;
328	is this now available or not? I've commented it out for the time being,
329	hoping that this doesn't affect us :)
330
331	<warn>
332	"Linux 2.4 doesn't support agp 8x, so I had to go find a backport. The backport
333	works .... it doesn't patch quite properly, and it requires 2.4.21 (I've only
334	gotten it to work with vanilla, straight from the tarball (not ebuild)). First
335	go get the 2.4.20-2.4.21 patch from kernel.org .... (then get the patch,) It
336	was on a mailing list somewhere. It doesn't patch cleanly - - one file fails,
337	the pci_ids.h file, but if you actually read the file and the reject list, it's
338	very easy to fix. But it does load, and it gives me 1600x1200 with video
339	(although a bit slow b/c of lack of dga) with xfree-drm." (SanityInAnarchy on
340	#gentoo)
341	</warn>
342
343	<impo>
344	The patch is a little tricky to work with but <uri
345	link="http://www.ussg.iu.edu/hypermail/linux/kernel/0302.2/att-1618/01-agp3.diff.bz2">here's
346	the link</uri>. If you can disable 8X AGP in your BIOS, change it to 4X and you
347	may not need the patch.
348	</impo>
349	-->
350
351	</body>
352	</section>
353	<section>
354	<title>Follow the CVS Instructions</title>
355	<body>
356
357	<p>
358	The DRI project has a document about CVS compiling themselves. Please read <uri
359	link="http://dri.freedesktop.org/wiki/Building">the document</uri> and follow
360	the instructions up to the <e>Installing for X.org</e> part.
361	</p>
362
363	</body>
364	</section>
365	<section>
366	<title>Install the CVS</title>
367	<body>
368
369	<p>
370	Verify that the DRI kernel module(s) for your system were built:
371	</p>
372
373	<pre caption="Verification">
374	# <i>cd ~/DRI-CVS/build/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel; ls</i>
375	</pre>
376
377	<p>
378	For the 3dfx Voodoo, you should see <path>tdfx.o</path>. For the Matrox
379	G200/G400, you should see <path>mga.o</path>. For the ATI Rage 128, you should
380	see <path>r128.o</path>. For the ATI Radeon, you should see
381	<path>radeon.o</path>. For the Intel i810, you should see <path>i810.o</path>.
382	If the DRI kernel module(s) failed to build, you should verify that you're
383	using the right version of the Linux kernel. The most recent kernels are not
384	always supported.
385	</p>
386
387	<p>
388	Install over your X.org installation. You may wish to back up xorg-x11.
389	</p>
390
391	<pre caption="Backing up Xorg">
392	# <i>quickpkg xorg-x11</i>
393	<comment>(This backs up your Xorg-X11 package.)</comment>
394	# <i>make install</i>
395	</pre>
396
397	<p>
398	Follow the "Configure Xorg" section above.
399	</p>
400
401	<p>
402	To load the appropriate DRM module in your running kernel, copy the kernel
403	module to <path>/lib/modules/`uname -r`/kernel/drivers/char/drm/</path> then
404	run <c>modules-update</c> and restart your X server. If you're not running the
405	kernel you'll be using it in, instead of <c>`uname -r`,</c> use that kernel's
406	name.
407	</p>
408
409	<warn>
410	Make sure you first unload any older DRI kernel modules that might be already
411	loaded. Note that some DRM modules require that the agpgart module be loaded
412	first.
413	</warn>
414
415	</body>
416	</section>
417	</chapter>
418
419	<chapter>
420	<title>Tweak your performance</title>
421	<section>
422	<title>Get the most out of direct rendering</title>
423	<body>
424
425	<p>
426	A few options may increase performance by up to 30 percent (or more) over the
427	default. Set them in <path>/etc/X11/xorg.conf</path>.
428	</p>
429
430	<pre caption="xorg.conf">
431	Section "Device"
432	Option "AGPMode" "4"
433	<comment>(This increased FPS from 609 to 618.)</comment>
434	Option "AGPFastWrite" "True"
435	<comment>(This had no measurable effect, but it may increase instability of your computer.)</comment>
436	<comment>(You may also need to set it in your BIOS.)</comment>
437	Option "EnablePageFlip" "True"
438	<comment>(This improved FPS from 618 to 702. It also is "risky" but few people have reported problems.)</comment>
439	...
440	EndSection
441	</pre>
442
443	<p>
444	If you want to set even more features, check out the <uri
445	link="http://dri.freedesktop.org/wiki/FeatureMatrix">feature matrix</uri> on
446	the DRI web site or the <uri
447	link="http://dri.sourceforge.net/doc/dri_driver_features.phtml">features
448	listing</uri> on Sourceforge.
449	</p>
450
451	</body>
452	</section>
453	</chapter>
454
455	<chapter>
456	<title>Troubleshooting</title>
457	<section>
458	<title>It doesn't work. I just recompiled my kernel or switched to a new one.</title>
459	<body>
460
461	<p>
462	Whenever you rebuild your kernel or switch to another kernel, you'll have to
463	rebuild the kernel module. Note that you don't need to remerge xorg-x11, but
464	you will need to remerge x11-drm.
465	</p>
466
467	</body>
468	</section>
469
470	<section>
471	<title>It doesn't work. I don't have rendering, and I can't tell why.</title>
472	<body>
473
474	<p>
475	Try <c>insmod radeon</c> before you start the X server. Also, try building
476	agpgart into the kernel instead of as a module.
477	</p>
478
479	</body>
480	</section>
481	<section>
482	<title>When I startx, I get this error: "[drm] failed to load kernel module agpgart"</title>
483	<body>
484
485	<p>
486	That's because you compiled agpgart into the kernel instead of as a module.
487	Ignore it unless you're having problems.
488	</p>
489
490	</body>
491	</section>
492	<section>
493	<title>Direct rendering doesn't work, and in /var/log/Xorg.0.log I have an error about driver version too low.</title>
494	<body>
495
496	<p>
497	You aren't using the x11-drm driver. Check if you compiled DRM and the driver
498	into the kernel; you shouldn't have.
499	</p>
500
501	</body>
502	</section>
503	<section>
504	<title>I have a Radeon, and I want TV-Out.</title>
505	<body>
506
507	<p>
508	Check out ati-gatos drivers. <c>emerge -s gatos</c>.
509	</p>
510
511	</body>
512	</section>
513	<section>
514	<title>It doesn't work. My card is so incredibly new and cool that it isn't supported at all.</title>
515	<body>
516
517	<p>
518	Try out the binary drivers. For ati-drivers, a listing is at
519	<uri>http://www.schneider-digital.de/html/download_ati.php</uri>. If those
520	don't support it, use fbdev. It's slow, but it works.
521	</p>
522
523	</body>
524	</section>
525	<section>
526	<title>I have a PCI card and it doesn't work. Help!</title>
527	<body>
528
529	<p>
530	In section "Device" enable ForcePCIMode.
531	</p>
532
533	<pre caption="Enabling ForcePCIMode">
534	Option "ForcePCIMode" "True"
535	</pre>
536
537	</body>
538	</section>
539	</chapter>
540
541	<chapter>
542	<title>Acknowledgments</title>
543	<section>
544	<body>
545
546	<ol>
547	<li>
548	Christopher Webber for suggesting a troubleshooting question about changing
549	or recompiling kernels
550	</li>
551	<li>
552	Steve, for suggesting consistency between the cases of dri and DRI in
553	XF86Config
554	</li>
555	</ol>
556
557	</body>
558	</section>
559	</chapter>
560
561	<chapter>
562	<title>References</title>
563	<section>
564	<body>
565
566	<ol>
567	<li><uri>http://forums.gentoo.org/viewtopic.php?t=46681</uri></li>
568	<li><uri>http://forums.gentoo.org/viewtopic.php?t=29264</uri></li>
569	<li><uri>http://dri.freedesktop.org/</uri></li>
570	<li><uri>http://www.retinalburn.net/linux/dri_status.html</uri></li>
571	</ol>
572
573	</body>
574	</section>
575	</chapter>
576	</guide>