Linux NVIDIA/XFree86 driver switching

Essential files

This section contains a list of the files that contain overlapping functionality between the XFree86 and the NVIDIA setup; there are some other files in each that contain special purpose or shared functionality, like the XFree86/Mesa3d GLUT library that is used with an NVIDIA setup too, and the runtime library for the XvMCNVIDIA extension.

It is important to note that all files listed as being in /usr/lib/ might be instead in /usr/lib/tls/.

NVIDIA essential files

Kernel AGP module(s)

/lib/modules/2.4.22/kernel/drivers/video/nvidia.o contains both the NVIDIA AGP driver and the OpenGL GLX low level implementation. It is essential.
/lib/modules/2.4.22/kernel/drivers/char/agp/agpgart.o contains the optional native LinuxAGP driver; if it is loaded, and depending on a configuration parameter, its AGP driver will be used instead of the one in nvidia.o, but the latter is still neeed as it contains the low level GLX implementation.
The /dev/nvidiactl and /dev/nvidia0 device files, and /dev/agpgart if the agpgart.o kernel module is also loaded.

OpenGL runtime libraries

/usr/lib/GL/libGL.so.1.0.4496.nv_glx is the OpenGL runtime API library.
/usr/lib/libGLcore.so.1.0.4496 contains the implementation of most of the runtime API library semantics.

X11R6 chipset and GLX driver modules

/usr/X11R6/lib/modules/drivers/nvidia_drv.o is the NVIDIA chipset driver for the XFree86 server.
/usr/X11R6/lib/modules/extensions/libglx.so.1.0.4496.nv_glx is the NVIDIA GLX extension driver for the XFree86 server.

X11R6 configuration file directives

The XF86Config directives that must be present are:

Load "glx" in the "Module" section.
Driver "nvidia" in the "Device" section.

and the Load "dri" and

Load
	      "GLcore"

directive must not be present in the "Module" section.

XFree86/Mesa3D essential files

Kernel AGP module(s)

/lib/modules/2.4.22/kernel/drivers/char/agp/agpgart.o contains the native Linux AGP driver.
The /dev/agpgart device file.

OpenGL runtime libraries

/usr/X11R6/lib/libGL.so.1.2 is the OpenGL runtime API library.

X11R6 chipset and GLX driver modules

/usr/X11R6/lib/modules/drivers/nv_drv.o is the XFree86 chipset driver for the XFree86 server.
/usr/X11R6/lib/modules/extensions/libglx.a is the XFree86/Mesa3D GLX extension driver for the XFree86 server.
/usr/X11R6/lib/modules/extensions/libGLcore.a is an extra module used and automatically loaded by libglx.a. It does not need to be listed in the modules section, and it should not be therefore listed in it as it conflicts with the NVIDIA libglx.so module.

X11R6 configuration file directives

The XF86Config directives that must be present are:

Load "glx" in the "Module" section.
Load "dri" directive should be in the "Module" section.
Driver "nv" in the "Device" section.

Switching configuration to the NVIDIA setup

Modify the XF86Config file:
- Remove from the "Module" section the Load "dri" line.
- Change the appropriate "Device" section so that the Driver line is Driver "nvidia", and add the appropriate NVIDIA driver specific options, of which probably the "NvAGP" is the most important.
Create a symbolic link from /usr/X11R6/lib/modules/extensions/libglx.so.1.0.4496.nv_glx to /usr/X11R6/lib/modules/extensions/libglx.so, for example like this:
```
# cd /usr/X11R6/lib/modules/extensions/
# rm -f libglx.so
# ln -s libglx.so.1.0.4496.nv_glx libglx.so
```
Remove the symbolic links to the XFree86 OpenGL library with rm -f /usr/lib/libGL.so*.
Create a symbolic link from /usr/lib/GL/libGL.so.1.0.4496.nv_glx to both /usr/lib/libGL.so.1.0.4496 and /usr/lib/libGL.so, for example like this:
```
# cd /usr/lib
# ln -s GL/libGL.so.1.0.4496.nv_glx libGL.so.1.0.4496
# ln -s GL/libGL.so.1.0.4496.nv_glx libGL.so
```
Rebuild the runtime loader cache to take into account the new links with ldconfig.
If one is using Option "NvAGP" with values "2" or "3" one must also load the agpgart.o kernel module first, otherwise make sure it has never been loaded.
Ensure that the nvidia.o kernel module is loaded, with something like modprobe nvidia or:
```
insmod /lib/modules/2.4.22/kernel/drivers/video/nvidia.o
```
Ensure that the /dev/nvidiactl and /dev/nvidia0 device files exist. if one is using devfsd then they will autocreated when the nvidia.o kernel module is loaded, otherwise run the script makedevices.sh that comes with the NVIDIA kernel driver package.
Ensure that the Composite extension is disabled, as it is incompatible with the GLX extension; usually the RANDR and RENDER extensions should be enabled. For example:
```
Section		"Extensions"
  Option		"RANDR"				"on"
  Option		"RENDER"			"on"
  Option		"Composite"			"off"
EndSection
```
Restart the X11 server.

