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