Add a glossary of compile-time kernel debugging options.
This commit is contained in:
Robert Watson
parent
498d5c3f93
commit
06360975af
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=29309
1 changed files with 173 additions and 0 deletions
|
|
@ -16,6 +16,10 @@
|
|||
<firstname>Jörg</firstname>
|
||||
<surname>Wunsch</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Robert</firstname>
|
||||
<surname>Watson</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
|
||||
|
|
@ -867,6 +871,175 @@ Reading symbols from /sys/modules/linux/linux.ko...done.
|
|||
<command>thread thread-id</command> to switch to the thread
|
||||
stack, and do a backtrace with <command>where</command>.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kerneldebug-options">
|
||||
<title>Glossary of Kernel Options for Debugging</title>
|
||||
|
||||
<para>This section provides a brief glossary of compile-time kernel
|
||||
options used for debugging:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>options KDB</literal>: compiles in the kernel
|
||||
debugger framework. Required for <literal>options DDB</literal>
|
||||
and <literal>options GDB</literal>. Little or no performance
|
||||
overhead. By default, the debugger will be entered on panic
|
||||
instead of an automatic reboot.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options KDB_UNATTENDED</literal>: change the default
|
||||
value of the <literal>debug.debugger_on_panic</literal> sysctl to
|
||||
0, which controls whether the debugger is entered on panic. When
|
||||
<literal>options KDB</literal> is not compiled into the kernel, the
|
||||
behavior is to automatically reboot on panic; when it is compiled
|
||||
into the kernel, the default behavior is to drop into the debugger
|
||||
unless <literal>options KDB_UNATTENDED</literal> is compiled in.
|
||||
If you want to leave the kernel debugger compiled into the kernel
|
||||
but want the system to come back up unless you're on-hand to use
|
||||
the debugger for diagnostics, use this option.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options KDB_TRACE</literal>: change the default value
|
||||
of the <literal>debug.trace_on_panic</literal> sysctl to 1, which
|
||||
controls whether the debugger automatically prints a stack trace
|
||||
on panic. Especially if running with <literal>options
|
||||
KDB_UNATTENDED</literal>, this can be helpful to gather basic
|
||||
debugging information on the serial or firewire console while
|
||||
still rebooting to recover.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options DDB</literal>: compile in support for the
|
||||
console debugger, DDB. This interactive debugger runs on whatever
|
||||
the active low-level console of the system is, which includes the
|
||||
video console, serial console, or firewire console. It provides
|
||||
basic integrated debugging facilities, such as stack tracing,
|
||||
process and thread listing, dumping of lock state, VM state, file
|
||||
system state, and kernel memory management. DDB does not require
|
||||
software running on a second machine or being able to generate a
|
||||
core dump or full debugging kernel symbols, and provides detailed
|
||||
diagnostics of the kernel at run-time. Many bugs can be fully
|
||||
diagnosed using only DDB output. This option depends on
|
||||
<literal>options KDB</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options GDB</literal>: compiler in support for the
|
||||
remote debugger, GDB, which can operate over serial cable or
|
||||
firewire. When the debugger is entered, GDB may be attached to
|
||||
inspect structure contents, generate stack traces, etc. Some
|
||||
kernel state is more awkward to access than in DDB, which is able
|
||||
to generate useful summaries of kernel state automatically, such
|
||||
as automatically walking lock debugging or kernel memory
|
||||
management structures, and a second machine running the debugger
|
||||
is required. On the other hand, GDB combines information from
|
||||
the kernel source and full debugging symbols, and is aware of full
|
||||
data structure definitions, local variables, and is scriptable.
|
||||
This option is not required to run GDB on a kernel core dump.
|
||||
This option depends on <literal>options KDB</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options BREAK_TO_DEBUGGER</literal>, <literal>options
|
||||
ALT_BREAK_TO_DEBUGGER</literal>: allow a break signal or
|
||||
alternative signal on the console to enter the debugger. If the
|
||||
system hangs without a panic, this is a useful way to reach the
|
||||
debugger. Due to the current kernel locking, a break signal
|
||||
generated on a serial console is significantly more reliable at
|
||||
getting into the debugger, and is generally recommended. This
|
||||
option has little or no performance impact.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options INVARIANTS</literal>: compile into the kernel
|
||||
a large number of run-time assertion checks and tests, which
|
||||
constantly test the integrity of kernel data structures and the
|
||||
invariants of kernel algorithms. These tests can be expensive, so
|
||||
are not compiled in by default, but help provide useful "fail stop"
|
||||
behavior, in which certain classes of undesired behavior enter the
|
||||
debugger before kernel data corruption occurs, making them easier
|
||||
to debug. Tests include memory scrubbing and use-after-free
|
||||
testing, which is one of the more significant sources of overhead.
|
||||
This option depends on <literal>options INVARIANT_SUPPORT</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options INVARIANT_SUPPORT</literal>: many of the tests
|
||||
present in <literal>options INVARIANTS</literal> require modified
|
||||
data structures or additional kernel symbols to be defined.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options WITNESS</literal>: this option enables run-time
|
||||
lock order tracking and verification, and is an invaluable tool for
|
||||
deadlock diagnosis. WITNESS maintains a graph of acquires lock
|
||||
orders by lock type, and checks the graph at each acquire for
|
||||
cycles (implicit or explicit). If a cycle is detected, a warning
|
||||
and stack trace are generated to the console, indicating that a
|
||||
potential deadlock might have occurred. WITNESS is required in
|
||||
order to use the <command>show locks</command>, <command>show
|
||||
witness</command> and <command>show all locks</command> DDB
|
||||
commands. This debug option has significant performance overhead,
|
||||
which may be somewhat mitigated through the use of <literal>options
|
||||
WITNESS_SKIPSPIN</literal>. Detailed documentation may be found in
|
||||
&man.witness.4;.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options WITNESS_SKIPSIN</literal>: disable run-time
|
||||
checking of spinlock lock order with WITNESS. As spin locks are
|
||||
acquired most frequently in the scheduler, and scheduler events
|
||||
occur often, this option can significantly speed up systems
|
||||
running with WITNESS. This option depends on <literal>options
|
||||
WITNESS</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options WITNESS_KDB</literal>: change the default
|
||||
value of the <literal>debug.witness.kdb</literal> sysctl to 1,
|
||||
which causes WITNESS to enter the debugger when a lock order
|
||||
violation is detected, rather than simply printing a warning. This
|
||||
option depends on <literal>options WITNESS</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options SOCKBUF_DEBUG</literal>: perform extensive
|
||||
run-time consistency checking on socket buffers, which can be
|
||||
useful for debugging both socket bugs and race conditions in
|
||||
protocols and device drivers that interact with sockets. This
|
||||
option significantly impacts network performance, and may change
|
||||
the timing in device driver races.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options DEBUG_VFS_LOCKS</literal>: track lock
|
||||
acquisition points for lockmgr/vnode locks, expanding the amount
|
||||
of information displayed by <command>show lockedvnods</command>
|
||||
in DDB. This option has a measurable performance impact.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options DEBUG_MEMGUARD</literal>: a replacement for
|
||||
the &man.malloc.9; kernel memory allocator that uses the VM system
|
||||
to detect reads or writes from allocated memory after free.
|
||||
Details may be found in &man.memguard.9;. This option has a
|
||||
significant performance impact, but can be very helpful in
|
||||
debugging kernel memory corruption bugs.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>options DIAGNOSTIC</literal>: enable additional, more
|
||||
expensive diagnostic tests along the lines of <literal>options
|
||||
INVARIANTS</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
|
||||
<!--
|
||||
|
|
|
|||
Loading…
Reference in a new issue