Date: Thu, 14 Feb 2002 00:14:14 +0000 From: Ceri <setantae@submonkey.net> To: FreeBSD-gnats-submit@freebsd.org Subject: docs/34921: Developer's Handbook fixes continued: Kernel Debugging chapter Message-ID: <E16b9XS-000BDD-00@rhadamanth.private.submonkey.net>
next in thread | raw e-mail | index | archive | help
>Number: 34921
>Category: docs
>Synopsis: Developer's Handbook fixes continued: Kernel Debugging chapter
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Wed Feb 13 16:20:01 PST 2002
>Closed-Date:
>Last-Modified:
>Originator: Ceri <setantae@submonkey.net>
>Release: FreeBSD 4.5-STABLE i386
>Organization:
>Environment:
System: FreeBSD rhadamanth.private.submonkey.net 4.5-STABLE FreeBSD 4.5-STABLE #0: Tue Feb 12 17:56:57 GMT 2002 setantae@rhadamanth.private.submonkey.net:/usr/obj/usr/src/sys/RHADAMANTH i386
>Description:
- Rework the beginning to remove duplicated information.
- Minor markup fix
- Couple of grammatical/readability improvements
- Mention that ddd is a port
Ceri
>How-To-Repeat:
>Fix:
--- doc/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml.old Wed Feb 13 22:10:39 2002
+++ doc/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml Thu Feb 14 00:04:54 2002
@@ -14,29 +14,24 @@
<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 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 &man.dumpon.8; command. The best way to use
- &man.dumpon.8; is to set the <literal>dumpdev</literal> variable
- in <filename>/etc/rc.conf</filename>. Typically you want to
+ space for a crash dump. 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 <option>-g</option></command>. See
- <ulink url="../handbook/index.html">The FreeBSD
- Handbook</ulink> for details on configuring the FreeBSD
- kernel.</para>
-
- <para>Use the &man.dumpon.8; 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 &man.swapon.8;). 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 deprecated and should be used only if
- you want a crash dump from a kernel that crashes during booting.</para>
+ tapes for example, are currently not supported.</para>
+
+ <note>
+ <para>Use the &man.dumpon.8; 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 &man.swapon.8;). This is normally arranged
+ by setting the <varname>dumpdev</varname> variable in
+ <filename>/etc/rc.conf</filename>.</para>
+
+ <para>Alternatively, you can hard-code the dump device via the
+ <literal>dump</literal> clause in the <literal>config</literal> line of
+ your kernel configuration file. This approach is deprecated and should
+ be used only if you want a crash dump from a kernel that crashes during
+ booting.</para>
+ </note>
<note>
<para>In the following, the term <command>gdb</command> refers to
@@ -211,8 +206,8 @@
<term>line 36:</term>
<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
+ <para>Force usage of a new stack frame; this is no longer necessary.
+ The stack frames are supposed to point to the right
locations now, even in case of a trap.
From looking at the code in source line 403, there is a
high probability that either the pointer access for
@@ -248,7 +243,9 @@
<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 (you will need to install
+ the <port>devel/ddd</port> port in order to use the
+ <command>ddd</command> debugger). Add the <option>-k</option>
option to the <command>ddd</command> command line you would use
normally. For example;</para>
@@ -265,18 +262,18 @@
and it is therefore not compiled using <command>config -g</command>? Not
everything is lost here. Do not panic!</para>
- <para>Of course, you still need to enable crash dumps. See above on the
+ <para>Of course, you still need to enable crash dumps. See above for the
options you have to specify in order to do this.</para>
<para>Go to your kernel config directory
(<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>)
and edit your configuration file. Uncomment (or add, if it does not
- exist) the following line</para>
+ exist) the following line:</para>
<programlisting>makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting>
<para>Rebuild the kernel. Due to the time stamp change on the Makefile,
- there will be some other object files rebuild, for example
+ there some other object files will be rebuilt, for example
<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
@@ -288,7 +285,8 @@
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 symbols, remove
- the appropriate object files and repeat the <command>gdb <option>-k</option></command>
+ the appropriate object files, recompile the kernel again and repeat the
+ <command>gdb <option>-k</option></command>
session until you know enough.</para>
<para>All this is not guaranteed to work, but it will do it fine in most
@@ -304,11 +302,11 @@
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
+ on-line debugger available called DDB. It allows setting of
breakpoints, single-stepping kernel functions, examining and changing
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>gdb</command>.</para>
+ debug information like <command>gdb</command> does.</para>
<para>To configure your kernel to include DDB, add the option line
@@ -316,12 +314,12 @@
to your config file, and rebuild. (See <ulink
url="../handbook/index.html">The FreeBSD Handbook</ulink> for details on
- configuring the FreeBSD kernel.</para>
+ configuring the FreeBSD kernel).</para>
<note>
<para>If you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
- the recent ones load the DDB symbols automagically.)</para>
+ the recent ones load the DDB symbols automagically.</para>
</note>
<para>Once your DDB kernel is running, there are several ways to enter
@@ -335,7 +333,7 @@
this. If you would like to break to the debugger from the
command prompt, simply type the command :</para>
- <screen>&prompt.root; sysctl debug.enter_debugger=ddb</screen>
+ <screen>&prompt.root; <userinput>sysctl debug.enter_debugger=ddb</userinput></screen>
<para>Alternatively, if you are at the system console, you may use
a hot-key on the keyboard. The default break-to-debugger
@@ -347,7 +345,7 @@
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 not the default since there are a lot
- of crappy serial adapters around that gratuitously generate a BREAK
+ of 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
@@ -379,7 +377,7 @@
<note>
<para>Note that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
- for you.</para>
+ to you.</para>
</note>
<para>If you want to remove a breakpoint, use</para>
@@ -487,7 +485,7 @@
<screen><userinput>call cpu_reset()</userinput></screen>
- <para>is the final way out of disaster and almost the same as hitting the
+ <para>This is the final way out of disaster and almost the same as hitting the
Big Red Button.</para>
<para>If you need a short command summary, simply type:</para>
@@ -517,7 +515,7 @@
<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
+ compile it as usual. This gives a large 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 serial line
@@ -563,7 +561,7 @@
<para>You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
- window) etc.</para>
+ window), etc.</para>
</sect1>
<sect1>
@@ -633,7 +631,7 @@
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 driver, of course also on a serial
+ on any configured console driver, including a serial
console.</para>
</sect1>
</chapter>
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?E16b9XS-000BDD-00>