NVIDIA Accelerated FreeBSD Driver Set README & Installation Guide

Last Updated: $Date: 2005/06/13 $
Most Recent Driver: 1.0-7676

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-7676            /compat/linux/usr/lib
 - libnvidia-tls.so.1.0-7676    /compat/linux/usr/lib
 - libGLcore.so.1.0-7676        /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.


Q: When I attempt to start `nvidia-settings`, I get an error message of
   the form:

    Shared object "libgtk-x11-2.0.so.400" not found, required by nvidia-settings

A: Due to differences between the gtk+-2.x ports packages included with
   different FreeBSD 5.x releases, the prebuilt nvidia-settings binary
   shipped with the NVIDIA driver may not work with FreeBSD releases more
   recent than FreeBSD 5.3.

   If you have a recent ports package of gtk+-2.x and gmake installed
   on your system, you can build the nvidia-installer utility from source
   to solve this problem.

   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 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 <zander 'at' mail.minion.de>
and Matthew N. Dodd <mdodd 'at' freebsd.org>.


__________________________________________________________________________

(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


