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.40 2007/08/23 22:31:14 nightmorph 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="dberkholz@gentoo.org">Donnie Berkholz</mail>
</author>
<author title="Editor">
  <mail link="peesh@gentoo.org">Jorge Paulo</mail>
</author>
<author title="Editor">
  <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
</author>

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

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.10</version>
<date>2007-08-23</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 <c>x11-drivers/nvidia-drivers</c> for nVidia cards
and <c>x11-drivers/ati-drivers</c> for ATI cards.
</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 the DRM and how does it relate to regular Xorg?</title>
<body>

<p>
The DRM (Direct Rendering Manager) 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.
The DRM works for the following drivers:
</p>

<ul>
  <li>3dfx</li>
  <li>i8x0</li>
  <li>matrox</li>
  <li>rage128</li>
  <li>radeon</li>
  <li>mach64</li>
  <li>sis300</li>
  <li>via</li>
</ul>

<p>
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="dberkholz@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 a
standard <c>gentoo-sources</c> kernel.
</p>

<pre caption="Configuring the kernel">
# <i>ls -l /usr/src/linux </i>
lrwxrwxrwx 1 root root 22 2007-02-14 20:12 /usr/src/linux -> linux-2.6.18-gentoo-r4
<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 --->
&lt;*&gt; MTRR (Memory Type Range Register) support
Device drivers --->
   Character devices --->
   &lt;M&gt; /dev/agpgart (AGP Support)
   <comment>(The agpgart option is not present on 64-bit kernels; just choose your chipset support.)</comment>
   &lt;M&gt; Intel 440LX/BX/GX, I8xx and E7x05 support
<comment>(Enable your chipset instead of the above.)</comment>
   &lt;M&gt; Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)
</pre>

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

<pre caption="Compiling and installing kernel">
# <i>make &amp;&amp; make modules_install</i>
</pre>

<p>
Don't forget to set up <path>grub.conf</path> or <path>lilo.conf</path> and run
<c>/sbin/lilo</c> if you use LILO.
</p>

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

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

<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"
  <comment>(Replace radeon with the name of your driver.)</comment>
  ...
EndSection
...
Section "dri"
  Mode 0666
EndSection
</pre>

</body>
</section>
<section>
<title>Changes to modules.autoload.d</title>
<body>

<p>
You will need to add the module name that your card uses to
<path>/etc/modules.autoload.d/kernel-2.6</path> to ensure that the module is
loaded automatically when the system starts up.
</p>

<pre caption="Editing /etc/modules.autoload.d/kernel-2.6">
<comment>(Change module name as required.)</comment>
intel-agp
</pre>

<note>
If you compiled <c>agpgart</c> as a module, you will also need to add it to
<path>/etc/modules.autoload.d/kernel-2.6</path>.
</note>

</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 and login as a normal user. It's time to
see if you have direct rendering and how good it is. <c>glxinfo</c> and
<c>glxgears</c> are part of the <c>mesa-progs</c> package, so make sure it is
installed before you attempt to run these commands.
</p>

<pre caption="Testing rendering">
$ <i>startx</i>
<comment>(No need to load modules for your driver or agpgart, even if you compiled them 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
significantly higher than before configuring DRM. Do this while the CPU is as idle as
possible.)</comment>
</pre>

<note>
FPS may be limited by your screen's refresh rate, so keep this in mind if
<c>glxgears</c> reports only about 70-100 FPS. <c>games-fps/ut2004-demo</c> is a
better benchmarking tool, as it can give you real-world performance results.
</note>

</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>. However, you will first
need to check that your motherboard and video card support these options.
</p>

<p>
First, let's see if your video card can support fast writes. We'll do this by
closely inspecting the output from <c>lspci</c>. Specifically, we are looking
at the "VGA compatible controller" information.
</p>

<pre caption="Video card check">
# <i>lspci -vv</i>
01:00.0 VGA compatible controller: ATI Technologies Inc Radeon Mobility M6 LY (prog-if 00 [VGA])
. . .
Capabilities: [58] AGP version 2.0
    Status: RQ=48 Iso- ArqSz=0 Cal=0 SBA+ ITACoh- GART64- HTrans- 64bit- FW+ AGP3- Rate=x1,x2,x4
