doc/en/nvidia-guide.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/nvidia-guide.xml,v 1.24 2006/02/17 19:01:06 nightmorph Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/doc/en/nvidia-guide.xml">
<title>Gentoo Linux nVidia Guide</title>

<author title="Author">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>
<author title="Editor">
  <mail link="curtis119@gentoo.org">M Curtis Napier</mail>
</author>
<author title="Editor">
  <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
</author>

<abstract>
Many Gentooists have an nVidia chipset on their system. nVidia provides specific
Linux drivers to boost the performance of your card. This guide informs you how
to install and configure these drivers.
</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.21</version>
<date>2006-03-04</date>

<chapter>
<title>Introduction</title>
<section>
<body>

<p>
nVidia release their own Linux drivers which provide good performance and full
3D acceleration. The driver releases are split up into two parts:
<c>nvidia-kernel</c> and <c>nvidia-glx</c>.
</p>

<p>
<c>nvidia-kernel</c> is a kernel driver which handles the low-level
communication with your video hardware. This is simply a kernel module, named
<c>nvidia</c>, which installs against your kernel sources and needs to be loaded
whenever you want to use the nvidia drivers.
</p>

<p>
As well as the kernel driver, you need to install the X11 GLX layer
(<c>nvidia-glx</c>). This is used by X to render graphics, which internally
uses the <c>nvidia-kernel</c> kernel driver to interface with the hardware.
</p>

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

<chapter>
<title>Configuring your Card</title>
<section>
<title>Kernel Configuration</title>
<body>

<p>
As mentioned above, the nVidia kernel driver installs and runs against your
current kernel. It builds as a module, so it makes sense that your kernel must
support the loading of kernel modules. If you used <c>genkernel</c> to configure
the kernel for you then you're all set. If not, double check your kernel
configuration so that this support is enabled:
</p>

<pre caption="Enabling the Loading of Kernel Modules">
Loadable module support ---&gt;
  [*] Enable loadable module support
</pre>

<p>
You also need to enable <e>Memory Type Range Register</e> in your kernel:
</p>

<pre caption="Enabling MTRR">
Processor and Features ---&gt;
  [*] MTRR (Memory Type Range Register) support
</pre>

</body>
</section>
<section>
<title>Arch-specific notes</title>
<body>

<impo>
For x86 and AMD64 processors, the in-kernel driver conflicts with the binary
driver provided by nVidia. If you will be compiling your kernel for these CPUs,
you must completely remove support for the in-kernel driver as shown:
</impo>

<pre caption="Remove the in-kernel driver">
Device Drivers ---&gt;
Graphics Support ---&gt;
&lt; &gt;   nVidia Framebuffer Support
&lt; &gt;   nVidia Riva support
</pre>

<p>
A good framebuffer alternative is <c>VESA</c>:
</p>

<pre caption="Enable VESA support">
Device Drivers ---&gt; 
Graphics Support ---&gt;
&lt;*&gt;   VESA VGA graphics support
</pre>

<p>
Then, under "VESA driver type" select either <c>vesafb</c> or
<c>vesafb-tng</c>:
</p>

<pre caption="Select framebuffer type">
( ) vesafb
(X) vesafb-tng
</pre>

<p>
For more information, you can read up
<path>/usr/src/linux/Documentation/fb/vesafb.txt</path> if you are using
<c>vesafb</c> or look for your framebuffer documentation under
<path>/usr/src/linux/Documentation/fb/</path>.
</p>

</body>
</section>
<section>
<title>Continuing with Kernel Configuration</title>
<body>

<p>
nVidia's modules and libraries are combined in two packages: <c>nvidia-glx</c>
and <c>nvidia-kernel</c>. The former are the X11 GLX libraries while the latter
are the kernel modules.
</p>

<p>
The nvidia-kernel ebuild auto discovers your kernel version based on the
<path>/usr/src/linux</path> symlink. Please ensure that you have this symlink
pointing to the correct sources and that your kernel is correctly configured.
Please refer to the Configuring the Kernel section of the <uri
link="/doc/en/handbook/">Installation Handbook</uri> for details on configuring
your kernel.
</p>

<p>
If you are using gentoo-sources-2.6.11-r6, your <path>/usr/src</path> directory
might look something like this:
</p>

<pre caption="Check your /usr/src/linux symlink">
# <i>cd /usr/src</i>
# <i>ls -l</i>
<comment>(Check that linux points to the right directory)</comment>
lrwxrwxrwx   1 root root   22 Apr 23 18:33 linux -&gt; linux-2.6.11-gentoo-r6
drwxr-xr-x   4 root root  120 Apr  8 18:56 linux-2.4.26-gentoo-r4
drwxr-xr-x  18 root root  664 Dec 31 16:09 linux-2.6.10
drwxr-xr-x  18 root root  632 Mar  3 12:27 linux-2.6.11
drwxr-xr-x  19 root root 4096 Mar 16 22:00 linux-2.6.11-gentoo-r6
</pre>

