kallsyms - Extract all kernel symbols for debugging


SYNOPSIS

       kallsyms [-Vh] kernel_filename


DESCRIPTION

       Kallsyms  extracts all the non-stack symbols from a kernel
       and builds a data blob that can be linked into that kernel
       for use by debuggers.

       A  normal  kernel  only  exports  symbols that are used by
       modules.  For debugging you may want a  list  of  all  the
       non-stack  symbols,  not just the exported ones.  kallsyms
       extracts  all  sections  and  symbols   from   a   kernel,
       constructs  a  list  of  the  sections,  symbols and their
       addresses and writes a relocatable object containing  just
       the  __kallsyms  section.  After the __kallsyms section is
       linked into the kernel and the kernel has been booted, any
       debugger can use the data in the __kallsyms section to get
       better symbol resolution.

       For example, a debugger can use  the  __kallsyms  data  to
       resolve a kernel address to:
       *  The owning kernel or module.
       *  The section within the owning code.
       *  The nearest symbol.


OPTIONS

       -h, --help
              Display a summary of options and exit.

       -V, --version
              Display the version of kallsyms and exit.


LINKER PASSES

       To  create  a  kernel  containing  an  accurate __kallsyms
       section, you have to make four linker  passes  instead  of
       the  normal single link step.  kallsyms and the linker are
       fast, the three extra steps take a few seconds on a  P200.

       1  The initial build of the kernel, without any __kallsyms
          data.  Run kallsyms against the output  of  this  link,
          creating  a  relocatable  object which contains all the
          sections and symbols in the raw kernel.

       2  Link the kernel again, this time including the kallsyms
          output  from  step  (1).  Adding the __kallsyms section
          changes the number of sections and many of  the  kernel
          symbol offsets so run kallsyms again against the second
          link, again saving the relocatable output.

       3  Link the kernel again, this time including the kallsyms
          output  from step (2).  Run kallsyms against the latest

          __kallsyms  section  on this run is now stable, none of
          the kernel sections or symbols will change  after  this
          run.   The kallsyms output contains the final values of
          the kernel symbols.

       4  Link the final kernel, including  the  kallsyms  output
          from step (3).


DATA FORMAT

       The  __kallsyms section is a bit unusual.  It deliberately
       has no relocatable data, all "pointers" are represented as
       byte  offsets  into  the  section  or as absolute numbers.
       This means it can be stored  anywhere  without  relocation
       problems.   In particular it can be stored within a kernel
       image, it can be stored separately from the kernel  image,
       it can be appended to a module just before loading, it can
       be stored in a separate area, etc.

       /usr/include/sys/kallsyms.h contains the mappings for  the
       __kallsyms data.

   Header
       *  Size of header.
       *  Total size of the __kallsyms data, including strings.
       *  Number  of sections.  This only included sections which
          are loaded into memory.
       *  Offset to the first section entry  from  start  of  the
          __kallsyms header.
       *  Size  of each section entry, excluding the name string.
       *  Number of symbols.
       *  Offset to the first symbol entry from the start of  the
          __kallsyms header.
       *  Size of each symbol entry, excluding the name string.
       *  Offset  to  the  first  string  from  the  start of the
          __kallsyms header.
       *  Start address of the first section[1].
       *  End address of the last section[1].

   Section entry
       One entry per  loaded  section.   Since  __kallsyms  is  a
       loaded  section,  if  the input file contains a __kallsyms
       section then it is included in this list.
       *  Start of the section within the kernel[1].
       *  Size of section.
       *  Offset to the name of section, from the  start  of  the
          __kallsyms strings.
       *  Section flags, from the original Elf section.

   Symbol entry
       One  per symbol in the input file.  Only symbols that fall
       within loaded sections are stored.
       *  Offset to the __kallsyms section entry that this symbol
          falls  within.   The  offset  is  from the start of the

       *  Address  of  the  symbol  within  the  kernel[1].   The
          symbols are sorted in ascending order on this field.
       *  Offset  to  the  name  of symbol, from the start of the
          __kallsyms strings.

   Strings
       A set of NUL terminated strings.  Each name is  referenced
       using  an  offset  from the start of the __kallsyms string
       area.

   Note [1]
       These fields are  exceptions  to  the  "everything  is  an
       offset"  rule.  They contain absolute addresses within the
       kernel.


SEE ALSO

       insmod(8).


HISTORY

       Initial version by Keith  Owens  <kaos@ocs.com.au>,  April
       2000


Man(1) output converted with man2html