GENKSYMS(8) manual page

NAME

genksyms - generate symbol version information

SYNOPSIS

genksyms [ -g ] [ -w ] [ -q ] [ output directory ]
extra debug options: [ -d ] [ -D ]

Genksyms reads (on standard input) the output from 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
If the output directory doesn't exist, it will be created.

Genksyms normally looks for explicit symbol table definitions in the source file, which are recognized by the construct 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 definition, 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: symbol_R12345678, where 12345678 is the hexadicimal representation 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 recommend 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 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.
-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 handled. 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/modules/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 resident function; before any modules have been loaded.
The last restriction might be lifted, if I decide to...

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

FILES

SEE ALSO

HISTORY

BUGS