/[gentoo]/xml/htdocs/doc/en/dri-howto.xml
Gentoo

Contents of /xml/htdocs/doc/en/dri-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.39 - (show annotations) (download) (as text)
Sun Jul 22 07:32:28 2007 UTC (7 years, 4 months ago) by nightmorph
Branch: MAIN
Changes since 1.38: +7 -8 lines
File MIME type: application/xml
update nvidia references as nvidia-legacy-drivers is deprecated and will be removed. nvidia-drivers now contains every available version. see Cardoe's message to gentoo-dev for more information.

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

  ViewVC Help
Powered by ViewVC 1.1.20