Written by Bjorn Ekwall <bj0rn@blox.se> for genksyms-0.40, December 9 1994

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 you also do 'make install' and (if necessary) apply the small
patches in the DIFFS directory, 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 requirements are that <linux/config.h>, <linux/module.h>
and <linux/version.h> are included in the source.
Note: the file <linux/module.h> _must_ be the first include file!!!

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.

NOTE 1 (for kernels without version support):

In the directory DIFFS you will find some small patches that should
be added to the kernel. They are relative 1.1.78, but could be patched
in by hand in older kernels, if necessary...


NOTE 2:

The set of include-files to the current "linux/kernel/ksyms.c" is not
complete! This will be seen as 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!
