aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-03-04 22:42:55 +0000
committerNik Clayton <nik@FreeBSD.org>1999-03-04 22:42:55 +0000
commitfe79ecbe4d70cad7758daa4c0ebdcea12e3bd317 (patch)
tree467fe938e26147822545ffa4e9edb7689084c381 /en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
parent772051fe94fb962ca7695afcc04934d381939c0f (diff)
downloaddoc-fe79ecbe4d70cad7758daa4c0ebdcea12e3bd317.tar.gz
doc-fe79ecbe4d70cad7758daa4c0ebdcea12e3bd317.zip
Revert one of my previous changes. Sentences now have two spaces after
the period. Apologies for the repository bloat. This is entirely a whitespace change.
Notes
Notes: svn path=/head/; revision=4465
Diffstat (limited to 'en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml')
-rw-r--r--en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml134
1 files changed, 67 insertions, 67 deletions
diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
index 2507290ae1..c7e43305ab 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
@@ -8,48 +8,48 @@
<title>Debugging a Kernel Crash Dump with <command>kgdb</command></title>
<para>Here are some instructions for getting kernel debugging working
- on a crash dump. They assume that you have enough swap space for a
- crash dump. If you have multiple swap partitions and the first one
+ on a crash dump. They assume that you have enough swap space for a
+ crash dump. If you have multiple swap partitions and the first one
is too small to hold the dump, you can configure your kernel to use
an alternate dump device (in the <literal>config
kernel</literal> line), or you can specify an alternate using the
- <citerefentry><refentrytitle>dumpon</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. The best way to use <citerefentry>
+ <citerefentry><refentrytitle>dumpon</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. The best way to use <citerefentry>
<refentrytitle>dumpon</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry> is to set the <literal>dumpdev</literal> variable in
- <filename>/etc/rc.conf</filename>. Typically you want to specify one of
+ <filename>/etc/rc.conf</filename>. Typically you want to specify one of
the swap devices specified in <filename>/etc/fstab</filename>.
Dumps to non-swap devices, tapes for example,
- are currently not supported. Config your kernel using
- <command>config -g</command>. See <link linkend="kernelconfig">Kernel
+ are currently not supported. Config your kernel using
+ <command>config -g</command>. See <link linkend="kernelconfig">Kernel
Configuration</link> for
details on configuring the FreeBSD kernel.</para>
<para>Use the <citerefentry><refentrytitle>dumpon</refentrytitle><manvolnum>8</manvolnum></citerefentry> command to tell the kernel
where to dump to (note that this will have to be done after
configuring the partition in question as swap space via
- <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>). This is normally arranged via
+ <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>). This is normally arranged via
<filename>/etc/rc.conf</filename> and <filename>/etc/rc</filename>.
Alternatively, you can hard-code the dump device via the <literal>dump</literal>
- clause in the <literal>config</literal> line of your kernel config file. This is
+ clause in the <literal>config</literal> line of your kernel config file. This is
deprecated and should be used only if you want a crash dump from a
kernel that crashes during booting.</para>
<note>
<para>In the following, the term <command>kgdb</command> refers to
- <command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This can be
+ <command>gdb</command> run in &ldquo;kernel debug mode&rdquo;. This can be
accomplished by either starting the <command>gdb</command> with
the option <option>-k</option>, or by linking and starting it
- under the name <command>kgdb</command>. This is not being done by
+ under the name <command>kgdb</command>. This is not being done by
default, however, and the idea is basically deprecated since the
GNU folks do not like their tools to behave differently when
- called by another name. This feature may well be discontinued in
+ called by another name. This feature may well be discontinued in
further releases.</para>
</note>
<para>When the kernel has been built make a copy of it, say
<filename>kernel.debug</filename>, and then run <command>strip
- -d</command> on the original. Install the original as normal. You
+ -d</command> on the original. Install the original as normal. You
may also install the unstripped kernel, but symbol table lookup time
for some programs will drastically increase, and since the whole
kernel is loaded entirely at boot time and cannot be swapped out
@@ -69,13 +69,13 @@ Dumps to non-swap devices, tapes for example,
<para>This instructs <citerefentry><refentrytitle>savecore</refentrytitle><manvolnum>8</manvolnum></citerefentry> to
- use another kernel for symbol name extraction. It would otherwise
+ use another kernel for symbol name extraction. It would otherwise
default to the currently running kernel and most likely not do
anything at all since the crash dump and the kernel symbols
differ.</para>
<para>Now, after a crash dump, go to
- <filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
+ <filename>/sys/compile/WHATEVER</filename> and run <command>kgdb</command>. From <command>kgdb</command>
do:
@@ -88,7 +88,7 @@ Dumps to non-swap devices, tapes for example,
kernel sources just like you can for any other program.</para>
<para>Here is a script log of a <command>kgdb</command>
- session illustrating the procedure. Long lines have been folded to
+ session illustrating the procedure. Long lines have been folded to
improve readability, and the lines are numbered for reference.
Despite this, it is a real-world error trace taken during the
development of the pcvt console driver.</para>
@@ -203,8 +203,8 @@ Dumps to non-swap devices, tapes for example,
<listitem>
<para>Force usage of a new stack frame; this is no longer
- necessary now. The stack frames are supposed to point to
- the right locations now, even in case of a trap. (I do not
+ necessary now. The stack frames are supposed to point to
+ the right locations now, even in case of a trap. (I do not
have a new core dump handy &lt;g&gt;, my kernel has not
panicked for a rather long time.) From looking at the code
in source line 403, there is a high probability that either
@@ -243,9 +243,9 @@ Dumps to non-swap devices, tapes for example,
<title>Debugging a crash dump with DDD</title>
<para>Examining a kernel crash dump with a graphical debugger like
- <command>ddd</command> is also possible. Add the <option>-k</option>
+ <command>ddd</command> is also possible. Add the <option>-k</option>
option to the <command>ddd</command> command line you would use
- normally. For example;</para>
+ normally. For example;</para>
<screen>&prompt.root; <userinput>ddd -k /var/crash/kernel.0 /var/crash/vmcore.0</userinput></screen>
@@ -260,32 +260,32 @@ Dumps to non-swap devices, tapes for example,
<para>What do you do if a kernel dumped core but you did not expect
it, and it is therefore not compiled using <command>config
- -g</command>? Not everything is lost here. Do not panic!</para>
+ -g</command>? Not everything is lost here. Do not panic!</para>
- <para>Of course, you still need to enable crash dumps. See above on
+ <para>Of course, you still need to enable crash dumps. See above on
the options you have to specify in order to do this.</para>
<para>Go to your kernel compile directory, and edit the line
- containing <literal>COPTFLAGS?=-O</literal>. Add the
+ containing <literal>COPTFLAGS?=-O</literal>. Add the
<option>-g</option> option there (but <emphasis>do not</emphasis>
- change anything on the level of optimization). If you do already
+ change anything on the level of optimization). If you do already
know roughly the probable location of the failing piece of code
(e.g., the <devicename>pcvt</devicename> driver in the example
- above), remove all the object files for this code. Rebuild the
- kernel. Due to the time stamp change on the Makefile, there will be
+ above), remove all the object files for this code. Rebuild the
+ kernel. Due to the time stamp change on the Makefile, there will be
some other object files rebuild, for example
- <filename>trap.o</filename>. With a bit of luck, the added
+ <filename>trap.o</filename>. With a bit of luck, the added
<option>-g</option> option will not change anything for the
generated code, so you will finally get a new kernel with similar
- code to the faulting one but some debugging symbols. You should at
+ code to the faulting one but some debugging symbols. You should at
least verify the old and new sizes with the
- <citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry> command. If there is a mismatch, you
+ <citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry> command. If there is a mismatch, you
probably need to give up here.</para>
- <para>Go and examine the dump as described above. The debugging
+ <para>Go and examine the dump as described above. The debugging
symbols might be incomplete for some places, as can be seen in the
stack trace in the example above where some functions are displayed
- without line numbers and argument lists. If you need more debugging
+ without line numbers and argument lists. If you need more debugging
symbols, remove the appropriate object files and repeat the
<command>kgdb</command> session until you know
enough.</para>
@@ -300,52 +300,52 @@ Dumps to non-swap devices, tapes for example,
<para>While <command>kgdb</command> as an offline debugger
provides a very high level of user interface, there are some things
- it cannot do. The most important ones being breakpointing and
+ it cannot do. The most important ones being breakpointing and
single-stepping kernel code.</para>
<para>If you need to do low-level debugging on your kernel, there is
- an on-line debugger available called DDB. It allows to setting
+ an on-line debugger available called DDB. It allows to setting
breakpoints, single-steping kernel functions, examining and changing
- kernel variables, etc. However, it cannot access kernel source
+ kernel variables, etc. However, it cannot access kernel source
files, and only has access to the global and static symbols, not to
the full debug information like <command>kgdb</command>.</para>
<para>To configure your kernel to include DDB, add the option line
<programlisting>
-options DDB</programlisting> to your config file, and rebuild. (See <link
+options DDB</programlisting> to your config file, and rebuild. (See <link
linkend="kernelconfig">Kernel Configuration</link> for details on configuring the
FreeBSD kernel.</para>
<note>
<para>Note that if you have an older version of the boot blocks,
- your debugger symbols might not be loaded at all. Update the boot
+ your debugger symbols might not be loaded at all. Update the boot
blocks; the recent ones load the DDB symbols
automagically.)</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
- DDB. The first, and earliest way is to type the boot flag
- <option>-d</option> right at the boot prompt. The kernel will start
- up in debug mode and enter DDB prior to any device probing. Hence
+ DDB. The first, and earliest way is to type the boot flag
+ <option>-d</option> right at the boot prompt. The kernel will start
+ up in debug mode and enter DDB prior to any device probing. Hence
you can even debug the device probe/attach functions.</para>
<para>The second scenario is a hot-key on the keyboard, usually
- Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
- distributed maps do this, so watch out. There is an option available
+ Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
+ distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on
the console line to enter DDB (<literal>options
- BREAK_TO_DEBUGGER</literal> in the kernel config file). It is
+ BREAK_TO_DEBUGGER</literal> in the kernel config file). It is
not the default since there are a lot of crappy serial adapters
around that gratuitously generate a BREAK condition, for example
when pulling the cable.</para>
<para>The third way is that any panic condition will branch to DDB if
- the kernel is configured to use it. For this reason, it is not
+ the kernel is configured to use it. For this reason, it is not
wise to configure a kernel with DDB for a machine running
unattended.</para>
- <para>The DDB commands roughly resemble some <command>gdb</command> commands. The first thing you probably
+ <para>The DDB commands roughly resemble some <command>gdb</command> commands. The first thing you probably
need to do is to set a breakpoint:</para>
@@ -356,7 +356,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>Numbers are taken hexadecimal by default, but to make them
distinct from symbol names; hexadecimal numbers starting with the
letters <literal>a-f</literal> need to be preceded with
- <literal>0x</literal> (this is optional for other numbers). Simple
+ <literal>0x</literal> (this is optional for other numbers). Simple
expressions are allowed, for example: <literal>function-name +
0x103</literal>.</para>
@@ -386,7 +386,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>The first form will be accepted immediately after
- a breakpoint hit, and deletes the current breakpoint. The second
+ a breakpoint hit, and deletes the current breakpoint. The second
form can remove any breakpoint, but you need to specify the exact
address; this can be obtained from:</para>
@@ -422,8 +422,8 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
for word/halfword/byte access, and
- hexadecimal/decimal/character/ string display. The number after the
- comma is the object count. To display the next 0x10 items, simply
+ hexadecimal/decimal/character/ string display. The number after the
+ comma is the object count. To display the next 0x10 items, simply
use:</para>
@@ -487,9 +487,9 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>Now you have now examined why your kernel failed, and you wish
- to reboot. Remember that, depending on the severity of previous
+ to reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working
- as expected. Perform one of the following actions to shut down and
+ as expected. Perform one of the following actions to shut down and
reboot your system:</para>
@@ -497,8 +497,8 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>This will cause your kernel to dump core and reboot, so you can
- later analyze the core on a higher level with kgdb. This command
- usually must be followed by another <command>continue</command> statement. There is now an alias for
+ later analyze the core on a higher level with kgdb. This command
+ usually must be followed by another <command>continue</command> statement. There is now an alias for
this: <command>panic</command>.</para>
@@ -507,7 +507,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>Which might be a good way to cleanly shut down the
running system, <function>sync()</function> all disks, and finally
- reboot. As long as the disk and file system interfaces of the
+ reboot. As long as the disk and file system interfaces of the
kernel are not damaged, this might be a good way for an almost clean
shutdown.</para>
@@ -526,7 +526,7 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>However, it is highly recommended to have a
printed copy of the <citerefentry><refentrytitle>ddb</refentrytitle><manvolnum>4</manvolnum></citerefentry> manual page
- ready for a debugging session. Remember that it is hard to read the
+ ready for a debugging session. Remember that it is hard to read the
on-line manual while single-stepping the kernel.</para>
</sect1>
@@ -538,9 +538,9 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
actually a very neat one.</para>
<para>GDB has already supported <emphasis>remote debugging</emphasis>
- for a long time. This is done using a very simple protocol along a
- serial line. Unlike the other methods described above, you will
- need two machines for doing this. One is the host providing the
+ for a long time. This is done using a very simple protocol along a
+ serial line. Unlike the other methods described above, you will
+ need two machines for doing this. One is the host providing the
debugging environment, including all the sources, and a copy of the
kernel binary with all the symbols in it, and the other one is the
target machine that simply runs a similar copy of the very same
@@ -548,12 +548,12 @@ options DDB</programlisting> to your config file, and rebuild. (See <link
<para>You should configure the kernel in question with <command>config
-g</command>, include <option>DDB</option> into the
- configuration, and compile it as usual. This gives a large blurb of
- a binary, due to the debugging information. Copy this kernel to the
+ configuration, and compile it as usual. This gives a large blurb of
+ a binary, due to the debugging information. Copy this kernel to the
target machine, strip the debugging symbols off with <command>strip
-x</command>, and boot it using the <option>-d</option> boot
- option. Connect the first serial line of the target machine to any
- serial line of the debugging host. Now, on the debugging machine,
+ option. Connect the first serial line of the target machine to any
+ serial line of the debugging host. Now, on the debugging machine,
go to the compile directory of the target kernel, and start gdb:</para>
@@ -589,8 +589,8 @@ Stopped at Debugger+0x35: movb $0, edata+0x51bc
<para>Every time you type <command>gdb</command>, the mode will be toggled between
- remote GDB and local DDB. In order to force a next trap
- immediately, simply type <command>s</command> (step). Your hosting GDB will now
+ remote GDB and local DDB. In order to force a next trap
+ immediately, simply type <command>s</command> (step). Your hosting GDB will now
gain control over the target kernel:</para>
@@ -605,7 +605,7 @@ Debugger (msg=0xf01b0383 "Boot flags requested debugger")
an Emacs window (which gives you an automatic source code display in
another Emacs window) etc.</para>
- <para>Remote GDB can also be used to debug LKMs. First build the LKM
+ <para>Remote GDB can also be used to debug LKMs. First build the LKM
with debugging symbols:</para>
@@ -625,8 +625,8 @@ EXEC 0 4 f5109000 001c f510f010 1 linux_mod</screen>
<para>Take the load address of the module and add 0x20 (probably to
- account for the a.out header). This is the address that the module
- code was relocated to. Use the <command>add-symbol-file</command> command in GDB to tell the
+ account for the a.out header). This is the address that the module
+ code was relocated to. Use the <command>add-symbol-file</command> command in GDB to tell the
debugger about the module:</para>
@@ -644,10 +644,10 @@ text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
<title>Debugging a Console Driver</title>
<para>Since you need a console driver to run DDB on, things are more
- complicated if the console driver itself is failing. You might
+ complicated if the console driver itself is failing. You might
remember the use of a serial console (either with modified boot
blocks, or by specifying <option>-h</option> at the <prompt>Boot:</prompt> prompt), and hook up a standard terminal
- onto your first serial port. DDB works on any configured console
+ onto your first serial port. DDB works on any configured console
driver, of course also on a serial console.</para>
</sect1>