Switching configuration to the XFree86/Mesa3D setup

Modify the XF86Config file:
- Add to the "Module" section the Load "dri" line.
- Change the appropriate "Device" section so that the Driver line is Driver "nv", and add the appropriate XFree86 driver specific options.
Remove the symbolic link to the NVIDIA GLX X11 server module running
```
rm -f /usr/X11R6/lib/modules/extensions/libglx.so
```
Remove the symbolic links to the NVIDIA OpenGL library with
```
rm -f /usr/lib/libGL.so*
```
Create a symbolic link from /usr/X11R6/lib/libGL.so.1.2 to both /usr/lib/libGL.so.1.2 and /usr/lib/libGL.so, for example like this:
```
# cd /usr/lib
# ln -s /usr/X11R6/lib/libGL.so.1.2 libGL.so.1.2
# ln -s /usr/X11R6/lib/libGL.so.1.2 libGL.so
```
Rebuild the dynamic loader cache to take into account the new links with ldconfig, having checked that the /usr/lib directory comes the /usr/X11R6/lib in the dynamic loader search path.
If the nvidia.o kernel module is loaded, ensure it is removed with
```
rmmod nvidia.o
```
Ensure that the agpgart.o kernel module is loaded, with something like modprobe agpgart or
```
insmod /lib/modules/2.4.22/kernel/drivers/char/agp/agpgart.o
```
Ensure that the /dev/agpgart device file exists. If one is using devfsd then it will autocreated when the nvidia.o kernel module is loaded, otherwise run /dev/MAKEDEV agpgart.
You can reenable the Composite extension, but without RENDER acceleration, which is not provided by the nv driver, it will be rather slow; usually the RANDR and RENDER extensions should be enabled. For example:
```
Section		"Extensions"
  Option		"RANDR"				"on"
  Option		"RENDER"			"on"
  Option		"Composite"			"on"
EndSection
```
Restart the X11 server.

How to check the setup is consistent and correct

Checking that the NVIDIA setup is consistent

Run glxinfo. If the lines
```
server glx vendor string: NVIDIA Corporation
```
```
client glx vendor string: NVIDIA Corporation
```
are present the NVIDIA chipset driver and the NVIDIA GLX extension for the X server are correctly installed. If the line
```
OpenGL vendor string: NVIDIA Corporation
```
is present the NVIDIA OpenGL libraries are correctly installed.
Run xdpyinfo and check that there is an extension called NV-GLX.
Run
```
ldd /usr/X11R6/bin/glxgears
```
and verify that there is a line that points to /usr/lib/libGL.so.1.
Run
```
file /usr/lib/libGL.so.1
```
and verify that it says it is a symbolic link to libGL.so.1.0.4496.
Run
```
file /usr/lib/libGL.so.1.0.4496
```
and verify that it says it is a symbolic link to GL/libGL.so.1.0.4496.nv_glx.
Run
```
file /usr/X11R6/lib/modules/extensions/libglx.so
```
and check that is a symbolic link to libglx.so.1.0.4496.nv_glx.
Ensure that there is no Load "dri" line in XF86Config.
Ensure that there is a Load "glx" line in the "Modules" section of XF86Config, and that it is a line like
```
Loading /usr/X11R6/lib/modules/extensions/libglx.so
```
in /var/log/XFree86.0.log.
Ensure that there the Driver in the active "Device" section of XF86Config says "nvidia".
Check that the nvidia.o kernel module is actually loaded and working, by running
```
lsmod
cat /proc/driver/nvidia/version
cat /proc/driver/nvidia/agp/card
```
and checking both files exist and the values printed are plausible.
Check that the device files associated with the nvidia.o kernel module exists by running
```
file /dev/nvidia*
```
Ensure that if Option "NvAGP" have value "2" or "3" the agpgart.o kernel module is loaded.

