NVIDIA Accelerated FreeBSD Driver Set README & Installation Guide Last Updated: $Date: 2005/03/08 $ Most Recent Driver: 1.0-7174 This README aims to provide rudimentary coverage of the steps required to install and configure the NVIDIA FreeBSD Driver Set on a computer running FreeBSD 5.x -STABLE. 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 5-STABLE (FreeBSD 5.3 or later) Please review sec-05: CHOOSING THE AGP GART DRIVER for AGP related information. - kernel source tree in /usr/src/sys (package 'ssys' installed) - Xorg 6.7.0 or XFree86 4.2 and greater FreeBSD -STABLE versions older than FreeBSD 5.3 and FreeBSD 6.x -CURRENT development snapshots 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 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-7174 /compat/linux/usr/lib - libnvidia-tls.so.1.0-7174 /compat/linux/usr/lib - libGLcore.so.1.0-7174 /compat/linux/usr/lib __________________________________________________________________________ (sec-03) BASIC CONFIGURATION INSTRUCTIONS __________________________________________________________________________ These configuration instructions assume that you have a basic XFree86 or Xorg configuration file adapted for your system. The XFree86/Xorg 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/Xorg 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/Xorg 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/xorg.conf 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). __________________________________________________________________________ (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 driver or if it should rely on the OS provided AGP driver with the "NvAGP" XFree86/Xorg config file option: - Option "NvAGP" "0" Disable AGP - Option "NvAGP" "1" Use NVIDIA's AGP GART Driver - Option "NvAGP" "2" Use the OS FreeBSD 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; because of known problems, nvidia.ko is built without support for FreeBSD's AGP driver by default. This behavior 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; in order to allow NvAGP to work, the kernel can be rebuilt without 'device agp' or the following entry added to /boot/device.hints: hint.agp.0.disabled="1" When built with support for FreeBSD's AGP 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 AGP chipset or was explicitely disabled with device hints). Note: it is highly recommended that you use the NVIDIA AGP driver. Please review the NVIDIA Linux(!) Driver Set README for a complete list of AGP chipsets supported by the NVIDIA AGP driver (NvAGP). __________________________________________________________________________ (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: 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. * * This option is disabled by default, see below for information on how * to enable it. * * * 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: ReqAGPRate * * Description: * * Normally, the driver will compare speed modes of the chipset & card, * picking the highest common rate. This key forces a maximum limit, to * limit the driver to lower speeds. The driver will not attempt a speed * beyond what the chipset and card claim they are capable of. * * Make sure you really know what you're doing before you enable this * override. By default, AGP drivers will enable the fastest AGP rate * your card and motherboard chipset are capable of. Then, in some cases, * our driver will force this rate down to work around bugs in both our * chipsets, and motherboard chipsets. Using this variable will override * our bug fixes. This may be desirable in some cases, but not most. * * This is completely unsupported! * * Possible Values: * * This option expects a bitmask (7 = 1 | 2 | 4, 3 = 1 | 2, etc) * * This option is disabled by default, see below for information on how * to enable it. * * * 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 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 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: 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. __________________________________________________________________________ (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 thread-safe on FreeBSD 5.3 or later systems making use of the libpthread or libthr KSE threading libraries. On these systems, the NVIDIA Linux ABI compatibility libraries are fully thread-safe, as well. __________________________________________________________________________ (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