<p>
In the above output, you'll notice that the <c>linux</c> symlink is pointing
to the <c>linux-2.6.11-gentoo-r6</c> kernel.
</p>

<p>
If the symlink is not pointing to the correct sources, you must update the link
like this:
</p>

<pre caption="Create/Update /usr/src/linux symlink">
# <i>cd /usr/src</i>
# <i>ln -snf linux-2.6.11-gentoo-r6 linux</i>
</pre>

</body>
</section>
<section>
<title>Optional: Check for Legacy Card Support</title>
<body>

<note>
Unfortunately, certain legacy video cards are not supported by the newer
versions of <c>nvidia-glx</c> and <c>nvidia-kernel</c>. nVidia provides a <uri
link="http://www.nvidia.com/object/IO_18897.html">list of supported cards</uri>.
Please check the list before installing the drivers.
</note>

<p>
The following is a list of <b>unsupported</b> legacy video cards:
</p>

<pre caption="Unsupported cards">
TNT2
TNT2 Pro
TNT2 Ultra
TNT2 Model 64 (M64)
TNT2 Model 64 (M64) Pro
Vanta
Vanta LT
GeForce 256
GeForce DDR
GeForce2 GTS
GeForce2 Pro
GeForce2 Ti
GeForce2 Ultra
GeForce2 MX Integrated graphics
Quadro
Quadro2 Pro
Quadro2 EX
</pre>

<p>
If you own one of these cards, you will have to mask the newer versions of the
nVidia drivers, and install an older version:
</p>

<pre caption="Masking newer drivers">
# <i>echo "&gt;media-video/nvidia-kernel-1.0.6629-r4" &gt;&gt; /etc/portage/package.mask</i>
# <i>echo "&gt;media-video/nvidia-glx-1.0.6629-r7" &gt;&gt; /etc/portage/package.mask</i>
</pre>

</body>
</section>
<section>
<title>Installing the Appropriate Drivers</title>
<body>

<p>
Now it's time to install <c>nvidia-kernel</c> and <c>nvidia-glx</c>. Since
<c>nvidia-glx</c> depends on <c>nvidia-kernel</c>, installing <c>nvidia-glx</c>
is sufficient.
</p>

<pre caption="Installing the nVidia modules">
# <i>emerge nvidia-glx</i>
</pre>

<impo>
Every time you <uri link="/doc/en/kernel-upgrade.xml">compile a new
kernel</uri> or recompile the current one, you have to run <c>emerge
nvidia-kernel</c> to reinstall the nVidia modules. <c>nvidia-glx</c> is
unaffected by a kernel change and doesn't even need to be rebuilt when you
recompile/upgrade X.
</impo>

<p>
Once the installation has finished, run <c>modprobe nvidia</c> to load the
kernel module into memory.
</p>

<pre caption="Loading the kernel module">
# <i>modprobe nvidia</i>
</pre>

<p>
To prevent you having to manually load the module on every bootup, you probably
want to have this done automatically each time you boot your system, so edit
<path>/etc/modules.autoload.d/kernel-2.6</path> (or <path>kernel-2.4</path>,
depending on which kernel version you use) and add <c>nvidia</c> to it. Don't
forget to run <c>modules-update</c> afterwards.
</p>

<pre caption="Running modules-update">
# <i>modules-update</i>
</pre>

</body>
</section>
<section>
<title>Configuring the X Server</title>
<body>

<p>
Once the appropriate drivers are installed you need to configure your X Server
(XFree86 or Xorg) to use the <c>nvidia</c> driver instead of the default
<c>nv</c> driver.
</p>

<p>
Open <path>/etc/X11/xorg.conf</path> (or <path>/etc/X11/XF86Config</path> if you
still use the older configuration file location) with your favorite editor
(such as <c>nano</c> or <c>vim</c>) and go to the <c>Device</c> section. In that
section, change the <c>Driver</c> line:
</p>

<pre caption="Changing nv to nvidia in the X Server configuration">
Section "Device"
  Identifier "nVidia Inc. GeForce2"
  <i>Driver     "nvidia"</i>
  VideoRam   65536
EndSection
</pre>

<p>
Then go to the <c>Module</c> section and make sure the <c>glx</c> module gets
loaded while the <c>dri</c> module doesn't:
</p>

