/[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.29 - (show annotations) (download) (as text)
Sun May 7 12:39:17 2006 UTC (8 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.28: +68 -10 lines
File MIME type: application/xml
Updated some parts of the dri-howto doc. Until I can track down an ati or non-nvidia cardholder, though, the proposed hardware check process will have to wait. Mostly, I need a monkey/volunteer to show some bits of /proc. The section is in comments in the guide now, so it can be added eventually. See bug 116506 .

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/dri-howto.xml,v 1.28 2006/02/01 11:58:34 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 <!-- 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-07</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="spyderous@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>.
447 </p>
448
449 <pre caption="xorg.conf">
450 Section "Device"
451 Option "AGPMode" "4"
452 <comment>(This increased FPS from 609 to 618.)</comment>
453 Option "AGPFastWrite" "True"
454 <comment>(This had no measurable effect, but it may increase instability of your computer.)</comment>
455 <comment>(You may also need to set it in your BIOS.)</comment>
456 Option "EnablePageFlip" "True"
457 <comment>(This improved FPS from 618 to 702. It also is "risky" but few people have reported problems.)</comment>
458 ...
459 EndSection
460 </pre>
461
462 <warn>
463 Enabling <c>AGPFastWrite</c> on a VIA chipset will very likely cause your
464 machine to lock up. VIA chipsets do not play nicely with fast writes, so use
465 this setting at your own risk.
466 </warn>
467
468 <note>
469 Remember, if you want fast writes to work properly, you will have to first
470 enable the appropriate option in your BIOS.
471 </note>
472
473 <!--
474 **
475 This section needs to be in eventually, but non-nvidia cards don't use
476 /proc/driver at all. We need some way to get users to check and see that SBA
477 and fast-writes are allowed for their hardware; that info is somewhere else in
478 /proc. If you have a non-nvidia card, you can help by emailing
479 nightmorph@gentoo.org with the relevant bits of your /proc so I can get this
480 info into the guide. See below for where things are found on an nvidia card.
481 **
482
483 <p>
484 A few options may increase performance by up to 30 percent (or more) over the
485 default. Set them in <path>/etc/X11/xorg.conf</path>. However, you will first
486 need to check that your motherboard and video card support these options.
487 </p>
488
489 <p>
490 First, let's check the supported modes of your video cards, and see if your it
491 supports fast writes. Remember to replace <c>nvidia</c> with the actual name of
492 your device in <path>/proc/driver/nvidia/</path>.
493 </p>
494
495 <pre caption="Video card check">
496 $ <i>cat /proc/driver/nvidia/agp/card</i>
497 </pre>
498
499 <p>
500 Next, let's check out the capabilities of the motherboard:
501 </p>
502
503 <pre caption="Motherboard check">
504 $ <i>cat /proc/driver/nvidia/agp/host-bridge</i>
505 </pre>
506
507 <impo>
508 Remember, the modes and capabilities for your video card and motherboard must
509 match for these settings to work!
510 </impo>
511 -->
512
513 <p>
514 If you want to set even more features, check out the <uri
515 link="http://dri.freedesktop.org/wiki/FeatureMatrix">feature matrix</uri> on
516 the DRI web site or the <uri
517 link="http://dri.sourceforge.net/doc/dri_driver_features.phtml">features
518 listing</uri> on Sourceforge.
519 </p>
520
521 </body>
522 </section>
523 </chapter>
524
525 <chapter>
526 <title>Troubleshooting</title>
527 <section>
528 <title>It doesn't work. I just recompiled my kernel or switched to a new one.</title>
529 <body>
530
531 <p>
532 Whenever you rebuild your kernel or switch to another kernel, you'll have to
533 rebuild the kernel module. Note that you don't need to remerge xorg-x11, but
534 you will need to remerge x11-drm.
535 </p>
536
537 </body>
538 </section>
539
540 <section>
541 <title>It doesn't work. I don't have rendering, and I can't tell why.</title>
542 <body>
543
544 <p>
545 Try <c>insmod radeon</c> before you start the X server. Also, try building
546 agpgart into the kernel instead of as a module.
547 </p>
548
549 </body>
550 </section>
551 <section>
552 <title>When I startx, I get this error: "[drm] failed to load kernel module agpgart"</title>
553 <body>
554
555 <p>
556 That's because you compiled agpgart into the kernel instead of as a module.
557 Ignore it unless you're having problems.
558 </p>
559
560 </body>
561 </section>
562 <section>
563 <title>Direct rendering doesn't work, and in /var/log/Xorg.0.log I have an error about driver version too low.</title>
564 <body>
565
566 <p>
567 You aren't using the x11-drm driver. Check if you compiled DRM and the driver
568 into the kernel; you shouldn't have.
569 </p>
570
571 </body>
572 </section>
573 <section>
574 <title>I have a Radeon, and I want TV-Out.</title>
575 <body>
576
577 <p>
578 Check out ati-gatos drivers. <c>emerge -s gatos</c>.
579 </p>
580
581 </body>
582 </section>
583 <section>
584 <title>It doesn't work. My card is so incredibly new and cool that it isn't supported at all.</title>
585 <body>
586
587 <p>
588 Try out the binary drivers. For ati-drivers, a listing is at
589 <uri>http://www.schneider-digital.de/html/download_ati.php</uri>. If those
590 don't support it, use fbdev. It's slow, but it works.
591 </p>
592
593 </body>
594 </section>
595 <section>
596 <title>I have a PCI card and it doesn't work. Help!</title>
597 <body>
598
599 <p>
600 In section "Device" enable ForcePCIMode.
601 </p>
602
603 <pre caption="Enabling ForcePCIMode">
604 Option "ForcePCIMode" "True"
605 </pre>
606
607 </body>
608 </section>
609 </chapter>
610
611 <chapter>
612 <title>Acknowledgments</title>
613 <section>
614 <body>
615
616 <ol>
617 <li>
618 Christopher Webber for suggesting a troubleshooting question about changing
619 or recompiling kernels
620 </li>
621 <li>
622 Steve, for suggesting consistency between the cases of dri and DRI in
623 XF86Config
624 </li>
625 </ol>
626
627 </body>
628 </section>
629 </chapter>
630
631 <chapter>
632 <title>References</title>
633 <section>
634 <body>
635
636 <ol>
637 <li><uri>http://forums.gentoo.org/viewtopic.php?t=46681</uri></li>
638 <li><uri>http://forums.gentoo.org/viewtopic.php?t=29264</uri></li>
639 <li><uri>http://dri.freedesktop.org/</uri></li>
640 <li><uri>http://www.retinalburn.net/linux/dri_status.html</uri></li>
641 </ol>
642
643 </body>
644 </section>
645 </chapter>
646 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20