</pre>

<p>
While quite a lot of information is produced, we are looking for <b>FW</b> in
the "Status" subsection of the AGP "Capabilities" section. If <b>FW+</b> is
present in the "Status" line, it means the card supports fast writes. We can
now check if the motherboard supports fast writes.
</p>

<impo>
If you do not see <b>FW+</b>, but instead see <b>FW-</b>, you cannot enable
fast writes in <path>xorg.conf</path>. Your card does not support fast writes.
</impo>

<p>
Now let's make sure the motherboard supports fast writes as well. This time,
look at the "Host bridge" section of your <c>lspci</c> output.
</p>

<pre caption="Motherboard check">
# <i>lspci -vv</i>
00:00.0 Host bridge: Intel Corporation 82830 830 Chipset Host Bridge (rev 02)
. . .
Capabilities: [a0] AGP version 2.0
    Status: RQ=32 Iso- ArqSz=0 Cal=0 SBA+ ITACoh- GART64- HTrans- 64bit- FW+ AGP3- Rate=x1,x2,x4
</pre>

<p>
Again, examine the "Status" subsection of your AGP "Capabilities" section. Look
for <b>FW</b>. If you see <b>FW+</b>, your motherboard supports fast writes.
</p>

<impo>
Remember, both your video card information and your motherboard information
must show the same <b>FW</b> capability. If either device shows <b>FW-</b> in
"Status", you cannot enable fast writes in <path>xorg.conf</path>.
</impo>

<p>
Assuming that all has gone well and both your motherboard and video card
support fast writes, let's enable this option in
<path>/etc/X11/xorg.conf</path> and get the best performance out of your
hardware.
</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>

<warn>
Enabling <c>AGPFastWrite</c> on a VIA chipset will very likely cause your
machine to lock up. VIA chipsets do not play nicely with fast writes, so use
this setting at your own risk.
</warn>

<note>
Remember, if you want fast writes to work properly, you will have to first
enable the appropriate option in your BIOS.
</note>

<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 don't have rendering, and I can't tell why.</title>
<body>

<p>
Try <c>modprobe radeon</c> before you start the X server (replace <c>radeon</c>
with the name of your driver). 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>I have a Radeon, and I want TV-Out.</title>
<body>

