Written by Bjorn Ekwall <bj0rn@blox.se> for genksyms-0.40, May 14 1995
(Updated in January 1995)

Contents:
	1. What is is.
	2. How to create and test.
	3. What is does, and how to use it.
	4. How to 'modifiy' the current loadable modules.
	5. Notes.

This package is created (and maintained) by Bjorn Ekwall <bj0rn@blox.se>
with inspiration, support and code from Jacques Gelinas <jack@solucorp.ca>
and Jeremy Fitzhardinge <jeremy@suite.sw.oz.au>.
The KERNEL-channel people have also contributed with a lot of ideas and input.


1. What is is.

The program 'genksyms' creates files to be included for adding version
information to some selected kernel symbols.  This will make it possible
to safely relax the currently hard dependence on a specific kernel version
for loadable modules.  The dependencies will instead be on the versions of
the actual symbols that a module uses.  The version information will be
automatically updated whenever any syntactic change is made to the kernel
that _might_ make the use of the module unsafe.


2. How to create and test.

Do: 'make test' and look at the file in the newly created directory
VERSIONHEADERS.

If the test fails, edit the Makefile and comment away the "LFLAGS" definition.
As a last resort, enable the definition of "YYTEXT_PTR" in the Makefile.

If you also do 'make install', the next time you do a 'make config'
for the kernel you will be asked if you want the module symbol version
support or not.  If you answer yes to this question, this package
will be in effect when you reboot your newly made kernel.

The 'genksyms' program is intended to be automatically run when a
kernel 'make' is being done.


3. What is does, and how to use it.

The program just barely knows ANSI C, but it will basically
take the output of "gcc -E -Dwhatever file.c" and build an internal
representation of all definitions and declarations.
(Read the comments in parsesym.c for a more lucid(?) explanation)

If it finds the construct 'X(symbol)' in the input stream,
it will look for that symbol and internally expand its _full_
definition down to its basic parts.
This full definition is then used as input to a 32-bit crc,
and this value (in hex) will be used as the 'version' of the symbol.

If you use the option '-D' to genksyms, it will print the expansion
of the symbols to stdout (instead of the module_version.h text).

On stdout you will normally see something almost humanly readable
that can be used _both_ as in include file for "linux/kernel/ksyms.c"
and _also_ as an include file for _all_ loadable modules.

This will result in exported kernel symbol names that will look
like this:
	_symbol_R01234567
instead of:
	_symbol
where the '_R01234567' part is the version string (01234567 is the
hexadecimal representation of the crc).

Since the module also includes this file, the C-compiler will 'invisibly'
replace all the symbols in the module, that are exported by the kernel,
so that the resulting object file will use exactly the same (versioned)
names as the kernel will later export!


4. How to 'modifiy' the current loadable modules.

No changes will be needed to the module source!

The only requirement is that <linux/module.h> is included in the source.

Note 1: the file <linux/module.h> _must_ be the first include file!!!

Note 2: For newer kernels, <linux/version.h> is included by <linux/module.h>,
so you don't have to.  For older kernels, you will also have to include
<linux/version.h>. If you get complaints about "kernel_version" being
multiple defined, just remove the "#include <linux_version.h>", or,
alternatively, add "#define __NO_VERSION__" before you include "module.h".

Note 3: If you compile a module that is _not_ included in the kernel tree,
you should also add the following to your CFLAGS in the module Makefile:
    "-DMODVERSIONS -include /usr/include/linux/modversions.h"
Some older versions of gcc had trouble with "-include", so in that case
you will have to add "#include <linux/modversions.h>" to the module as well.

All versions of insmod (including the one from modules-1.1.67) will
happily accept these modified symbols.  The only real difference can
be seen in the output from /proc/ksyms, that will be different since the
'version-expanded' symbol names will be shown instead of the 'normal' ones.
Note that the zImage.map file will still contain the 'normal' symbol names.

The included version of insmod makes full use of these features,
so that the dependencies between the kernel version and the modules
can be more relaxed, though still with the same demands on _real_
compatibility.

Actually, you can try a part this concept with the all later versions of
insmod (from the 'modules*.tar.gz'), if you use the option '-f'!


5. Notes.

If the set of include-files to "linux/kernel/ksyms.c" is not complete,
you will see warning messages from 'genksyms'.
The resulting output from 'genksyms' is still usable, but will
result in version strings that are not created from the _full_ definitions.
When the set of include files is made more "complete", the version
strings will change as well.  This _is_ a 'genksyms' feature, not a bug!
