README

__________________________________________________________________________

NVIDIA-INSTALLER SOURCE DOCUMENTATION
__________________________________________________________________________

Information on how to use the nvidia-installer is in:

    Chapter 4. Installing the NVIDIA Driver

of the NVIDIA driver README (available from the NVIDIA Linux driver
download page, and installed in /usr/share/doc/NVIDIA_GLX-1.0/).


There is not currently any formal documentation describing the
implementation of nvidia-installer, but the source code is fairly
well commented.


Build dependencies of nvidia-installer include:

   ncurses pciutils

Please ensure that the appropriate development packages for these
dependencies have been installed before building nvidia-installer.


One interesting thing to note is that user interface shared libraries
are built into nvidia-installer to avoid potential problems with
the installer not being able to find the user interface libraries (or
finding the wrong ones, etc): after the shared lib is built, the utility
`gen-ui-array` is run on it to create a source file storing a byte
array of the data that is the shared library.  When the installer runs,
it writes this byte data to a temporary file and then dlopens() it.

 
This directory also contains source for a simple tool 'mkprecompiled',
which is used for stamping nv-linux.o's (aka the kernel interfaces)
with the necessary information so that the installer can match it to a
running kernel. nvidia-installer can automate the process of building
a precompiled kernel interface package when used with the installer's
"--add-this-kernel" option - mkprecompiled is a standalone utility that
can be used to build a precompiled kernel interface package independently
of nvidia-installer.

To build a precompiled kernel interface package using mkprecompiled, you
might do the following:

    sh NVIDIA-Linux-x86-XXX.YY.run --extract-only
    cd NVIDIA-Linux-x86-XXX.YY/kernel/
    modules=`head -n 4 ../.manifest | tail -n 1`
    interface_files=`for module in $modules; do
        echo $module | grep -v nvidia-uvm |
        sed -e 's/nvidia/nv/' -e 's/$/-linux.o/'
    done`
    make $interface_files
    for interface in $interface_files; do
        nv_stem=`echo $interface | sed 's/-linux.o$//'`
        module_name=`echo $nv_stem | sed 's/nv/nvidia/'`
        ../mkprecompiled --pack precompiled-mykernel \
            --driver-version XXX.YY \
            --proc-version-string "`cat /proc/version`" \
            --description "This is not an interesting description" \
            --kernel-interface $interface \
            --linked-module-name $module_name.ko \
            --core-object-name $module_name/$nv_stem-kernel.o_binary \
            --target-directory .
    done
    if [ -f nvidia-uvm.ko ]; then
        ../mkprecompiled --pack precompiled-mykernel \
            --kernel-module nvidia-uvm.ko \
            --target-directory .
    fi
    mkdir -p precompiled
    mv precompiled-mykernel precompiled

(where "XXX.YY" is replaced with the driver version number).


To build precompiled kernel interfaces for a kernel other than the
currently running one, set SYSSRC=/path/to/kernel-source on the `make`
command line. If your kernel sources use a separate output directory,
additionally set SYSOUT=/path/to/kernel-output. You will also need to
extract the correct proc version string from the kernel image, so that
it can be passed as an argument to mkprecompiled, e.g.:

    /path/to/kernel-source/scripts/extract-vmlinux /boot/vmlinuz |
        strings | grep "^Linux version"


nvidia-installer will scan the contents of the kernel/precompiled/
directory for any precompiled kernel interfaces that match the running
kernel's /proc/version string.

If you would like to provide precompiled kernel interfaces for others
to use, you may build them as above.  To use them, users can do the
following:

    sh NVIDIA-Linux-x86-XXX.YY.run --extract-only
    mkdir -p NVIDIA-Linux-x86-XXX.YY/kernel/precompiled
    cp precompiled-mykernel NVIDIA-Linux-x86-XXX.YY/kernel/precompiled
    ./NVIDIA-Linux-x86-XXX.YY/nvidia-installer


(Updated: 2003-09-23)  The search path for directories containing
precompiled kernel interfaces has been extended; the heuristic
is now:

    - if --precompiled-kernel-interfaces-path was specified, search
      in that directory; if no match found, then

    - search in the directory /lib/modules/precompiled/`uname -r`/nvidia/gfx/,
      if no match found, then

    - search in the usr/src/nv/precompiled directory of the .run file,
      if no match found, then

    - give up and just build the kernel module yourself


TODO:

- Add new user interfaces (gtk+/qt/your toolkit of choice).

- Add additional tests to be run for the '--sanity' option.

- Cleanup memory leaks.

- Improve error messages.

- Internationalization.

Patches are very welcome, and may be submitted to linux-bugs@nvidia.com