root/i2c/trunk/doc/mkpatch

This file tries to document how the `mkpatch' program works.
The file in copyright (c) 1999 by Frodo Looijaard

mkpatch compares the newest I2C sources with what is found in a kernel,
and generates a set of diffs. These diffs can be amplied to that kernel,
after which the kernel is synchronised with the current I2C sources.

mkpatch needs two arguments. The first is the root of the I2C package,
the second is the root of Linux kernel tree. For example:
  cd /tmp/i2c-1.0.0
  mkpatch/mkpatch . /usr/src/linux
The patch file is written to stdout; any errors are written to stderr.
So you will want to capture the output:
  mkpatch/mkpatch . /usr/src/linux > /tmp/i2c-diffs
Later on, you will want to apply the diffs:
  cd /usr/src/linuc
  patch -p1 -E < /tmp/i2c-diffs
Of course, this can be combined:
  mkpatch/mkpatch . /usr/src/linux | patch -d /usr/src/linux -p1 -E

mkpatch uses several files in the mkpatch subdirectory. The location of
these files is hardcoded in the program, but all other files used are
specified in these files, and can easily be changed. Used files are:
  FILES
    a list of files that will be considered by mkpatch. Each line contains
    two filenames, separated by whitespace. The first is the name and
    location (relative to the I2C package root) of the I2C file, the
    second is the name and location (relative to the kernel root) of 
    the kernel file. A diff will be created between these two files.
  INCLUDES
    A list of include file changes. Each line contains two strings that
    can be found after a `#include' statement. All occurences of the
    first string will be changed to the second, for all I2C files in 
    FILES, before the normal diff is generated. This allow us to use
    `#include "i2c.h"' when compiling in the package tree, and
    `#include <linux/i2c.h>' in the kernel tree.
  OLDI2C
    The generated kernel diffs will rename the old I2C header file to
    `i2c-old'. In the files specified in this file, `#include' statements
    will be changed accordingly.
  Makefile, Config.in
    These files are new and will be copied to the appropriate place as
    specified in FILES.

mkpatch does several things:
  * It generates diffs to change `#include <linux/i2c.h>' to 
    `#include <linux/i2c-old.h>' for files mentioned in OLDI2C
  * For each file pair as specified in FILES, it creates a diff between
    them, but before that is done, it changes `#include' lines in the
    I2C file as specified in INCLUDES, and it takes care of
    lm_sensors changes.
  * It handles several special files, that have to be scanned explicitly
    to generate diffs to for them

The generated diffs have specific headers. It will seem as if the old
kernel was contained in the `linux-old' directory, and the new patched
kernel in the `linux' directory, regardless of where the kernel was
actually located.

Most intricate are the special files that are handled. These special
files were already present in the kernel, but had to be patched. Because
they can change between kernel versions, I had to scan them by hand to
find where the new code should be inserted. Each file has documented
what actually happens.

Sometimes, a new file is inserted in the kernel tree by the I2C package,
and it needs to be patched by the lm_sensors package. In that case, the
part that is patched by the lm_sensors package is specifically marked.
If not, the I2C package would back out the lm_sensors changes!
The markers are:
  sensors code starts here
  sensors code ends here
They may be anywhere on a line, and must always occur in pairs.
More than one pair may be present.