/[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.31 - (show annotations) (download) (as text)
Fri Jul 7 07:39:55 2006 UTC (8 years, 3 months ago) by neysx
Branch: MAIN
Changes since 1.30: +3 -3 lines
File MIME type: application/xml
#139518 s/spyderous/dberkholz/

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

  ViewVC Help
Powered by ViewVC 1.1.20