genksyms
Hurricane Electric Internet Services
NAME
genksyms - generate symbol version information
SYNOPSIS
genksyms [ -g ] [ -w ] [ -q ] [ output directory ]
extra debug options: [ -d ] [ -D ]
DESCRIPTION
Genksyms reads (on standard input) the output from gcc -E
source.c and generates a file containing version informa-
tion. 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
If the output directory doesn't exist, it will be created.
Genksyms normally looks for explicit symbol table defini-
tions in the source file, which are recognized by the con-
struct X(symbol)
All definitions and declarations of typedef, struct, union
and 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.
When a symbol table is found in the source (also see the
-g option) the symbol will be expanded to its full defini-
tion, where all struct's, unions, enums and typedefs will
be expanded down to their basic part, recursively.
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.
The version information in the kernel looks like: sym-
bol_R12345678, where 12345678 is the hexadicimal represen-
tation of the CRC.
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 recom-
mend a study of the first part of <linux/module.h> and the
two companions: <linux/symtab_begin.h> and
<linux/symtab_end.h>
The options are as follows:
-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.
-w Since genksyms tries to expand all definitions
fully, and also do an attempt at looking for ille-
gal 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.
-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.
-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.
-d For debugging genksyms, as well as your source,
you can look at how the incoming tokens are han-
dled. If you double this option, the explanation
will be sent to standard output, otherwise it will
be sent to standard error.
EXAMPLE
If you have a kernel that is updated for version handling,
you can test genksyms by doing:
cc -E -D__KERNEL__ -D__GENKSYMS__ -DCONFIG_MODVERSIONS -DEXPORT_SYMTAB
/linux/kernel/ksyms.c | genksyms /usr/include/linux/modules
This will create the file /usr/include/linux/mod-
ules/ksyms.ver, which contains version information for the
symbols found in ksyms.c
If you want to create your own symbol table in the kernel,
or in a module, the skeleton looks like:
#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);
...
}
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 resi-
dent function; before any modules have been loaded.
The last restriction might be lifted, if I decide to...
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
SEE ALSO
insmod(1), modprobe(1)
HISTORY
This versioning concept is a result from discussions, not
at least on the KERNEL-channel, with a lot of people.
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>
BUGS
Genksyms relies on getting valid input, conforming rather
strictly to ANSI C, although it only pretends to know any-
thing about it...
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.