genksyms

Hurricane Electric Internet Services: Accounts starting at $9.95/month
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: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.