NAME    [Toc]    [Back]

       kallsyms - Extract all kernel symbols for debugging

SYNOPSIS    [Toc]    [Back]

       kallsyms [-Vh] kernel_filename

DESCRIPTION    [Toc]    [Back]

       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    [Toc]    [Back]

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

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

LINKER PASSES    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]
       *  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    [Toc]    [Back]
       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    [Toc]    [Back]
       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    [Toc]    [Back]
       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    [Toc]    [Back]

       insmod(8).

HISTORY    [Toc]    [Back]

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



Linux			       January 31, 2002 		   KALLSYMS(8)