If you have used the NVIDIA installer to install the driver, modules and libraries, you can also try using nvidia-installer --sanity.

Checking that the XFree86/Mesa3D setup is consistent

Run glxinfo. If the lines
```
server glx vendor string: SGI
```
```
client glx vendor string: SGI
```
are present the XFree86 chipset driver and the XFree86 GLX extension for the X server are correctly installed. If the line
```
OpenGL vendor string: Mesa project: www.mesa3d.org
```
is present the Mesa3D OpenGL libraries are correctly installed.
Run
```
ldd /usr/X11R6/bin/glxgears
```
and verify that there is a line that points to /usr/lib/libGL.so.1.
Run
```
file /usr/lib/libGL.so.1
```
and verify that it says it is a symbolic link to libGL.so.1.2.
Run
```
file /usr/lib/libGL.so.1.2
```
and verify that it says it is a symbolic link to /usr/X11R6/lib/libGL.so.1.2.

Run

file /usr/X11R6/lib/modules/extensions/libglx.so

and verify that it does not exist.

Ensure that there is a Load "dri" line in XF86Config.
Ensure that there is a Load "glx" line in the "Modules" section of XF86Config, and that it is a line like
```
Loading /usr/X11R6/lib/modules/extensions/libglx.a
```
in /var/log/XFree86.0.log.
Ensure that there the Driver in the active "Device" section of XF86Config says "nv".
Check that the nvidia.o kernel module is not loaded by running
```
lsmod
ls -ld /proc/driver/nvidia/version
```
and checking that there is no nvidia module listed by lsmod and that there is no file called /proc/driver/nvidia/version.
Check that the device file associated with agpgart.o kernel module exists by running
```
file /dev/agpgart
```
Check that the agpgart.o kernel module is loaded by running
```
lsmod
```

Sample configurations and scripts

Sample XF86Config for NVIDIA

Section "Module"
  Load          "extmod"

  Load          "fb"
  Load          "xaa"
  Load          "dbe"
  Load          "i2c"
  Load          "ddc"

  Load          "libglx.so"
EndSection

Section "Device"
  Identifier    "Generic GeForce NVIDIA"

  Driver        "nvidia"

  Option        "NvAGP"                 "1"

  Option        "HWCursor"              "false"
  Option        "CursorShadow"          "false"

  Option        "RenderAccel"           "false"
  Option        "NoRenderExtension"     "false"
EndSection

Sample XF86Config for XFree86/Mesa3D

Section "Module"
  Load          "extmod"

  Load          "fb"
  Load          "xaa"
  Load          "dbe"
  Load          "i2c"
  Load          "ddc"

  Load          "dri"
  Load          "libglx.a"
EndSection

Section "Device"
  Identifier    "Generic GeForce XFree86"

  Driver        "nv"

  Option        "HW Cursor"             "false"
EndSection

Other interesting details

With the NVIDIA XFree86 driver, the Screen directive in the Device sections selects the CRTC.
With the NVIDIA XFree86 driver, the Option "ConnectedMonitor" selects the output socket.
With the NVIDIA XFree86 driver, the values for Option "ConnectedMonitor" can be other than CRT and DFP, for example they can be CRT-0, CRT-1, DFP-0, TV-0 or others depending on the types of sockets the card has got. Look also at the APPENDIX T: DISPLAY DEVICE NAMES in the NVIDIA README.txt.

Building the NVIDIA kernel module

