kallsyms

KALLSYMS(8)                  Linux Module Support                  KALLSYMS(8)



NAME
       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 version  of  the  kernel.
          The  size  and position of the __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 __kallsyms section
          entries.
       *  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



Linux                          January 31, 2002                    KALLSYMS(8)