manual/modutils/original/man8/kallsyms.8

   1 .\" Copyright (c) 2000 Keith Owens <kaos@ocs.com.au>
   2 .\" This program is distributed according to the Gnu General Public License.
   3 .\" See the file COPYING in the kernel source directory.
   4 .\"
   5 .TH KALLSYMS 8 "January 31, 2002" Linux "Linux Module Support"
   6 .SH NAME
   7 kallsyms \- Extract all kernel symbols for debugging
   8 .SH SYNOPSIS
   9 .B kallsyms
  10 [\-Vh] kernel_filename
  11 .SH DESCRIPTION
  12 .hy 0
  13 .B Kallsyms
  14 extracts all the non-stack symbols from a kernel and builds a data blob
  15 that can be linked into that kernel for use by debuggers.
  16 .PP
  17 A normal kernel only exports symbols that are used by modules.
  18 For debugging you may want a list of all the non-stack symbols, not
  19 just the exported ones.
  20 .B kallsyms
  21 extracts all sections and symbols from a kernel, constructs a list of
  22 the sections, symbols and their addresses and writes a relocatable
  23 object containing just the __kallsyms section.
  24 After the __kallsyms section is linked into the kernel and the kernel
  25 has been booted, any debugger can use the data in the __kallsyms
  26 section to get better symbol resolution.
  27 .PP
  28 For example, a debugger can use the __kallsyms data to resolve a kernel
  29 address to:
  30 .PD 0
  31 .IP * 3
  32 The owning kernel or module.
  33 .IP * 3
  34 The section within the owning code.
  35 .IP * 3
  36 The nearest symbol.
  37 .PD 1
  38 .SH OPTIONS
  39 .TP
  40 .BR \-h ", " \-\-help
  41 Display a summary of options and exit.
  42 .TP
  43 .BR \-V ", " \-\-version
  44 Display the version of \fBkallsyms\fR and exit.
  45 .SH LINKER PASSES
  46 .PP
  47 To create a kernel containing an accurate __kallsyms section, you have
  48 to make four linker passes instead of the normal single link step.
  49 kallsyms and the linker are fast, the three extra steps take a few
  50 seconds on a P200.
  51 .IP 1 3
  52 The initial build of the kernel, without any __kallsyms data.
  53 Run \fBkallsyms\fR against the output of this link, creating a relocatable
  54 object which contains all the sections and symbols in the raw kernel.
  55 .IP 2 3
  56 Link the kernel again, this time including the \fBkallsyms\fR output from
  57 step (1).
  58 Adding the __kallsyms section changes the number of sections and many
  59 of the kernel symbol offsets so run \fBkallsyms\fR again against the second
  60 link, again saving the relocatable output.
  61 .IP 3 3
  62 Link the kernel again, this time including the \fBkallsyms\fR output from
  63 step (2).
  64 Run \fBkallsyms\fR against the latest version of the kernel.
  65 The size and position of the __kallsyms section on this run is now
  66 stable, none of the kernel sections or symbols will change after this
  67 run.
  68 The \fBkallsyms\fR output contains the final values of the kernel symbols.
  69 .IP 4 3
  70 Link the final kernel, including the \fBkallsyms\fR output from step (3).
  71 .SH DATA FORMAT
  72 .PP
  73 The __kallsyms section is a bit unusual.
  74 It deliberately has no relocatable data, all "pointers" are represented
  75 as byte offsets into the section or as absolute numbers.
  76 This means it can be stored anywhere without relocation problems.
  77 In particular it can be stored within a kernel image, it can be stored
  78 separately from the kernel image, it can be appended to a module just
  79 before loading, it can be stored in a separate area, etc.
  80 .PP
  81 \fI/usr/include/sys/kallsyms.h\fR contains the mappings for the __kallsyms
  82 data.
  83 .SS Header
  84 .PD 0
  85 .IP * 3
  86 Size of header.
  87 .IP * 3
  88 Total size of the __kallsyms data, including strings.
  89 .IP * 3
  90 Number of sections.
  91 This only included sections which are loaded into memory.
  92 .IP * 3
  93 Offset to the first section entry from start of the __kallsyms header.
  94 .IP * 3
  95 Size of each section entry, excluding the name string.
  96 .IP * 3
  97 Number of symbols.
  98 .IP * 3
  99 Offset to the first symbol entry from the start of the __kallsyms
 100 header.
 101 .IP * 3
 102 Size of each symbol entry, excluding the name string.
 103 .IP * 3
 104 Offset to the first string from the start of the __kallsyms header.
 105 .IP * 3
 106 Start address of the first section[1].
 107 .IP * 3
 108 End address of the last section[1].
 109 .PD 1
 110 .SS Section entry
 111 .PP
 112 One entry per loaded section.
 113 Since __kallsyms is a loaded section, if the input file contains a
 114 __kallsyms section then it is included in this list.
 115 .PD 0
 116 .IP * 3
 117 Start of the section within the kernel[1].
 118 .IP * 3
 119 Size of section.
 120 .IP * 3
 121 Offset to the name of section, from the start of the __kallsyms
 122 strings.
 123 .IP * 3
 124 Section flags, from the original Elf section.
 125 .PD 1
 126 .SS Symbol entry
 127 .PP
 128 One per symbol in the input file.
 129 Only symbols that fall within loaded sections are stored.
 130 .PD 0
 131 .IP * 3
 132 Offset to the __kallsyms section entry that this symbol falls within.
 133 The offset is from the start of the __kallsyms section entries.
 134 .IP * 3
 135 Address of the symbol within the kernel[1].
 136 The symbols are sorted in ascending order on this field.
 137 .IP * 3
 138 Offset to the name of symbol, from the start of the __kallsyms strings.
 139 .PD 1
 140 .SS Strings
 141 .PP
 142 A set of NUL terminated strings.
 143 Each name is referenced using an offset from the start of the
 144 __kallsyms string area.
 145 .SS Note [1]
 146 .PP
 147 These fields are exceptions to the "everything is an offset" rule.
 148 They contain absolute addresses within the kernel.
 149 .SH SEE ALSO
 150 \fBinsmod\fR(8).
 151 .SH HISTORY
 152 Initial version by Keith Owens <kaos@ocs.com.au>, April 2000