root/i2c/trunk/INSTALL @ 3376

These are the installation instruction for the i2c package.

There are three ways in which you can compile and install this package. Each
has its own strong points. They are:
 1. Complete separate from kernel compilation
    This will generate a set of modules which can be inserted and removed
    as needed; nothing will be written into the kernel tree;
 2. Semi-integrated into the kernel 
    This will add some files to your kernel tree, but has the advantage
    that module symbols are supported; the end result is functionally very 
    like the previous way;
 3. Patching of the kernel
    This will patch your kernel source tree. You must recompile your kernel
    to take advantage of this. But it makes it possible to compile drivers
    into the kernel itself, instead of having to add them as modules.

Each of these ways will be described below in detail. We recommend using
either method 1 or 3; method 2 is less well maintained.

NOTE: OPTION 3 WILL CURRENTLY NOT WORK FOR 2.0 AND OLDER 2.1 KERNELS!


Having a proper kernel tree (compilation options 1 and 2)
=========================================================

Usually, if you compile a user-space application, you can get away with
having a different version of the kernel running than the version of the
kernel header files against which you compiled it. But a perfect match
is needed for the first two compilation options above.

Let's say you want to use the i2c modules with the kernel 2.1.12 you
are running now. What you need, is the original tree in which you
compiled that 2.1.12 kernel. A freshly unpacked 2.1.12 kernel will not
cut it, because `make *config dep' creates some files that are needed.
And even then, you will run into trouble, because you may not have
selected the exact same configuration variables. Plain advise: if you
do not have your original kernel tree anymore, recompile your kernel
first.

Note that there is no need for a perfect match at compilation time, just
at run-time. This means you can cross-compile against a different kernel
version, and the Makefile does not check for this.

Usually problems if the match is imperfect, is that either this package
won't compile at all (because it was a freshly unpacked tree without
some files generated by `make *config dep'), or that you can't insert
modules because of either a `kernel-module version mismatch' or because
of `unresolved kernel symbols'. If you get either of these messages,
check your kernel tree!

Note that some distributions are notably bad at this. To offset this
somewhat, not the files in /usr/include/{linux,asm} are used, but instead
those in /usr/src/linux/include/{linux,asm}. It is also possible to
tell the Makefile the kernel is somewhere else than at /usr/src/linux.


Separate from kernel compilation (compilation option 1)
=======================================================

This will compile and install the complete i2c package. Though nothing is
written to your kernel tree, a proper tree is still needed for this. See
below for what a proper kernel tree is.

At the top of the Makefile are a couple of configuration variables that
you may want to change. As far as possible, the Makefile tries to figure
out by itself their settings, but it is possible to overrule them. A list
is found below. Most important are the variables that determine where
your kernel is located (LINUX=/usr/src/linux) and where you want to
install your modules (MODDIR=/lib/modules/KERNELVERSION/extra/misc) and
header files (LINUX_INCLUDE_DIR=/usr/local/include/linux). You can see
that the installation locations are choosen in such a way that they
are separate from the true kernel.

Compilation is done by `make all'; `make install' installs the package.
You will get a lot of warnings about files which are not found, all 
ending on `.d'. You can safely ignore this; they contain dependency
information, which is regenerated on the spot.

Please continue reading this file before you start compiling.


Semi-integrated into the kernel compilation (compilation option 2)
==================================================================

Please reconsider first whether you truly want to use this compilation
option. Often, it is better to use the previous compilation technique.

This will compile and install the complete i2c package, by using the
kernel build system. Some file will be written to your kernel tree
for this.

At the top of the Makefile are a couple of configuration variables that
you may want to change. Not all of those variables are used if you 
use this compilation option, though. A list of them is found below.

Compilation is done by `make all'; `make install' installs the package.

Please continue reading this file before you start compiling.


Makefile configuration variables (compilation options 1 and 2)
==============================================================

BUILD_SYSTEM (both) default: lm_sensors
  The build system which is used. lm_sensors corresponds with compilation
  option 1; i2c with compilatin option 2.
SHELL (both) (default: /bin/sh)
  You may have to specify the full path to Bash here, if /bin/sh is some
  other shell. There have been conflicting reports on whether this is 
  needed.
LINUX (both) default: /usr/src/linux
  The location of your kernel tree.