<pre caption="Updating the Module section">
Section "Module"
  <comment>(...)</comment>
  <i># Load  "dri"
  Load  "glx"</i>
  <comment>(...)</comment>
EndSection
</pre>

<p>
Next, in section <c>Screen</c>, make sure that either the <c>DefaultDepth</c>
directive is set to 16 or 24, or that you only have <c>Display</c> subsections
with <c>Depth</c> settings of 16 or 24. Without it, the nvidia-glx extensions
will not start.
</p>

<pre caption="Updating the Screen section">
Section "Screen"
  <comment>(...)</comment>
  <i>DefaultDepth 16</i>
  Subsection "Display"
  <comment>(...)</comment>
EndSection
</pre>

<p>
Run <c>opengl-update</c> so that the X Server uses the nVidia GLX libraries:
</p>

<pre caption="Running opengl-update">
# <i>opengl-update nvidia</i>
</pre>

</body>
</section>
<section>
<title>Adding your Users to the video Group</title>
<body>

<p>
You have to add your user to the <c>video</c> group so he has access to the
nvidia device files:
</p>

<pre caption="Adding your user to the video group">
# <i>gpasswd -a youruser video</i>
</pre>

<p>
This might not be totally necessary if you aren't using <c>udev</c> but it
doesn't hurt either and makes your system future-proof :)
</p>

</body>
</section>
<section>
<title>Testing your Card</title>
<body>

<p>
To test your nVidia card, fire up X and run the <c>glxinfo | grep direct</c>
command. It should say that direct rendering is activated:
</p>

<pre caption="Checking the direct rendering status">
$ <i>glxinfo | grep direct</i>
direct rendering: Yes
</pre>

<p>
To monitor your FPS, run <c>glxgears</c>.
</p>

</body>
</section>
<section>
<title>Enabling nvidia Support</title>
<body>

<p>
Some tools, such as <c>mplayer</c> and <c>xine-lib</c>, use a local USE flag
called "nvidia" which enables XvMCNVIDIA support, useful when watching high
resolution movies. Add in "nvidia" in your USE variable in
<path>/etc/make.conf</path> or add it as USE flag to <c>media-video/mplayer</c>
and/or <c>media-libs/xine-lib</c> in <path>/etc/portage/package.use</path>.
</p>

<p>
Then, run <c>emerge -uD --newuse world</c> to rebuild the applications that
benefit from the USE flag change.
</p>

</body>
</section>
<section>
<title>Using NVidia Settings Tool</title>
<body>

<p>
Since NVidia released version 1.0.6106 it also provides you with a settings
tool. This tool allows you to change graphical settings without restarting the X
server and is available through Portage as <c>media-video/nvidia-settings</c>.
</p>

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

<chapter>
<title>Troubleshooting</title>
<section>
<title>Getting 2D to work on machines with 4Gb or more memory</title>
<body>

<p>
If you are having troubles with the nVidia 2D acceleration it is likely that you
are unable to set up a write-combining range with MTRR. To verify, check the
contents of <path>/proc/mtrr</path>:
</p>

<pre caption="Checking if you have write-combining enabled">
# <i>cat /proc/mtrr</i>
</pre>

<p>
Every line should contain "write-back" or "write-combining". If you see a line
with "uncachable" in it you will need to change a BIOS setting to fix this.
</p>

