NVIDIA Accelerated FreeBSD Driver Set README & Installation Guide Last Updated: $Date: 2004/07/23 $ Most Recent Driver: 1.0-6113 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 (4.9 or later), or FreeBSD -CURRENT (5.2.1 or later) * A FreeBSD 4.x/-STABLE kernel configured with: options SYSVSHM * A FreeBSD 5.x/-CURRENT kernel configured with: options SYSVSHM Please review sec-05: CHOOSING THE AGP GART DRIVER for AGP related information. - 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.9 are not supported. Note that if you are using FreeBSD 4.10, the NVIDIA driver will not work correctly by default; please refer to the FAQ section for details. If you are using a -CURRENT kernel more recent than 05/25/2004, this may apply to your system, as well. __________________________________________________________________________ (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 install 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 (unless the system is using devfs), 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 - libnvidia-tls.so /usr/X11R6/lib - libnvidia-tls.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-6113 /compat/linux/usr/lib - libnvidia-tls.so.1.0-6113 /compat/linux/usr/lib - libGLcore.so.1.0-6113 /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 exclusive support for NVIDIA's AGP GART driver or with support for FreeBSD's driver and NVIDIA's driver. By default, nvidia.ko is built with support for NVIDIA's internal driver, only; this can be changed (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 could conflict with NVIDIA's AGP GART driver (NvAGP), resulting in stability problems; for this reason, the NVIDIA driver will abort NvAGP initialization when it detects agp.ko. Note that current FreeBSD releases are shipped with agp.ko built into the kernel, which will need to be rebuilt without 'device agp'. Very recent -CURRENT kernels allow disabling agp.ko via device hints; if you're using such a kernel, adding the following to /boot/device.hints is sufficient: hint.agp.0.disabled="1" If you're using FreeBSD 5.2.1 or another -CURRENT kernel that does not yet offer this functionality, the following patch will enable it: /usr/X11R6/share/doc/NVIDIA_GLX-1.0/agp.ko-hints.diff The patch can be applied like this: cd /usr/src/sys/ patch -p2 -i /usr/X11R6/share/doc/NVIDIA_GLX-1.0/agp.ko-hints.diff When built with support for FreeBSD's AGP GART driver, nvidia.ko will fall back to using NvAGP when it doesn't detect agp.ko (this will be the case when agp.ko does not support your chipset or was explicitely disabled with device hints). It is highly recommended that you use the NVIDIA NvAGP AGP GART driver. 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. See 'man 5 sysctl.conf' for details. The following parameters are recognized by nvidia.ko: * * 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: NvAGP * * Description: * * This options controls which AGP GART driver is used when no explicit * request is made to change the default (X server). * * Possible Values: * * 0 = disable AGP support * 1 = use NVIDIA's builtin driver (if possible) * 2 = use the kernel's AGPGART driver (if possible) * 3 = use any available driver (try 2, then 1) * * Please note that NVIDIA's internal AGP GART driver will not be used * if AGPGART was either statically linked into your kernel or built as * a kernel module and loaded before the NVIDIA kernel module. * * * 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: I have read that the NVIDIA FreeBSD Driver is not a native driver, but sits on top of the Linux ABI compatibility layer. Is this true? A: No, the NVIDIA FreeBSD Driver Set is a native driver. It does provide Linux OpenGL libraries in addition to the native, FreeBSD libraries to enable users to run Linux OpenGL applications. 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: NVRM: NVIDIA REG resource alloc failed. or: nvidia0: NVRM: NVIDIA IRQ resource alloc failed. 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: X fails to start, and during bootup time I get the following error message: nvidia0: NVRM: NVIDIA MEM resource alloc failed. A: On certain FreeBSD -CURRENT kernels, it may be necessary to add the following line to /boot/loader.conf: hw.pci.allow_unsupported_io_range="1" This should allow the NVIDIA kernel module to attach. 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_GLX-1.0/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_GLX-1.0/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. Q: I am using FreeBSD 4.10 (or -CURRENT more recent than 05/25/2004), and the NVIDIA driver doesn't work correctly. A: The msync(2) system call does not work correctly for character special files on these kernels. To solve this problem, you can set the VM OID 'old_msync' to '1' or apply one of the two patches below: sysctl vm.old_msync=1 It is possible to automate this by adding an appropriate entry in the /etc/sysctl.conf file. See 'man 5 sysctl.conf' for details. Furthermore, a memory leak has been identified in the device pager that is exposed by the NVIDIA driver. The device_pager.c patches solve this problem, as well. For users of FreeBSD 4.10/-STABLE: /usr/X11R6/share/doc/NVIDIA_GLX-1.0/device_pager.c_4.10.diff /usr/X11R6/share/doc/NVIDIA_GLX-1.0/vm_map.c_4.10.diff The patches can be applied like this: cd /usr/src/sys/vm/ patch -p0 -i /usr/X11R6/share/doc/NVIDIA_GLX-1.0/device_pager.c_4.10.diff patch -p0 -i /usr/X11R6/share/doc/NVIDIA_GLX-1.0/vm_map.c_4.10.diff For users of FreeBSD 5.2.1/-CURRENT: /usr/X11R6/share/doc/NVIDIA_GLX-1.0/device_pager.c_5.2.diff /usr/X11R6/share/doc/NVIDIA_GLX-1.0/vm_object.c_5.2.diff The patches can be applied like this: cd /usr/src/sys/vm/ patch -p0 -i /usr/X11R6/share/doc/NVIDIA_GLX-1.0/device_pager.c_5.2.diff patch -p0 -i /usr/X11R6/share/doc/NVIDIA_GLX-1.0/vm_object.c_5.2.diff Q: When I try to start X, all I get is a black screen. A: This can be the result of a variety of problems. If you have not done so already, try disabling ACPI support and look at the NVIDIA Linux driver FAQ. Q: Is the nvidia-settings utility available for FreeBSD? A: Due to differences between -STABLE and -CURRENT, no prebuilt version of nvidia-settings is shipped with the driver. It can be downloaded and built from source, provided you have recent ports of gtk+-2.x and gmake installed on your system: Download nvidia-settings-1.0.tar.gz (or the latest version) from this location: ftp://download.nvidia.com/XFree86/nvidia-settings You can then extract, build and install it (to /usr/local/bin) with: tar zxf nvidia-settings-1.0.tar.gz cd nvidia-settings-1.0 gmake install __________________________________________________________________________ (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 __________________________________________________________________________ This release of the NVIDIA FreeBSD Accelerated Driver Set is not safe for use with native multi-threaded applications. TLS support was removed to improve compatibility with FreeBSD -CURRENT installations using FreeBSD's new threading libraries. NVIDIA is working with FreeBSD developers to ensure that future releases of the NVIDIA driver will support FreeBSD's upcoming static TLS mechanism after its expected introduction with FreeBSD 5.3. Note that on FreeBSD -CURRENT, the Linux ABI compatibility libraries are fully thread-safe. __________________________________________________________________________ (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