COMPILE_KERNEL (both)
  This determines whether only the user-space utilities are needed (0) 
  or also the kernel modules (1). This is usually determined by checking
  whether the kernel was already patched to include the kernel modules, 
  but that is not really foolprool.
  At the moment of writing, there are no user-space utilities yet, so
  setting this to 0 will make for a very fast compilation :-)
SMP (compilation option 1 only)
  This must be set to 1 for a SMP kernel. The magic invocation should
  determine this automatically, so you should not have to bother with 
  this.
MODVER (compilation option 1 only)
  This must be set to 1 if CONFIG_MODVERSIONS is defined. The magic
  invocation should determine this automatically, so you should not
  have to bother with this.
MODDIR (both) default: /lib/modules/KERNELVERSION/extra/misc)
  The location where the kernel modules will be installed. 
LINUX_INCLUDE_DIR (compilation option 1 only) default: /usr/local/include/linux
  The location where the i2c header files will be installed
WARN (compilation option 1 only) default: 0
  Generate additional compilation warnings; mainly interesting for
  developers.


Handling the modules (compilation option 2)
===========================================

Once you have installed the kernel modules, you will have to make sure
they are found.

First, check whether your modutils will look in the right directory at
all. If you used build system 1, you will probably have to add lines
to /etc/conf.modules or /etc/modules.conf (use the one that exists, or
take your pick):
  (modules-2.0.0):
    path[misc]=/lib/modules/current/extra/misc
  (modutils-2.1.x):
    path=/lib/modules/current/extra
This assumes /lib/modules/current will always be linked to the correct
modules tree. If not, you will have to change it as appropriate for
your system.

Next, you will have to run `depmod -a' to have them recognised. Most
distributions run this command when you boot, so if you were cross-
compiling, you can skip this step.


Patching the kernel (compilation option 3)
==========================================

There is a special script which should be able to generate diffs against
any 2.0, 2.1, 2.2 and 2.3 kernel. Please report any problems to our
mailinglist. Note that it may fail, and probably silently, if you have
applied other patches to your kernel tree, or for very new kernels.
It *is* safe to run it if your kernel already has the i2c drivers, or
if it was patched with the lm_sensors drivers.

The kernel diffs are generated by the program `mkpatch.pl' in the mkpatch
subdirectory. It needs two arguments: the first one is the root of the
i2c package, the second one is the root of the kernel tree against
which the diffs will be generated. For example:
  cd /tmp/i2c-2.0.3
  mkpatch/mkpatch.pl . /usr/src/linux > /tmp/i2c-patch
You can apply the diffs as usual:
  cd /usr/src/linux
  patch -p1 -E < /tmp/i2c-patch
Genearation and application can easily be done in one step:
  mkpatch/mkpatch.pl . /usr/src/linux | patch -p1 -E -d /usr/src/linux
The generated diffs are of course only valid for the kernel version 
against which mkpatch.pl was run.

Once you have applied the patches, you can configure and compile your
kernel as usual. You will see the I2C configuration screen under the
`Character Devices' menu in menuconfig.


Using the I2C package
=====================

You can now load the modules by using `modprobe'. For example,
`modprobe i2c-elv' will load the i2c-elv modules, and all i2c modules
on which it depends.

You can not use demand-loading; you will have to issue explicit modprobe
instructions. The one exception is the `i2c-dev' module. You can 
automatically load it by adding the following line to etc/conf.modules or 
/etc/modules.conf (use the one that exists):
    alias char-major-89 i2c-dev

Note that there are no client drivers in this package; you will have to
get them from somewhere else (for example, download the lm_sensors
package at http://www.lm-sensors.nu). Without additional drivers and
programs, this package is of very limited use to you.


Old and new I2C drivers
=======================

In the current 2.2 and 2.3 kernels, there are already I2C drivers, but
they are not the same ones as in this package. They are much older, and
have a very limited functionality compared with the drivers included
here. Fortunately, they can co-exist peacefully, so you should not worry
about it. Except for one thing: `#include <linux/i2c.h>' can cause the
wrong header file to be included. If you patched the kernel (compilation
option 3), you will have to use `#include <linux/i2c-old.h>' to include
the old ones; in all other cases, including the old ones will probably
be impossible without copying them explicitly to some place that will
be checked first.