<p>
Reboot and enter the BIOS, then find the MTRR settings (probably under "CPU
Settings"). Change the setting from "continuous" to "discrete" and boot back
into Linux. You will now find out that there is no "uncachable" entry anymore
and 2D acceleration now works without any glitches.
</p>

</body>
</section>
<section>
<title>I receive warnings about unsupported 4K stack sizes</title>
<body>

<p>
<c>nvidia-kernel</c> packages older than 1.0.6106 only support kernels using an
8K stack size. More recent kernels (2.6.6 and higher) have support for 4K stack
size's as well. Do not select 4K stack size in your kernel configuration if you
are using such an <c>nvidia-kernel</c> package. You can find this option in the
section <c>Kernel Hacking</c>.
</p>

</body>
</section>
<section>
<title>
  When I attempt to load the kernel module I receive a "no such device"
</title>
<body>

<p>
This usually occurs when you don't have a matching video card. Make sure that
you have an nVidia-powered graphical card (you can double-check this using
<c>lspci</c>).
</p>

<p>
If you are confident that you have an nVidia card, check your BIOS and see if
the directive <e>Assign IRQ to VGA</e> is set.
</p>

</body>
</section>
<section>
<title>
  I get "no screens found" and the logs state "Failed to initialize the NVIDIA 
  kernel module!"
</title>
<body>

<p>
You're most likely missing the <path>/dev/nvidia*</path> device files. Create
them using <c>NVmakedevices.sh</c>:
</p>

<pre caption="Creating the nvidia device nodes">
# <i>/sbin/NVmakedevices.sh</i>
</pre>

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

<chapter>
<title>Expert Configuration</title>
<section>
<title>Documentation</title>
<body>

<p>
The nVidia driver package also comes with comprehensive documentation. This is
installed into <c>/usr/share/doc</c> and can be viewed with the following
command:
</p>

<pre caption="Viewing the NVIDIA documentation">
# <i>less /usr/share/doc/nvidia-glx-*/README.txt.gz</i>
</pre>

</body>
</section>
<section>
<title>Kernel module parameters</title>
<body>

<p>
The <c>nvidia</c> kernel module accepts a number of parameters (options) which
you can use to tweak the behaviour of the driver. Most of these are mentioned in
the documentation. To add or change the values of these parameters, edit the
file <c>/etc/modules.d/nvidia</c>. Remember to run <c>modules-update</c> after
modifying this file, and bear in mind that you will need to reload the
<c>nvidia</c> module before the new settings take effect.
</p>

<pre caption="Adjusting nvidia options">
<comment>(Edit /etc/modules.d/nvidia in your favourite editor)</comment>
# <i>nano -w /etc/modules.d/nvidia</i>
<comment>(Update module information)</comment>
# <i>modules-update</i>
<comment>(Unload the nvidia module...)</comment>
# <i>modprobe -r nvidia</i>
<comment>(...and load it once again)</comment>
# <i>modprobe nvidia</i>
</pre>

</body>
</section>
<section>
<title>Advanced X configuration</title>
<body>

<p>
The GLX layer also has a plethora of options which can be configured. These
control the configuration of TV out, dual displays, monitor frequency detection,
etc. Again, all of the available options are detailed in the documentation.
</p>

<p>
If you wish to use any of these options, you need to list them in the relevant
Device section of your X config file (usually <c>/etc/X11/xorg.conf</c>). For
example, suppose I wanted to disable the splash logo:
</p>

<pre caption="Advanced nvidia configuration in the X configuration">
Section "Device"
  Identifier "nVidia Inc. GeForce2"
  Driver     "nvidia"
  <i>Option     "NoLogo" "true"</i>
  VideoRam   65536
EndSection
</pre>

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

</guide>
1	swift	1.1	<?xml version='1.0' encoding="UTF-8"?>
2	fox2mike	1.25	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/nvidia-guide.xml,v 1.24 2006/02/17 19:01:06 nightmorph Exp $ -->
3	swift	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5			<guide link="/doc/en/nvidia-guide.xml">
6			<title>Gentoo Linux nVidia Guide</title>
7
8			<author title="Author">
9			<mail link="swift@gentoo.org">Sven Vermeulen</mail>
10			</author>
11	neysx	1.13	<author title="Editor">
12	fox2mike	1.15	<mail link="curtis119@gentoo.org">M Curtis Napier</mail>
13	neysx	1.13	</author>
14	neysx	1.21	<author title="Editor">
15	nightmorph	1.24	<mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
16	neysx	1.21	</author>
17	swift	1.1
18			<abstract>
19			Many Gentooists have an nVidia chipset on their system. nVidia provides specific
20			Linux drivers to boost the performance of your card. This guide informs you how
21			to install and configure these drivers.
22			</abstract>
23
24	fox2mike	1.15	<!-- The content of this document is licensed under the CC-BY-SA license -->
25			<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
26	swift	1.1	<license/>
27
28	fox2mike	1.25	<version>1.21</version>
29			<date>2006-03-04</date>
30	swift	1.1
31			<chapter>
32	neysx	1.14	<title>Introduction</title>
33			<section>
34			<body>
35
36			<p>
37			nVidia release their own Linux drivers which provide good performance and full
38			3D acceleration. The driver releases are split up into two parts:
39			<c>nvidia-kernel</c> and <c>nvidia-glx</c>.
40			</p>
41
42			<p>
43			<c>nvidia-kernel</c> is a kernel driver which handles the low-level
44			communication with your video hardware. This is simply a kernel module, named
45			<c>nvidia</c>, which installs against your kernel sources and needs to be loaded
46			whenever you want to use the nvidia drivers.
47			</p>
48
49			<p>
50			As well as the kernel driver, you need to install the X11 GLX layer
51			(<c>nvidia-glx</c>). This is used by X to render graphics, which internally
52			uses the <c>nvidia-kernel</c> kernel driver to interface with the hardware.
53			</p>
54
55			</body>
56			</section>
57			</chapter>
58
59			<chapter>
60	swift	1.1	<title>Configuring your Card</title>
61			<section>
62	neysx	1.21	<title>Kernel Configuration</title>
63	swift	1.1	<body>
64
65			<p>
66	neysx	1.14	As mentioned above, the nVidia kernel driver installs and runs against your
67			current kernel. It builds as a module, so it makes sense that your kernel must
68			support the loading of kernel modules. If you used <c>genkernel</c> to configure
69			the kernel for you then you're all set. If not, double check your kernel
70			configuration so that this support is enabled:
71	swift	1.1	</p>
72
73			<pre caption="Enabling the Loading of Kernel Modules">
74			Loadable module support --->
75			[*] Enable loadable module support
76			</pre>
77
78			<p>
79	swift	1.5	You also need to enable <e>Memory Type Range Register</e> in your kernel:
80			</p>
81
82			<pre caption="Enabling MTRR">
83			Processor and Features --->
84			[*] MTRR (Memory Type Range Register) support
85			</pre>
86
87	fox2mike	1.25	</body>
88			</section>
89			<section>
90			<title>Arch-specific notes</title>
91			<body>
92
93			<impo>
94			For x86 and AMD64 processors, the in-kernel driver conflicts with the binary
95			driver provided by nVidia. If you will be compiling your kernel for these CPUs,
96			you must completely remove support for the in-kernel driver as shown:
97			</impo>
98
99			<pre caption="Remove the in-kernel driver">
100			Device Drivers --->
101			Graphics Support --->
102			< > nVidia Framebuffer Support
103			< > nVidia Riva support
104			</pre>
105
106			<p>
107			A good framebuffer alternative is <c>VESA</c>:
108			</p>
109
110			<pre caption="Enable VESA support">
111			Device Drivers --->
112			Graphics Support --->
113			<*> VESA VGA graphics support
114			</pre>
115
116			<p>
117			Then, under "VESA driver type" select either <c>vesafb</c> or
118			<c>vesafb-tng</c>:
119			</p>
120
121			<pre caption="Select framebuffer type">
122			( ) vesafb
123			(X) vesafb-tng
124			</pre>
125
126			<p>
127			For more information, you can read up
128			<path>/usr/src/linux/Documentation/fb/vesafb.txt</path> if you are using
129			<c>vesafb</c> or look for your framebuffer documentation under
130			<path>/usr/src/linux/Documentation/fb/</path>.
131			</p>
132
133			</body>
134			</section>
135			<section>
136			<title>Continuing with Kernel Configuration</title>
137			<body>
138
139	swift	1.5	<p>
140	neysx	1.21	nVidia's modules and libraries are combined in two packages: <c>nvidia-glx</c>
141			and <c>nvidia-kernel</c>. The former are the X11 GLX libraries while the latter
142	neysx	1.13	are the kernel modules.
143			</p>
144
145			<p>
146			The nvidia-kernel ebuild auto discovers your kernel version based on the
147			<path>/usr/src/linux</path> symlink. Please ensure that you have this symlink
148			pointing to the correct sources and that your kernel is correctly configured.
149			Please refer to the Configuring the Kernel section of the <uri
150			link="/doc/en/handbook/">Installation Handbook</uri> for details on configuring
151			your kernel.
152			</p>
153
154			<p>
155	rane	1.18	If you are using gentoo-sources-2.6.11-r6, your <path>/usr/src</path> directory
156			might look something like this:
157	neysx	1.13	</p>
158
159			<pre caption="Check your /usr/src/linux symlink">
160			# <i>cd /usr/src</i>
161			# <i>ls -l</i>
162	neysx	1.14	<comment>(Check that linux points to the right directory)</comment>
163	neysx	1.13	lrwxrwxrwx 1 root root 22 Apr 23 18:33 linux -> linux-2.6.11-gentoo-r6
164			drwxr-xr-x 4 root root 120 Apr 8 18:56 linux-2.4.26-gentoo-r4
165			drwxr-xr-x 18 root root 664 Dec 31 16:09 linux-2.6.10
166			drwxr-xr-x 18 root root 632 Mar 3 12:27 linux-2.6.11
167			drwxr-xr-x 19 root root 4096 Mar 16 22:00 linux-2.6.11-gentoo-r6
168			</pre>
169
170			<p>
171	neysx	1.14	In the above output, you'll notice that the <c>linux</c> symlink is pointing
172			to the <c>linux-2.6.11-gentoo-r6</c> kernel.
173			</p>
174
175			<p>
176			If the symlink is not pointing to the correct sources, you must update the link
177	neysx	1.13	like this:
178			</p>
179
180	neysx	1.14	<pre caption="Create/Update /usr/src/linux symlink">
181	neysx	1.13	# <i>cd /usr/src</i>
182			# <i>ln -snf linux-2.6.11-gentoo-r6 linux</i>
183			</pre>
184
185	neysx	1.21	</body>
186			</section>
187			<section>
188			<title>Optional: Check for Legacy Card Support</title>
189			<body>
190
191			<note>
192			Unfortunately, certain legacy video cards are not supported by the newer
193			versions of <c>nvidia-glx</c> and <c>nvidia-kernel</c>. nVidia provides a <uri
194			link="http://www.nvidia.com/object/IO_18897.html">list of supported cards</uri>.
195			Please check the list before installing the drivers.
196			</note>
197
198			<p>
199			The following is a list of <b>unsupported</b> legacy video cards:
200			</p>
201
202			<pre caption="Unsupported cards">
203			TNT2
204			TNT2 Pro
205			TNT2 Ultra
206			TNT2 Model 64 (M64)
207			TNT2 Model 64 (M64) Pro
208			Vanta
209			Vanta LT
210			GeForce 256
211			GeForce DDR
212			GeForce2 GTS
213			GeForce2 Pro
214			GeForce2 Ti
215			GeForce2 Ultra
216			GeForce2 MX Integrated graphics
217			Quadro
218			Quadro2 Pro
219			Quadro2 EX
220			</pre>
221
222			<p>
223			If you own one of these cards, you will have to mask the newer versions of the
224			nVidia drivers, and install an older version:
225			</p>
226
227			<pre caption="Masking newer drivers">
228			# <i>echo ">media-video/nvidia-kernel-1.0.6629-r4" >> /etc/portage/package.mask</i>
229			# <i>echo ">media-video/nvidia-glx-1.0.6629-r7" >> /etc/portage/package.mask</i>
230			</pre>
231
232			</body>
233			</section>
234			<section>
235			<title>Installing the Appropriate Drivers</title>
236			<body>
237
238	neysx	1.13	<p>
239	neysx	1.21	Now it's time to install <c>nvidia-kernel</c> and <c>nvidia-glx</c>. Since
240			<c>nvidia-glx</c> depends on <c>nvidia-kernel</c>, installing <c>nvidia-glx</c>
241			is sufficient.
242	swift	1.1	</p>
243
244			<pre caption="Installing the nVidia modules">
245	swift	1.3	# <i>emerge nvidia-glx</i>
246	swift	1.1	</pre>
247
248	neysx	1.13	<impo>
249			Every time you <uri link="/doc/en/kernel-upgrade.xml">compile a new
250			kernel</uri> or recompile the current one, you have to run <c>emerge
251	neysx	1.21	nvidia-kernel</c> to reinstall the nVidia modules. <c>nvidia-glx</c> is
252			unaffected by a kernel change and doesn't even need to be rebuilt when you
253			recompile/upgrade X.
254	neysx	1.13	</impo>
255
256	swift	1.1	<p>
257			Once the installation has finished, run <c>modprobe nvidia</c> to load the
258			kernel module into memory.
259			</p>
260
261			<pre caption="Loading the kernel module">
262			# <i>modprobe nvidia</i>
263			</pre>
264
265			<p>
266	neysx	1.14	To prevent you having to manually load the module on every bootup, you probably
267			want to have this done automatically each time you boot your system, so edit
268			<path>/etc/modules.autoload.d/kernel-2.6</path> (or <path>kernel-2.4</path>,
269			depending on which kernel version you use) and add <c>nvidia</c> to it. Don't
270			forget to run <c>modules-update</c> afterwards.
271	swift	1.1	</p>
272
273			<pre caption="Running modules-update">
274			# <i>modules-update</i>
275			</pre>
276
277			</body>
278			</section>
279			<section>
280			<title>Configuring the X Server</title>
281			<body>
282
283			<p>
284			Once the appropriate drivers are installed you need to configure your X Server
285			(XFree86 or Xorg) to use the <c>nvidia</c> driver instead of the default
286			<c>nv</c> driver.
287			</p>
288
289			<p>
290	neysx	1.14	Open <path>/etc/X11/xorg.conf</path> (or <path>/etc/X11/XF86Config</path> if you
291			still use the older configuration file location) with your favorite editor
292			(such as <c>nano</c> or <c>vim</c>) and go to the <c>Device</c> section. In that
293			section, change the <c>Driver</c> line:
294	swift	1.1	</p>
295
296			<pre caption="Changing nv to nvidia in the X Server configuration">
297			Section "Device"
298			Identifier "nVidia Inc. GeForce2"
299			<i>Driver "nvidia"</i>
300			VideoRam 65536
301			EndSection
302			</pre>
303
304			<p>
305	swift	1.4	Then go to the <c>Module</c> section and make sure the <c>glx</c> module gets
306			loaded while the <c>dri</c> module doesn't:
307			</p>
308
309			<pre caption="Updating the Module section">
310			Section "Module"
311			<comment>(...)</comment>
312			<i># Load "dri"
313			Load "glx"</i>
314			<comment>(...)</comment>
315			EndSection
316			</pre>
317
318			<p>
319	swift	1.12	Next, in section <c>Screen</c>, make sure that either the <c>DefaultDepth</c>
320	neysx	1.21	directive is set to 16 or 24, or that you only have <c>Display</c> subsections
321			with <c>Depth</c> settings of 16 or 24. Without it, the nvidia-glx extensions
322	swift	1.12	will not start.
323			</p>
324
325			<pre caption="Updating the Screen section">
326			Section "Screen"
327			<comment>(...)</comment>
328			<i>DefaultDepth 16</i>
329			Subsection "Display"
330			<comment>(...)</comment>
331			EndSection
332			</pre>
333
334			<p>
335	swift	1.1	Run <c>opengl-update</c> so that the X Server uses the nVidia GLX libraries:
336			</p>
337
338			<pre caption="Running opengl-update">
339			# <i>opengl-update nvidia</i>
340			</pre>
341
342			</body>
343			</section>
344			<section>
345	swift	1.10	<title>Adding your Users to the video Group</title>
346			<body>
347
348			<p>
349			You have to add your user to the <c>video</c> group so he has access to the
350			nvidia device files:
351			</p>
352
353			<pre caption="Adding your user to the video group">
354			# <i>gpasswd -a youruser video</i>
355			</pre>
356
357			<p>
358	fox2mike	1.16	This might not be totally necessary if you aren't using <c>udev</c> but it
359	swift	1.10	doesn't hurt either and makes your system future-proof :)
360			</p>
361
362			</body>
363			</section>
364			<section>
365	swift	1.1	<title>Testing your Card</title>
366			<body>
367
368			<p>
369			To test your nVidia card, fire up X and run the <c>glxinfo \| grep direct</c>
370			command. It should say that direct rendering is activated:
371			</p>
372
373			<pre caption="Checking the direct rendering status">
374			$ <i>glxinfo \| grep direct</i>
375			direct rendering: Yes
376			</pre>
377
378			<p>
379	neysx	1.21	To monitor your FPS, run <c>glxgears</c>.
380	swift	1.1	</p>
381
382			</body>
383			</section>
384	swift	1.11	<section>
385			<title>Enabling nvidia Support</title>
386			<body>
387
388			<p>
389			Some tools, such as <c>mplayer</c> and <c>xine-lib</c>, use a local USE flag
390			called "nvidia" which enables XvMCNVIDIA support, useful when watching high
391			resolution movies. Add in "nvidia" in your USE variable in
392			<path>/etc/make.conf</path> or add it as USE flag to <c>media-video/mplayer</c>
393			and/or <c>media-libs/xine-lib</c> in <path>/etc/portage/package.use</path>.
394			</p>
395
396			<p>
397			Then, run <c>emerge -uD --newuse world</c> to rebuild the applications that
398			benefit from the USE flag change.
399			</p>
400
401			</body>
402			</section>
403	swift	1.19	<section>
404			<title>Using NVidia Settings Tool</title>
405			<body>
406
407			<p>
408			Since NVidia released version 1.0.6106 it also provides you with a settings
409			tool. This tool allows you to change graphical settings without restarting the X
410			server and is available through Portage as <c>media-video/nvidia-settings</c>.
411			</p>
412
413			</body>
414			</section>
415	swift	1.1	</chapter>
416	swift	1.6
417			<chapter>
418			<title>Troubleshooting</title>
419			<section>
420			<title>Getting 2D to work on machines with 4Gb or more memory</title>
421			<body>
422
423			<p>
424			If you are having troubles with the nVidia 2D acceleration it is likely that you
425			are unable to set up a write-combining range with MTRR. To verify, check the
426			contents of <path>/proc/mtrr</path>:
427			</p>
428
429			<pre caption="Checking if you have write-combining enabled">
430			# <i>cat /proc/mtrr</i>
431			</pre>
432
433			<p>
434			Every line should contain "write-back" or "write-combining". If you see a line
435			with "uncachable" in it you will need to change a BIOS setting to fix this.
436			</p>
437
438			<p>
439			Reboot and enter the BIOS, then find the MTRR settings (probably under "CPU
440			Settings"). Change the setting from "continuous" to "discrete" and boot back
441			into Linux. You will now find out that there is no "uncachable" entry anymore
442			and 2D acceleration now works without any glitches.
443			</p>
444
445			</body>
446			</section>
447	swift	1.7	<section>
448			<title>I receive warnings about unsupported 4K stack sizes</title>
449			<body>
450
451			<p>
452	neysx	1.9	<c>nvidia-kernel</c> packages older than 1.0.6106 only support kernels using an
453			8K stack size. More recent kernels (2.6.6 and higher) have support for 4K stack
454			size's as well. Do not select 4K stack size in your kernel configuration if you
455			are using such an <c>nvidia-kernel</c> package. You can find this option in the
456			section <c>Kernel Hacking</c>.
457	swift	1.7	</p>
458
459			</body>
460			</section>
461	swift	1.20	<section>
462			<title>
463			When I attempt to load the kernel module I receive a "no such device"
464			</title>
465			<body>
466
467			<p>
468			This usually occurs when you don't have a matching video card. Make sure that
469			you have an nVidia-powered graphical card (you can double-check this using
470			<c>lspci</c>).
471			</p>
472
473			<p>
474			If you are confident that you have an nVidia card, check your BIOS and see if
475			the directive <e>Assign IRQ to VGA</e> is set.
476			</p>
477
478			</body>
479			</section>
480	swift	1.22	<section>
481			<title>
482			I get "no screens found" and the logs state "Failed to initialize the NVIDIA
483			kernel module!"
484			</title>
485			<body>
486
487			<p>
488			You're most likely missing the <path>/dev/nvidia*</path> device files. Create
489			them using <c>NVmakedevices.sh</c>:
490			</p>
491
492	jkt	1.23	<pre caption="Creating the nvidia device nodes">
493	swift	1.22	# <i>/sbin/NVmakedevices.sh</i>
494			</pre>
495
496			</body>
497			</section>
498	swift	1.6	</chapter>
499
500	neysx	1.14	<chapter>
501			<title>Expert Configuration</title>
502			<section>
503			<title>Documentation</title>
504			<body>
505
506			<p>
507			The nVidia driver package also comes with comprehensive documentation. This is
508			installed into <c>/usr/share/doc</c> and can be viewed with the following
509			command:
510			</p>
511
512			<pre caption="Viewing the NVIDIA documentation">
513			# <i>less /usr/share/doc/nvidia-glx-*/README.txt.gz</i>
514			</pre>
515
516			</body>
517			</section>
518			<section>
519			<title>Kernel module parameters</title>
520			<body>
521
522			<p>
523			The <c>nvidia</c> kernel module accepts a number of parameters (options) which
524			you can use to tweak the behaviour of the driver. Most of these are mentioned in
525			the documentation. To add or change the values of these parameters, edit the
526			file <c>/etc/modules.d/nvidia</c>. Remember to run <c>modules-update</c> after
527			modifying this file, and bear in mind that you will need to reload the
528			<c>nvidia</c> module before the new settings take effect.
529			</p>
530
531	jkt	1.17	<pre caption="Adjusting nvidia options">
532			<comment>(Edit /etc/modules.d/nvidia in your favourite editor)</comment>
533			# <i>nano -w /etc/modules.d/nvidia</i>
534			<comment>(Update module information)</comment>
535			# <i>modules-update</i>
536			<comment>(Unload the nvidia module...)</comment>
537			# <i>modprobe -r nvidia</i>
538			<comment>(...and load it once again)</comment>
539			# <i>modprobe nvidia</i>
540			</pre>
541
542	neysx	1.14	</body>
543			</section>
544			<section>
545			<title>Advanced X configuration</title>
546			<body>
547
548			<p>
549			The GLX layer also has a plethora of options which can be configured. These
550			control the configuration of TV out, dual displays, monitor frequency detection,
551			etc. Again, all of the available options are detailed in the documentation.
552			</p>
553
554			<p>
555			If you wish to use any of these options, you need to list them in the relevant
556			Device section of your X config file (usually <c>/etc/X11/xorg.conf</c>). For
557			example, suppose I wanted to disable the splash logo:
558			</p>
559
560			<pre caption="Advanced nvidia configuration in the X configuration">
561			Section "Device"
562			Identifier "nVidia Inc. GeForce2"
563			Driver "nvidia"
564			<i>Option "NoLogo" "true"</i>
565			VideoRam 65536
566			EndSection
567			</pre>
568
569			</body>
570			</section>
571			</chapter>
572
573	swift	1.1	</guide>