When installing the NVIDIA proprietary drivers there are two steps, building and installing the nvidia.o kernel module, and installing the OpenGL libraries and X server plugin.

Building the nvidia.o kernel module is the most difficult part, because a large number of conditions must be satisfied for a successful build, some of which are dependent on the particular release of the driver package.

It is very important to read carefully the driver package README.txt in its entirety (perhaps a few times), especially the FAQ section, and the help for the extended options of the installer, before attempting a build.

Usually recetn releases of the driver combined with recent releases of the kernel source are not as reliable as less daring combinations.

Experts might find more comfortable to extract the contents of the installer and do a manual build in its subdirectory usr/src/nv/.

There must not be an X server running: The reason is that quite insanely the building ends with the activation of the module. The check whether X is running is usually based on the presence of the X display lock file, usually /tmp/.X0-lock.
The module must be built under the same kernel version it will be deployed for.: This is due to the insane default that the newly built module will be activated as soon as it is built. It is however possible to build kernel module for another kernel version by using the --kernel-name option to the installer, as documented in the FAQ section of the README.txt.
The GCC ABI version must be the same used for compiling the kernel: It is extremly important that all parts of a kernel, statically linked or dynamically activated modules, be built to the same GCC ABI. To be sure, the GCC version major and minor numbers msut be the same.
The module can only be built with fully prepped kernel sources: The module build will succeed only if the full kernel sources are available, and they are prepped for build. This means that at the very least the kernel must have been configured with make config and then make dep or whatever is equivalent for the kernel version you are using.
In particular, for Debian based systems the kernel-headers package is not sufficient.
The location of the kernel sources must be known: The build process expects the kernel sources to be pointed at by the conventional symbolic link /lib/modules/2.4.22/build and/or the location of the kernel include directory might have to be explicitly specified using the --kernel-include-path option to the installer.
The location of the module binaries directory must be known: This must either be the conventional directory /lib/modules/2.4.22 or it must be explicitly specified using the --kernel-install-path option to the installer.

It is important in case of problems to read the installer log at /var/log/nvidia-installer.log.

It may be easier to do a manual build; with the 5x.xx installers, it is in the usr/src/nv/ directory in the extracted contents of the installer.

The build may be done for a 2.4.x kernel with:

make -f Makefile.nvidia \
   SYSINCLUDE=/usr/local/src/linux-2.4.22/include \
   module

or for a 2.6.x kernel with:

make -f Makefile.kbuild \
   SYSSRC=/usr/local/src/linux-2.6.4 \
   module

Special cases

If the monitor is an LCD/DVI device, you may have to specify Option "FlatPanel" "on" with the XFree86 driver, which otherwise may default to the analog VGA connector.
If you have a laptop, you may need either a special version of the NVIDIA kernel module, or to give some options when loading it, notably the NVreg_SoftEDIDs and NVreg_Mobile options, as documented in APPENDIX K of the NVIDIA README.txt. Read carefully that appendix anyhow.
With the NVIDIA setup multihead seems more likely to work with TwinView, but there are some limitations.
Hardware cursors have issues or limitations with both the NVIDIA and the XFree86 setups.
With the NVIDIA setup the RENDER extension may be buggy; you may have to disable it, or at least disable its hardware acceleration.
If the NVIDIA packages with version numbers like 5x.xx cause problems, try to revert to the package with version 44.96.
Trying the NVIDIA setup with kernel version 2.6.x with the unofficial patches at Minion.DE may work well, but it may also be cause of trouble.
In most recent SUSE distributions there is a nice package to verify and change the state of the OpenGL setup. its description for SUSE 9.0 is here. Note in particular the 3Ddiag, switch2nvidia and switch2nv commands. There is a nice discussion in German of their use here.

Common issues

First of all read the NVIDIA README.txt. very carefully, as it is far from simple and easy to do it right, and it contains a lot of useful information.

In particular read the sections APPENDIX G: ALI SPECIFIC ISSUES, APPENDIX H: TNT SPECIFIC ISSUES, KNOWN LAPTOP ISSUES, APPENDIX N: KNOWN ISSUES, HARDWARE ISSUES, APPENDIX R: CONFIGURING MULTIPLE X SCREENS ON ONE CARD for a discussion of some issues with TwinView, and APPENDIX S: POWER MANAGEMENT SUPPORT for power management issues.

