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

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

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

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 genkernel to configure the kernel for you then you're all set. If not, double check your kernel configuration so that this support is enabled:

Loadable module support --->
  [*] Enable loadable module support

You also need to enable Memory Type Range Register in your kernel:

Processor and Features --->
  [*] MTRR (Memory Type Range Register) support

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

The nvidia-kernel ebuild auto discovers your kernel version based on the /usr/src/linux 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 Installation Handbook for details on configuring your kernel.

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

# cd /usr/src
# ls -l
(Check that linux points to the right directory)
lrwxrwxrwx   1 root root   22 Apr 23 18:33 linux -> 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

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

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

# cd /usr/src
# ln -snf linux-2.6.11-gentoo-r6 linux

The following is a list of unsupported legacy video 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

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

# echo ">media-video/nvidia-kernel-1.0.6629-r4" >> /etc/portage/package.mask
# echo ">media-video/nvidia-glx-1.0.6629-r7" >> /etc/portage/package.mask

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

# emerge nvidia-glx

Once the installation has finished, run modprobe nvidia to load the kernel module into memory.

# modprobe nvidia

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 /etc/modules.autoload.d/kernel-2.6 (or kernel-2.4, depending on which kernel version you use) and add nvidia to it. Don't forget to run modules-update afterwards.

# modules-update

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

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

Section "Device"
  Identifier "nVidia Inc. GeForce2"
  Driver     "nvidia"
  VideoRam   65536
EndSection

Then go to the Module section and make sure the glx module gets loaded while the dri module doesn't:

Section "Module"
  (...)
  # Load  "dri"
  Load  "glx"
  (...)
EndSection

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

Section "Screen"
  (...)
  DefaultDepth 16
  Subsection "Display"
  (...)
EndSection

Run opengl-update so that the X Server uses the nVidia GLX libraries:

# opengl-update nvidia

You have to add your user to the video group so he has access to the nvidia device files:

# gpasswd -a youruser video

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

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

$ glxinfo | grep direct
direct rendering: Yes

To monitor your FPS, run glxgears.

Some tools, such as mplayer and xine-lib, 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 /etc/make.conf or add it as USE flag to media-video/mplayer and/or media-libs/xine-lib in /etc/portage/package.use.

Then, run emerge -uD --newuse world to rebuild the applications that benefit from the USE flag change.

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 media-video/nvidia-settings.

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 /proc/mtrr:

# cat /proc/mtrr

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.

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.

nvidia-kernel 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 nvidia-kernel package. You can find this option in the section Kernel Hacking.

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 lspci).

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

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

# less /usr/share/doc/nvidia-glx-*/README.txt.gz

The nvidia 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 /etc/modules.d/nvidia. Remember to run modules-update after modifying this file, and bear in mind that you will need to reload the nvidia module before the new settings take effect.

(Edit /etc/modules.d/nvidia in your favourite editor)
# nano -w /etc/modules.d/nvidia
(Update module information)
# modules-update
(Unload the nvidia module...)
# modprobe -r nvidia
(...and load it once again)
# modprobe nvidia

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.

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 /etc/X11/xorg.conf). For example, suppose I wanted to disable the splash logo:

Section "Device"
  Identifier "nVidia Inc. GeForce2"
  Driver     "nvidia"
  Option     "NoLogo" "true"
  VideoRam   65536
EndSection