NVIDIA Accelerated FreeBSD Driver Set README & Installation Guide Last Updated: $Date: 2003/06/18 $ Most Recent Driver: 1.0-4365 This README aims to provide rudimentary coverage of the steps required to install and configure the NVIDIA FreeBSD Driver Set on a -STABLE or -CURRENT computer running FreeBSD. It is complemented by the NVIDIA Linux Driver Set README, which provides information common to both operating systems. Please note that some parts of the FreeBSD Driver Set have not undergone the high level of testing the Linux Driver Set has since its release. If you are experiencing problems, please report them. __________________________________________________________________________ CONTENTS: (sec-01) SOFTWARE REQUIREMENTS (sec-02) BASIC INSTALLATION INSTRUCTIONS (sec-03) BASIC CONFIGURATION INSTRUCTIONS (sec-04) LINUX COMPATIBILITY SUPPORT (sec-05) CHOOSING THE AGP GART DRIVER (sec-06) CONFIGURING LOW-LEVEL PARAMETERS (sec-07) FREQUENTLY ASKED QUESTIONS (app-a) APPENDIX A: SUPPORTED NVIDIA GRAPHICS CHIPS (app-b) APPENDIX B: DEVELOPING MULTI-THREADED APPLICATIONS (app-c) APPENDIX C: THE SYSCTL INTERFACE (app-d) APPENDIX D: CREDITS (app-e) APPENDIX E: CONTACTING US __________________________________________________________________________ (sec-01) SOFTWARE REQUIREMENTS __________________________________________________________________________ The offical minimum software requirements for the NVIDIA FreeBSD Driver Set are: - FreeBSD -STABLE (version 4.7 or later), or FreeBSD -CURRENT (anything after the 5.0 release should be fine) - A -STABLE kernel configured with: options USER_LDT options SYSVSHM While SYSVSHM is enabled in the GENERIC FreeBSD kernel, USER_LDT is *not* included in the default -STABLE FreeBSD kernel. Please see "Chapter 9 Configuring the FreeBSD Kernel" of the FreeBSD handbook for steps on how to recompile your kernel. or A -CURRENT kernel configured with: options SYSVSHM SYSVSHM is enabled in the GENERIC FreeBSD kernel. Note that USER_LDT is not a kernel configuration option in FreeBSD -CURRENT (it is always enabled). - kernel source tree in /usr/src/sys/ - XFree86 4.2 or greater, the precise minimum packages required are: XFree86-4.2.0_1 XFree86-libraries-4.2.1_1.tgz XFree86-Server-4.2.1_3 XFree86-clients-4.2.1_1.tgz (please note that it is *not* sufficient to download 4.2.1 binaries from ftp.xfree86.org -- you must have XFree86-Server-4.2.1_3 or later). FreeBSD -STABLE versions older than 4.7 are not supported. __________________________________________________________________________ (sec-02) BASIC INSTALLATION INSTRUCTIONS __________________________________________________________________________ This installation procedure will likely be simplified further in the future, but for the moment you will need to download the NVIDIA FreeBSD Driver Set archives from the NVIDIA website, extract them to a temporary location of your choice, and run the following from the root of the extracted directory hierarchy: make setup This will compile the NVIDIA FreeBSD kernel module, install it, and kldload it. It will also remove any conflicting OpenGL libraries, and install the NVIDIA OpenGL libraries. The /dev/nvidia device files will be created, and your /boot/loader.conf file will be updated to automatically load the NVIDIA kernel module on boot, as well as the Linux ABI compatiability module should you not have it compiled into your kernel. The following list summarizes the files installed by the script and their designated locations in the file system hierarchy. - libGL.so /usr/X11R6/lib - libGL.so.1 /usr/X11R6/lib - libGLcore.so /usr/X11R6/lib - libGLcore.so.1 /usr/X11R6/lib - nvidia_drv.o /usr/X11R6/lib/modules/drivers - libglx.so /usr/X11R6/lib/modules/extensions - libglx.so.1 /usr/X11R6/lib/modules/extensions - nvidia0 /dev - nvidia1 /dev - nvidia2 /dev - nvidia3 /dev - nvidiactl /dev - libGL.so.1.0.1.0-4365 /compat/linux/usr/lib - libGLcore.so.1.0.1.0-4365 /compat/linux/usr/lib __________________________________________________________________________ (sec-03) BASIC CONFIGURATION INSTRUCTIONS __________________________________________________________________________ These configuration instructions assume that you have a basic XFree86 configuration file adapted for your system. The XFree86 configuration file has a minimum of two sections that are of particular interest: - the "Module" section - the "Device" section(s) corresponding to the NVIDIA device(s) A typical "Module" section configured for use with the NVIDIA Driver Set could look like this: Section "Module" Load "bitmap" Load "extmod" Load "dbe" Load "type1" Load "glx" Load "freetype" EndSection Important: It is the 'Load "glx"' line which instructs the X server to load the NVIDIA GLX XFree86 extension module. The "dri" and "GLcore" lines, which are often present in auto-generated configuration files, are not required, but shouldn't do any harm. A typical "Device" section configured for use with the NVIDIA Driver Set could look like this: Section "Device" Identifier "Device" Driver "nvidia" VendorName "NVIDIA" BoardName "GeForce2 Go" EndSection Important: It is the 'Driver "nvidia"' line, which instructs the X server to use the NVIDIA XFree86 driver module (nvidia_drv.o) for this device. Most configuration utilities choose the open-source "nv" driver (nv_drv.o) by default; if your XF86Config has a "Device" section with a 'Driver "nv"' line, you will need to change it to 'Driver "nvidia"'. Please see the README for the NVIDIA Linux Driver Set for a comprehensive description of available configuration options. __________________________________________________________________________ (sec-04) LINUX COMPATIBILITY SUPPORT __________________________________________________________________________ If you wish to run Linux OpenGL applications on your FreeBSD machine, you will need to make sure that several prerequisites are met. First, you should follow the basic Linux compatibility installation guide in the FreeBSD Handbook (install the linux_base package, etc). Once the basic components are in place, you will need to install the NVIDIA Linux OpenGL libraries in /compat/linux/usr/lib (do not brandelf them!); if the /compat/linux/usr/lib/ directory exists when you install the FreeBSD driver, the Linux compatibility OpenGL libraries will automatically be installed. Additionally, the nvidia.ko kernel module needs to be built with support for the Linux ABI compatibility layer. This is the case by default; as a consequence, the nvidia.ko kernel module requires the linux.ko module to be loaded. Note: If you have no need for Linux ABI compatibility and do not wish to load linux.ko, you can build the nvidia.ko kernel module without support for the Linux ABI compatibility layer (see nv-freebsd.h for details). Known Issues: the Linux OpenGL library, when run in linux compatibility mode on FreeBSD, may have difficulties determining if the application is multithreaded. As the resulting warning suggestions, it may help to set the environment variable __GL_SINGLE_THREADED (eg: `setenv __GL_SINGLE_THREADED 1`). Please see the FAQ entry "Why can the Linux compatibility libraries not correctly determine if they are used in a multithreaded application?" for details and a better solution. __________________________________________________________________________ (sec-05) CHOOSING THE AGP GART DRIVER __________________________________________________________________________ Similar to the NVIDIA Linux Driver Set, the user can decide if the NVIDIA driver should use its internal AGP GART driver or if it should rely on an OS provided AGP GART driver with the "NvAgp" XFree86 config file option: - Option "NvAgp" "0" Disable AGP - Option "NvAgp" "1" Use NVIDIA's AGP GART Driver - Option "NvAgp" "2" Use the OS AGP GART driver (agp.ko) - Option "NvAgp" "3" Attempt "2", fall back to "1" Unlike Linux, however, this option is not the only controlling factor at this point; for architectural reasons, the nvidia.ko kernel module must be built with support for either NVIDIA's or FreeBSD's AGP GART driver. By default, it is built with support for NVIDIA's internal driver, but it is possible to change this behaviour (see nv-freebsd.h for details). Please note that if you built nvidia.ko with support for FreeBSD's driver it will not load unless agp.ko is loaded. agp.ko is special in that you can not load it after the system boot is complete, you need to append the following line to /boot/loader.conf to make sure it is pre-loaded: # -- load FreeBSD AGP GART driver -- # agp_load="YES" Also note that if agp.ko is loaded, it may conflict with NVIDIA's AGP GART driver, causing stability problems. It is advised that you only load agp.ko if you are going to use it. For those wondering which of the two drivers is better, there is no good answer. For most people, the NVIDIA AGP GART driver will work just fine, but it sometimes makes sense to try the FreeBSD AGP driver. One reason may be that the NVIDIA driver doesn't support a given chipset while the FreeBSD driver does. In rare cases, system stability may be better with one of the two drivers. Please review the NVIDIA Linux Driver Set README for a complete list of AGP chipsets supported by the NVIDIA AGP GART driver. __________________________________________________________________________ (sec-06) CONFIGURING LOW-LEVEL PARAMETERS __________________________________________________________________________ The NVIDIA resource manager recognizes several low-level configuration parameters that can be set using the sysctl driver interface /before/ the X server is started. Normally you should not need to modify any of these parameters, but it is sometimes necessary or desirable to do so. To view the current settings of these parameters, you need to issue this sysctl command (nvidia.ko needs to be loaded): sysctl -a hw.nvidia.registry To change any of the parameters, you need to pass the complete name of the OID followed by '=' and the new value, e.g.: sysctl hw.nvidia.registry.EnableVia4x=1 It is possible to automate setting these paramaters by adding them to the /etc/sysctl.conf file. ``man 5 sysctl.conf'' for details. The following parameters are recognized by nvidia.ko: * * Option: VideoMemoryTypeOverride * * Description: * * We normally detect memory type on TNT cards by scanning the embedded * BIOS. Unfortunately, we've seen some cases where a TNT card has been * flashed with the wrong bios. For example, an SDRAM based TNT has been * flashed with an SGRAM bios, and therefore claims to be an SGRAM TNT. * We've therefore provided an override here. Make sure to set the value * toe the type of memory used on your card. * * Possible Values: * * 1: SDRAM * 2: SGRAM * * Note that we can only do so much here. There are border cases where * even this fails. For example, if 2 TNT cards are in the same system, * one SGRAM, one SDRAM. * * * Option: EnableVia4x * * Description: * * We've had problems with some Via chipsets in 4x mode, we need force * them back down to 2x mode. If you'd like to experiment with retaining * 4x mode, you may try setting this value to 1 If that hangs the system, * you're stuck with 2x mode; there's nothing we can do about it. * * Possible Values: * * 0: disable AGP 4x on Via chipsets (default) * 1: enable AGP 4x on Via chipsets * * * Option: EnableALiAGP * * Description: * * Some ALi chipsets (ALi1541, ALi1647) are known to cause severe system * stability problems with AGP enabled. To avoid lockups, we disable AGP * on systems with these chipsets by default. It appears that updating the * system BIOS and using recent versions of the kernel AGP Gart driver can * make such systems much more stable. If you own a system with one of the * aforementioned chipsets and had it working reasonably well previously, * or if you want to experiment with BIOS and AGPGART revisions, you can * re-enable AGP support by setting this option to 1. * * Possible Values: * * 0: disable AGP on Ali1541 and ALi1647 (default) * 1: enable AGP on Ali1541 and ALi1647 * * * Option: EnableAGPSBA * * Description: * * For stability reasons, the driver will not Side Band Addressing even if * both the host chipset and the AGP card support it. You may override this * behaviour with the following registry key. * * This is completely unsupported! * * Possible Values: * * 0 = disable Side Band Addressing (default on x86, see below) * 1 = enable Side Band Addressing (if supported) * * * Option: EnableAGPFW * * Description: * * Similar to Side Band Addressing, Fast Writes are disabled by default. If * you wish to enable them on systems that support them, you can do so with * this registry key. Please note that this may render your system unstable * with many AGP chipsets. * * This is completely unsupported! * * Possible Values: * * 0 = disable Fast Writes (default) * 1 = enable Fast Writes * * * Option: SoftEDIDs * * Description: * * The SoftEDIDs registry key enables dynamic generation of an appropriate * EDID for mobile LCD displays from data stored in the video BIOS. If this * is turned off, then on mobile systems, a hardcoded EDID will be chosen * from a table, based on the value of the Mobile registry key. * * Possible Values: * * 0 = disable dynamic EDID generation * 1 = enable dynamic EDID generation (default) * * * Option: Mobile * * Description: * * The Mobile registry key should only be needed on mobile systems if * SoftEDIDs is disabled (see above), in which case the mobile value * will be used to lookup the correct EDID for the mobile LCD. * * Possible Values: * * ~0 = auto detect the correct value (default) * 1 = Dell notebooks * 2 = non-Compal Toshiba * 3 = all other notebooks * 4 = Compal/Toshiba * 5 = Gateway * * Make sure to specify the correct value for your notebook. * __________________________________________________________________________ (sec-07) FREQUENTLY ASKED QUESTIONS __________________________________________________________________________ Q: X crashes during `startx`, and my XFree86.0.log file contains this error message: (EE) NVIDIA(0): Failed to obtain a shared memory identifier. A: The NVIDIA OpenGL driver and the NVIDIA X driver require shared memory to communicate; you must have: a) SYSVSHM built into your kernel b) XFree86-Server-4.2.1_3 or later Downloading XFree86 4.2.1 from the XFree86 ftpsite is not sufficient; a shared memory bug in XFree86 was fixed between 4.2.1 and XFree86-Server-4.2.1_3. Q: X fails to start, and during bootup time I get error messages like the following: nvidia0: Unable to allocate NVIDIA register resource. or: nvidia0: Unable to allocate interrupt resource. A: The system bios has not properly setup your graphics card; FreeBSD can't currently setup PCI devices that the BIOS leaves unconfigured. Please uncheck "PNP-OS" in your system bios. Q: Why do KDE applications crash on exit? A: The FreeBSD signal handler resets the %gs segment register, which prevents OpenGL from properly accessing data during shutdown from a signal handler. To fix this problem on a -STABLE kernel, you can apply this patch: /usr/X11R6/share/doc/NVIDIA/machdep.c.diff to sys/i386/i386/machdep.c and rebuild your kernel. The patch can be applied like this: cd /usr/src/sys/i386/i386/ patch -p0 -i /usr/X11R6/share/doc/NVIDIA/machdep.c.diff This change has already been made in recent -CURRENT kernel sources. Q: Why can the Linux compatibility libraries not correctly determine if they are used in a multithreaded application? A: The Linux compatibility libraries are not able to correctly determine if they are used in a multithreaded application because the %gs segment register is not initialized correctly for Linux compatibility. The __GL_SINGLE_THREADED environment variable (set to "1") can be used to work around this issue, but at the cost of thread-safeness. If you are using a -CURRENT kernel, you can fix this problem by applying this patch: /usr/X11R6/share/doc/NVIDIA/linux_sysvec.c.diff to sys/i386/linux/linux_sysvec.c and rebuild your kernel. This patch has been applied to recent -CURRENT kernel sources, so if patch complains about a conflict, it is most likely that your kernel already has this patch. The patch can be applied like this: cd /usr/src/sys/i386/linux/ patch -p0 -i /usr/X11R6/share/doc/NVIDIA/linux_sysvec.c.diff The patch adjusts the initialization value of the %gs register such that it is the same as on Linux systems. A comparable patch is not available for -STABLE. __________________________________________________________________________ (app-a) APPENDIX A: SUPPORTED NVIDIA GRAPHICS CHIPS __________________________________________________________________________ Please see the NVIDIA Linux Driver Set README for a complete list of all supported graphics chips. __________________________________________________________________________ (app-b) APPENDIX B: DEVELOPING MULTI-THREADED APPLICATIONS __________________________________________________________________________ The NVIDIA FreeBSD Accelerated Driver Set is fully thread-safe if native, multi-threaded applications are developed using the FreeBSD linux-threads port. If the above mentioned linux_sysvec.c.diff patch is applied, then the Linux ABI compatibility libraries are also fully thread-safe. The native NVIDIA FreeBSD OpenGL driver does not currently interact well with the libc_r, libkse, or libthr thread libraries. Until these issues are resolved, it is recommended that you use the FreeBSD linux-threads port for multithreaded OpenGL applications. __________________________________________________________________________ (app-c) APPENDIX C: THE SYSCTL INTERFACE __________________________________________________________________________ The sysctl interface allows you to obtain run-time information about the driver, any installed NVIDIA graphics cards and the AGP status. It also allows you to control low-level configuration options and/or overrides. The various pieces of information are held in a hierarchy under hw.nvidia and are accessible with the sysctl(8) command: - hw.nvidia.version Prints the installed driver revision - hw.nvidia.cards.n.* These OIDs provide information about NVIDIA device 'n': - model: the device's product name - irq: the IRQ claimed by this device - vbios: the device's VBIOS revision - type: the bus type of this device - hw.nvidia.agp.host-bridge.* - hw.nvidia.agp.card.* These OIDs provide information about the AGP capabilities of the installed AGP graphics card and host-bridge respectively. These values are most likely to be correct after system boot and before the X server is started (and the AGP subsystem intialized). - rates: the AGP rates supported by this device - fw: if the device suppoprts AGP fast-writes - sba: if the device supports AGP side-band-addressing - registers: the device's AGP registers, status:command - hw.nvidia.agp.status.* Prints AGP status information based on the AGP command registers of the host-bridge and of the AGP card. - status: if AGP is enabled or disabled - driver: which driver is being used - rate: the programmed AGP rate - fw: if fast-writes are enabled or disabled - sba: if side-band-addressing is enabled or disabled - hw.nvidia.registry.* Low-level kernel module configuration options. Changing these is typically not necessary and potentially dangerous. If you do need to change any of these options, you will need to do so *before* you start the X server. __________________________________________________________________________ (app-d) APPENDIX D: CREDITS __________________________________________________________________________ The port of the NVIDIA driver to FreeBSD is due in no small part to the many contributions of Christian Zander and Matthew N. Dodd . __________________________________________________________________________ (app-e) APPENDIX E: CONTACTING US __________________________________________________________________________ If you believe you have found a bug or have a problem you feel you need assistance with that can't be found elsewhere, you can send email to the following address: freebsd-gfx-bugs@nvidia.com