.\" Copyright (c) 1994 Bjorn Ekwall <bj0rn@blox.se>
.\" This program is distributed according to the Gnu General Public License.
.\" See the file COPYING in the kernel source directory /linux
.\"
.\"
.TH GENKSYMS 8 "May 14, 1995" Linux "Linux Module Support"
.SH NAME
genksyms \- generate symbol version information
.SH SYNOPSIS
.B genksyms
[ \-g ] [ \-w ] [ \-q ]
[ output directory ]
.br
extra debug options: [ \-d ] [ \-D ]
.SH DESCRIPTION
.B Genksyms
reads (on standard input) the output from
.B gcc -E source.c
and generates a file containing version information.
This file will be created in the named output directory,
and will be named by taking the basename of the original source
and append an extension: .ver
.br
If the output directory doesn't exist, it will be created.
.PP
.B Genksyms
normally looks for explicit symbol table definitions in the source
file, which are recognized by the construct
.B X(symbol)
.br
All definitions and declarations of
.B typedef, struct, union
and
.B enum
will be saved for later expansion.
Every global symbol will also be saved, together with pointers
that will enable a full expansion later on.
.PP
When a symbol table is found in the source (also see the -g option)
the symbol will be expanded to its full definition, where all
struct's, unions, enums and typedefs will be expanded down to
their basic part, recursively.
.br
This final string will then be used as input to a CRC algorithm
that will give an integer that will change as soon as any of the
included definitions changes, for this symbol.
.br
The version information in the kernel looks like:
.B symbol_R12345678,
where 12345678 is the hexadicimal representation of the CRC.
.PP
There are some obscure (but legal) tricks used with the
C preprocessor, that will mark all relevant symbols in the
object file, and in any exported symbol tables.
I recommend a study of the first part of <linux/module.h>
and the two companions: <linux/symtab_begin.h> and <linux/symtab_end.h>
.PP
The options are as follows:
.TP 8
\-g
The \-g option makes genksyms create an output file based on the global
symbols in the source file.
If there is a symbol table in the source, this will override this option.
.TP 8
\-w
Since genksyms tries to expand all definitions fully, and also do
an attempt at looking for illegal syntax, there might be warnings
generated by genksyms. Normally these will be supressed, but it
is a good idea to enable the warnings by this option, at least
in the early stages of developing a function.
.TP 8
\-q
Since the warnings are supressed by default, this supressing
option has no function, but if you enable default warnings in
the source, you can disable them with this switch.
.TP 8
\-D
If you want to check what each symbol is expanded into,
you can get this information on standard output, with this switch.
No version file will be generated.
.TP 8
\-d
For debugging genksyms, as well as your source, you can look
at how the incoming tokens are handled.
If you double this option, the explanation will be sent to standard
output, otherwise it will be sent to standard error.
.SH EXAMPLE
If you have a kernel that is updated for version handling,
you can test genksyms by doing:
.PP
.nf
	cc -E -D__KERNEL__ -D__GENKSYMS__ -DCONFIG_MODVERSIONS -DEXPORT_SYMTAB
		/linux/kernel/ksyms.c | genksyms /usr/include/linux/modules

.fi
This will create the file /usr/include/linux/modules/ksyms.ver, which
contains version information for the symbols found in ksyms.c
.PP
If you want to create your own symbol table in the kernel, or in a module,
the skeleton looks like:
.PP
.nf
	#include <linux/module.h>
	  ...
	int my_export;
	  ...
	static struct symbol_table my_symtab = {
	#include <linux/symtab_begin.h>
		X(my_export),
	#include <linux/symtab_end.h>
	};
	  ...
	routine_init()
	{
		  ...
		register_symtab(&my_symtab);
		  ...
	}

.fi
That is all there is to it!
Just make sure that the call to register_symtab is done in the
context of the module initialization, or, if you are calling
from a kernel resident function; before any modules have been
loaded.
.br
The last restriction might be lifted, if I decide to...
.SH FILES
  linux/include/linux/module.h
  linux/include/linux/symtab_begin.h
  linux/include/linux/symtab_end.h
  linux/include/linux/modversions.h
  linux/include/linux/modules/*.ver
.SH SEE ALSO
insmod(1), modprobe(1)
.SH HISTORY
This versioning concept is a result from discussions, not at least
on the KERNEL-channel, with a lot of people.
.PP
The genksyms utility was created in 1994 by Bjorn Ekwall <bj0rn@blox.se>
being mostly inspired by Jacques Gelinas <jack@solucorp.ca>
and Jeremy Fitzhardinge <jeremy@suite.sw.oz.au>
.SH BUGS
.B Genksyms
relies on getting valid input, conforming rather strictly to ANSI C,
although it only pretends to know anything about it...