You should also consult Minion.DE's NVIDIA page for very important advice on kernel and chipset compatibility issues.

Crashes and bizarre behaviour, especially in 3D mode

Modern 3D cards can draw and dissipate 40-80 watts in 3D mode, but much less in 2D mode. This can cause power and cooling problems in 3D mode. Check carefully your power supply and motherboard AGP/PCI power ratings, and the temperatures.

GLX not enabled even if everything else seems all right

If you are using an X.org server, the COMPOSITE extension acceleration must be disabled in the NVIDIA driver configuration.

Green box in screen, or X complains about rivafb

Make really sure that the rivafb kernel module is not interfering by making sure it is not compiled, or if compiled is not loaded, or if loaded it is not not enabled.

Crashes and lockups as soon as the X server starts

Some versions of the Linux agpgart kernel driver work better with some motherboard chipsets, and some versions of the nvidia kernel driver work better with other chipset. If you are using agpgart and setting Option "NvAGP" to 2 or 3, make sure that the agpgart module is not loaded, and the option is set to 1 instead; and viceversa.

Crashes on AMD/VIA motherboards with 2.4.x kernels

Use the mem=nopentium kernel boot argument. Newer Linux kernels have a built in automagic workaround, but this argument is safe, in that at worst it causes a small loss of performance.

Crashes and lockups in 3D mode after error messages beginning with NRM: Xid

These issues are rather common, especially on x64 systems, and there appears to be no common solution. Usually such crashes are caused either by overheating or by AGP or GART issues.

Problems with recent releases of the NVIDIA drivers and/or of the kernel

Not all releases or combinations of releases of the card, driver and of the kernel work equally well, and some, especially if recent, work rather less well than others.
In particular:

Driver releases 96.26 and 96.25 have a small text rendering error that can result in visible duplication of small amounts of text.
Driver release 96.25 (a beta) locks up if the eeprom driver is compiled in or is loaded as a module.
Driver releases 76.64 and later do not support correctly (wrong colors) some GeForce3 cards.
Driver releases 76.64 do not support early chipsets, which includes the TNT, TNT2, GeForce, and GeForce2.
Driver releases 71.67 and 71.74 have a crash bug under at least Linux kernel 2.6.13 or later.
Driver releases around 7x.xx, especially on AMD64 CPUs, with kernels 2.6.1x, have some issues related to the kernel functions change_page_attr() and global_flush_tlb() (thanks to Primer for these links: 1, 2).
Driver releases up to and including releases 66.29 don't compile with Linux kernel 2.6.10 or later, which require driver versions 71.67 or later.

In general news of known issues with driver or kernel versions appear fairly soon in the NVNews.net Linux NVIDIA forums.

3D applications don't start

This may be due to GNU LIBC or the kernel not fully supporting TLS mode. Try setting

export LD_ASSUME_KERNEL
LD_ASSUME_KERNEL=2.3.98

before launching the 3D application, or fix your TLS mode libraries.

Misbehaviour with TwinView

In general having a single virtual monitor with TwinView is a hack that should be avoided. However, in the cases where it makes sense, if you enable it, make sure that Xinerama is not enabled at the same time.
The NVIDIA driver automatically enables its own Xinerama, and that conflicts with enabling Xinerama explicitly in the ServerFlags (inspired by a note in Primer's sample config).

Distribution specific notes

Debian

2. The "Debian" Way of Installing the Nvidia Drivers.
NVIDIA Display Driver Installation on Debian:
This document describes how to install the NVIDIA proprietary display drivers for e.g. the NVIDIA GeForce, Quadro and Riva TNT series graphics cards on Debian GNU/Linux by using the driver installer provided by NVIDIA.
Installing Nvidia kernel modules on a Debian machine..

Ubuntu

Fedora

Fedora FAQ notes, and in particular read this important warning.

General resources

The extraordinarily useful Icculus gaming FAQ has an excellent video section.
The Nvidia OpenGL Configuration mini-HOWTO