<p>
The drivers originally developed by the <uri
link="http://gatos.sf.net">GATOS</uri> project have been merged into Xorg's
codebase. You don't need anything special for TV-Out;
<c>x11-drivers/xf86-video-ati</c> will work just fine.
</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 <c>ati-drivers</c>, a listing is at
<uri>http://ati.amd.com/support/drivers/linux/linux-radeon.html</uri> (for x86)
and at <uri>http://ati.amd.com/support/drivers/linux64/linux64-radeon.html</uri>
(for amd64). 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>
Edit <path>/etc/X11/xorg.conf</path>. 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.40 2007/08/23 22:31:14 nightmorph Exp $ -->
3	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5	<guide link="/doc/en/dri-howto.xml">
6
7	<title>Hardware 3D Acceleration Guide</title>
8
9	<author title="Author">
10	<mail link="dberkholz@gentoo.org">Donnie Berkholz</mail>
11	</author>
12	<author title="Editor">
13	<mail link="peesh@gentoo.org">Jorge Paulo</mail>
14	</author>
15	<author title="Editor">
16	<mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
17	</author>
18
19	<abstract>
20	This document is a guide to getting 3D acceleration working using the DRM with
21	Xorg in Gentoo Linux.
22	</abstract>
23
24	<!-- The content of this document is licensed under the CC-BY-SA license -->
25	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
26	<license/>
27
28	<version>1.10</version>
29	<date>2007-08-23</date>
30
31	<chapter>
32	<title>Introduction</title>
33	<section>
34	<title>What is hardware 3D acceleration and why do I want it?</title>
35	<body>
36
37	<p>
38	With hardware 3D acceleration, three-dimensional rendering uses the graphics
39	processor on your video card instead of taking up valuable CPU resources
40	drawing 3D images. It's also referred to as "hardware acceleration" instead of
41	"software acceleration" because without this 3D acceleration your CPU is forced
42	to draw everything itself using the Mesa software rendering libraries, which
43	takes up quite a bit of processing power. While Xorg typically supports 2D
44	hardware acceleration, it often lacks hardware 3D acceleration.
45	Three-dimensional hardware acceleration is valuable in situations requiring
46	rendering of 3D objects such as games, 3D CAD and modeling.
47	</p>
48
49	</body>
50	</section>
51	<section>
52	<title>How do I get hardware 3D acceleration?</title>
53	<body>
54
55	<p>
56	In many cases, both binary and open-source drivers exist. Open-source drivers
57	are preferable since we're using Linux and open source is one of its underlying
58	principles. Sometimes, binary drivers are the only option, like with nVidia's
59	cards. Binary drivers include <c>x11-drivers/nvidia-drivers</c> for nVidia cards
60	and <c>x11-drivers/ati-drivers</c> for ATI cards.
61	</p>
62
63	</body>
64	</section>
65	<section>
66	<title>What is DRI?</title>
67	<body>
68
69	<p>
70	The <uri link="http://dri.freedesktop.org/wiki/">Direct Rendering
71	Infrastructure</uri>, also known as the DRI, is a framework for allowing direct
72	access to graphics hardware in a safe and efficient manner. It includes changes
73	to the X server, to several client libraries and to the kernel. The first major
74	use for the DRI is to create fast OpenGL implementations.
75	</p>
76
77	</body>
78	</section>
79	<section>
80	<title>What is the DRM and how does it relate to regular Xorg?</title>
81	<body>
82
83	<p>
84	The DRM (Direct Rendering Manager) is an <e>enhancement</e> to Xorg that adds 3D
85	acceleration for cards by adding the kernel module necessary for direct
86	rendering.
87	</p>
88
89	</body>
90	</section>
91	<section>
92	<title>Purpose</title>
93	<body>
94
95	<p>
96	This guide is for people who can't get direct rendering working with just Xorg.
97	The DRM works for the following drivers:
98	</p>
99
100	<ul>
101	<li>3dfx</li>
102	<li>i8x0</li>
103	<li>matrox</li>
104	<li>rage128</li>
105	<li>radeon</li>
106	<li>mach64</li>
107	<li>sis300</li>
108	<li>via</li>
109	</ul>
110
111	<p>
112	See the <uri link="http://dri.freedesktop.org/">DRI homepage</uri> for more info
113	and documentation.
114	</p>
115
116	</body>
117	</section>
118	<section>
119	<title>Feedback</title>
120	<body>
121
122	<p>
123	With suggestions, questions, etc., e-mail <mail
124	link="dberkholz@gentoo.org">Donnie Berkholz</mail>.
125	</p>
126
127	</body>
128	</section>
129	</chapter>
130
131	<chapter>
132	<title>Install Xorg and configure your kernel</title>
133	<section>
134	<title>Install Xorg</title>
135	<body>
136
137	<p>
138	Please read our <uri link="/doc/en/xorg-config.xml">Xorg Configuration
139	Guide</uri> to get Xorg up and running.
140	</p>
141
142	</body>
143	</section>
144	<section>
145	<title>Configure your kernel</title>
146	<body>
147
148	<p>
149	Probe for your chipset and enable just that one.
150	</p>
151
152	<pre caption="Checking your AGP chipset">
153	# <i>emerge pciutils; lspci \| grep AGP</i>
154	# <i>00:01.0 PCI bridge: Intel Corp. 440BX/ZX/DX - 82443BX/ZX/DX AGP bridge (rev 03)</i>
155	<comment>(Your output may not match the above due to different hardware.)</comment>
156	</pre>
157
158	<p>
159	If your chipset is not supported by the kernel you might have some succes by
160	passing <c>agp=try_unsupported</c> as a kernel parameter. This will use Intel's
161	generic routines for AGP support. To add this parameter, edit your bootloader
162	configuration file!
163	</p>
164
165	<p>
166	Most, if not all, kernels should have these options. This was configured using a
167	standard <c>gentoo-sources</c> kernel.
168	</p>
169
170	<pre caption="Configuring the kernel">
171	# <i>ls -l /usr/src/linux </i>
172	lrwxrwxrwx 1 root root 22 2007-02-14 20:12 /usr/src/linux -> linux-2.6.18-gentoo-r4
173	<comment>(Make sure /usr/src/linux links to your current kernel.)</comment>
174	# <i>cd /usr/src/linux</i>
175	# <i>make menuconfig</i>
176	</pre>
177
178	<pre caption="make menuconfig options">
179	Processor type and features --->
180	<*> MTRR (Memory Type Range Register) support
181	Device drivers --->
182	Character devices --->
183	<M> /dev/agpgart (AGP Support)
184	<comment>(The agpgart option is not present on 64-bit kernels; just choose your chipset support.)</comment>
185	<M> Intel 440LX/BX/GX, I8xx and E7x05 support
186	<comment>(Enable your chipset instead of the above.)</comment>
187	<M> Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)
188	</pre>
189
190	</body>
191	</section>
192	<section>
193	<title>Compile and install your kernel</title>
194	<body>
195
196	<pre caption="Compiling and installing kernel">
197	# <i>make && make modules_install</i>
198	</pre>
199
200	<p>
201	Don't forget to set up <path>grub.conf</path> or <path>lilo.conf</path> and run
202	<c>/sbin/lilo</c> if you use LILO.
203	</p>
204
205	</body>
206	</section>
207	</chapter>
208
209	<chapter>
210	<title>Configure direct rendering</title>
211	<section id="configure_xorg">
212	<title>Configure Xorg.conf</title>
213	<body>
214
215	<p>
216	Open <path>/etc/X11/xorg.conf</path> with your favorite text editor and edit
217	it to enable DRI and GLX.
218	</p>
219
220	<pre caption="xorg.conf">
221	...
222	Section "Module"
223	Load "dri"
224	Load "glx"
225	...
226	EndSection
227	...
228	Section "Device"
229	Driver "radeon"
230	<comment>(Replace radeon with the name of your driver.)</comment>
231	...
232	EndSection
233	...
234	Section "dri"
235	Mode 0666
236	EndSection
237	</pre>
238
239	</body>
240	</section>
241	<section>
242	<title>Changes to modules.autoload.d</title>
243	<body>
244
245	<p>
246	You will need to add the module name that your card uses to
247	<path>/etc/modules.autoload.d/kernel-2.6</path> to ensure that the module is
248	loaded automatically when the system starts up.
249	</p>
250
251	<pre caption="Editing /etc/modules.autoload.d/kernel-2.6">
252	<comment>(Change module name as required.)</comment>
253	intel-agp
254	</pre>
255
256	<note>
257	If you compiled <c>agpgart</c> as a module, you will also need to add it to
258	<path>/etc/modules.autoload.d/kernel-2.6</path>.
259	</note>
260
261	</body>
262	</section>
263	</chapter>
264
265	<chapter>
266	<title>Test 3D acceleration</title>
267	<section>
268	<title>Reboot to the new kernel</title>
269	<body>
270
271	<p>
272	Reboot your computer to your new kernel and login as a normal user. It's time to
273	see if you have direct rendering and how good it is. <c>glxinfo</c> and
274	<c>glxgears</c> are part of the <c>mesa-progs</c> package, so make sure it is
275	installed before you attempt to run these commands.
276	</p>
277
278	<pre caption="Testing rendering">
279	$ <i>startx</i>
280	<comment>(No need to load modules for your driver or agpgart, even if you compiled them as a module.)</comment>
281	<comment>(They will be loaded automatically.)</comment>
282	$ <i>glxinfo \| grep rendering</i>
283	direct rendering: Yes
284	<comment>(If it says "No", you don't have 3D acceleration.)</comment>
285	$ <i>glxgears</i>
286	<comment>(Test your frames per second (FPS) at the default size. The number should be
287	significantly higher than before configuring DRM. Do this while the CPU is as idle as
288	possible.)</comment>
289	</pre>
290
291	<note>
292	FPS may be limited by your screen's refresh rate, so keep this in mind if
293	<c>glxgears</c> reports only about 70-100 FPS. <c>games-fps/ut2004-demo</c> is a
294	better benchmarking tool, as it can give you real-world performance results.
295	</note>
296
297	</body>
298	</section>
299	</chapter>
300
301	<chapter>
302	<title>Tweak your performance</title>
303	<section>
304	<title>Get the most out of direct rendering</title>
305	<body>
306
307	<p>
308	A few options may increase performance by up to 30 percent (or more) over the
309	default. Set them in <path>/etc/X11/xorg.conf</path>. However, you will first
310	need to check that your motherboard and video card support these options.
311	</p>
312
313	<p>
314	First, let's see if your video card can support fast writes. We'll do this by
315	closely inspecting the output from <c>lspci</c>. Specifically, we are looking
316	at the "VGA compatible controller" information.
317	</p>
318
319	<pre caption="Video card check">
320	# <i>lspci -vv</i>
321	01:00.0 VGA compatible controller: ATI Technologies Inc Radeon Mobility M6 LY (prog-if 00 [VGA])
322	. . .
323	Capabilities: [58] AGP version 2.0
324	Status: RQ=48 Iso- ArqSz=0 Cal=0 SBA+ ITACoh- GART64- HTrans- 64bit- FW+ AGP3- Rate=x1,x2,x4
325	</pre>
326
327	<p>
328	While quite a lot of information is produced, we are looking for <b>FW</b> in
329	the "Status" subsection of the AGP "Capabilities" section. If <b>FW+</b> is
330	present in the "Status" line, it means the card supports fast writes. We can
331	now check if the motherboard supports fast writes.
332	</p>
333
334	<impo>
335	If you do not see <b>FW+</b>, but instead see <b>FW-</b>, you cannot enable
336	fast writes in <path>xorg.conf</path>. Your card does not support fast writes.
337	</impo>
338
339	<p>
340	Now let's make sure the motherboard supports fast writes as well. This time,
341	look at the "Host bridge" section of your <c>lspci</c> output.
342	</p>
343
344	<pre caption="Motherboard check">
345	# <i>lspci -vv</i>
346	00:00.0 Host bridge: Intel Corporation 82830 830 Chipset Host Bridge (rev 02)
347	. . .
348	Capabilities: [a0] AGP version 2.0
349	Status: RQ=32 Iso- ArqSz=0 Cal=0 SBA+ ITACoh- GART64- HTrans- 64bit- FW+ AGP3- Rate=x1,x2,x4
350	</pre>
351
352	<p>
353	Again, examine the "Status" subsection of your AGP "Capabilities" section. Look
354	for <b>FW</b>. If you see <b>FW+</b>, your motherboard supports fast writes.
355	</p>
356
357	<impo>
358	Remember, both your video card information and your motherboard information
359	must show the same <b>FW</b> capability. If either device shows <b>FW-</b> in
360	"Status", you cannot enable fast writes in <path>xorg.conf</path>.
361	</impo>
362
363	<p>
364	Assuming that all has gone well and both your motherboard and video card
365	support fast writes, let's enable this option in
366	<path>/etc/X11/xorg.conf</path> and get the best performance out of your
367	hardware.
368	</p>
369
370	<pre caption="xorg.conf">
371	Section "Device"
372	Option "AGPMode" "4"
373	<comment>(This increased FPS from 609 to 618.)</comment>
374	Option "AGPFastWrite" "True"
375	<comment>(This had no measurable effect, but it may increase instability of your computer.)</comment>
376	<comment>(You may also need to set it in your BIOS.)</comment>
377	Option "EnablePageFlip" "True"
378	<comment>(This improved FPS from 618 to 702. It also is "risky" but few people have reported problems.)</comment>
379	...
380	EndSection
381	</pre>
382
383	<warn>
384	Enabling <c>AGPFastWrite</c> on a VIA chipset will very likely cause your
385	machine to lock up. VIA chipsets do not play nicely with fast writes, so use
386	this setting at your own risk.
387	</warn>
388
389	<note>
390	Remember, if you want fast writes to work properly, you will have to first
391	enable the appropriate option in your BIOS.
392	</note>
393
394	<p>
395	If you want to set even more features, check out the <uri
396	link="http://dri.freedesktop.org/wiki/FeatureMatrix">feature matrix</uri> on
397	the DRI web site or the <uri
398	link="http://dri.sourceforge.net/doc/dri_driver_features.phtml">features
399	listing</uri> on Sourceforge.
400	</p>
401
402	</body>
403	</section>
404	</chapter>
405
406	<chapter>
407	<title>Troubleshooting</title>
408	<section>
409	<title>It doesn't work. I don't have rendering, and I can't tell why.</title>
410	<body>
411
412	<p>
413	Try <c>modprobe radeon</c> before you start the X server (replace <c>radeon</c>
414	with the name of your driver). Also, try building agpgart into the kernel
415	instead of as a module.
416	</p>
417
418	</body>
419	</section>
420	<section>
421	<title>When I startx, I get this error: "[drm] failed to load kernel module agpgart"</title>
422	<body>
423
424	<p>
425	That's because you compiled agpgart into the kernel instead of as a module.
426	Ignore it unless you're having problems.
427	</p>
428
429	</body>
430	</section>
431	<section>
432	<title>I have a Radeon, and I want TV-Out.</title>
433	<body>
434
435	<p>
436	The drivers originally developed by the <uri
437	link="http://gatos.sf.net">GATOS</uri> project have been merged into Xorg's
438	codebase. You don't need anything special for TV-Out;
439	<c>x11-drivers/xf86-video-ati</c> will work just fine.
440	</p>
441
442	</body>
443	</section>
444	<section>
445	<title>
446	It doesn't work. My card is so incredibly new and cool that it isn't supported
447	at all.
448	</title>
449	<body>
450
451	<p>
452	Try out the binary drivers. For <c>ati-drivers</c>, a listing is at
453	<uri>http://ati.amd.com/support/drivers/linux/linux-radeon.html</uri> (for x86)
454	and at <uri>http://ati.amd.com/support/drivers/linux64/linux64-radeon.html</uri>
455	(for amd64). If those don't support it, use fbdev. It's slow, but it works.
456	</p>
457
458	</body>
459	</section>
460	<section>
461	<title>I have a PCI card and it doesn't work. Help!</title>
462	<body>
463
464	<p>
465	Edit <path>/etc/X11/xorg.conf</path>. In section "Device" enable ForcePCIMode.
466	</p>
467
468	<pre caption="Enabling ForcePCIMode">
469	Option "ForcePCIMode" "True"
470	</pre>
471
472	</body>
473	</section>
474	</chapter>
475
476	<chapter>
477	<title>Acknowledgments</title>
478	<section>
479	<body>
480
481	<ol>
482	<li>
483	Christopher Webber for suggesting a troubleshooting question about changing
484	or recompiling kernels
485	</li>
486	<li>
487	Steve, for suggesting consistency between the cases of dri and DRI in
488	XF86Config
489	</li>
490	</ol>
491
492	</body>
493	</section>
494	</chapter>
495
496	<chapter>
497	<title>References</title>
498	<section>
499	<body>
500
501	<ol>
502	<li><uri>http://forums.gentoo.org/viewtopic.php?t=46681</uri></li>
503	<li><uri>http://forums.gentoo.org/viewtopic.php?t=29264</uri></li>
504	<li><uri>http://dri.freedesktop.org/</uri></li>
505	<li><uri>http://www.retinalburn.net/linux/dri_status.html</uri></li>
506	</ol>
507
508	</body>
509	</section>
510	</chapter>
511	</guide>