/[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.33 - (show annotations) (download) (as text)
Mon Oct 9 13:41:52 2006 UTC (7 years, 9 months ago) by nightmorph
Branch: MAIN
Changes since 1.32: +11 -10 lines
File MIME type: application/xml
fixed nvidia driver name, bug 150537

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

  ViewVC Help
Powered by ViewVC 1.1.20