.TH KDB 8 "17 January 2002"
.hy 0
.SH NAME
Built-in Kernel Debugger for Linux - v2.1
.SH "Overview"
This document describes the built-in kernel debugger available
for linux.   This debugger allows the programmer to interactively
examine kernel memory, disassemble kernel functions, set breakpoints
in the kernel code and display and modify register contents. 
.P
A symbol table is included in the kernel image and in modules which
enables all non-stack symbols (including static symbols) to be used as
arguments to the kernel debugger commands.
.SH "Getting Started"
To include the kernel debugger in a linux kernel, use a
configuration mechanism (e.g. xconfig, menuconfig, et. al.)
to enable the \fBCONFIG_KDB\fP option.   Additionally, for accurate
stack tracebacks, it is recommended that the \fBCONFIG_FRAME_POINTER\fP
option be enabled (if present).   \fBCONFIG_FRAME_POINTER\fP changes the compiler
flags so that the frame pointer register will be used as a frame
pointer rather than a general purpose register.   
.P
After linux has been configured to include the kernel debugger, 
make a new kernel with the new configuration file (a make clean
is recommended before making the kernel), and install the kernel
as normal.
.P
You can compile a kernel with kdb support but have kdb off by default,
select \fBCONFIG_KDB_OFF\fR.  Then the user has to explicitly activate
kdb by booting with the 'kdb=on' flag or, after /proc is mounted, by
.nf
  echo "1" > /proc/sys/kernel/kdb
.fi
You can also do the reverse, compile a kernel with kdb on and
deactivate kdb with the boot flag 'kdb=off' or, after /proc is mounted,
by
.nf
  echo "0" > /proc/sys/kernel/kdb
.fi
.P
When booting the new kernel, the 'kdb=early' flag
may be added after the image name on the boot line to
force the kernel to stop in the kernel debugger early in the 
kernel initialization process.  'kdb=early' implies 'kdb=on'.
If the 'kdb=early' flag isn't provided, then kdb will automatically be
invoked upon system panic or when the \fBPAUSE\fP key is used from the
keyboard, assuming that kdb is on.  Older versions of kdb used just a
boot flag of 'kdb' to activate kdb early, this is still supported but
is deprecated.
.P
Kdb can also be used via the serial port.  Set up the system to 
have a serial console (see \fIDocumentation/serial-console.txt\fP).
The \fBControl-A\fP key sequence on the serial port will cause the
kernel debugger to be entered, assuming that kdb is on.
.P
If you have both a keyboard+video and a serial console, you can use
either for kdb.
Define both video and serial consoles with boot parameters
.P
.nf
  console=tty0 console=ttyS0,38400
.fi
.P
Any kdb data entered on the keyboard or the serial console will be echoed
to both.
.P
While kdb is active, the keyboard (not serial console) indicators may strobe.
The caps lock and scroll lock lights will turn on and off, num lock is not used
because it can confuse laptop keyboards where the numeric keypad is mapped over
the normal keys.
On exit from kdb the keyboard indicators will probably be wrong, they will not match the kernel state.
Pressing caps lock twice should get the indicators back in sync with
the kernel.
.SH "Basic Commands"
There are several categories of commands available to the
kernel debugger user including commands providing memory
display and modification, register display and modification,
instruction disassemble, breakpoints and stack tracebacks.
.P
The following table shows the currently implemented commands:
.DS
.TS
box, center;
l | l
l | l.
Command	Description
_
bc	Clear Breakpoint
bd	Disable Breakpoint
be	Enable Breakpoint
bl	Display breakpoints
bp	Set or Display breakpoint
bph	Set or Display hardware breakpoint
bpa	Set or Display breakpoint globally
bpha	Set or Display hardware breakpoint globally
bt	Stack backtrace for current process
btp	Stack backtrace for specific process
bta	Stack backtrace for all processes
cpu	Display or switch cpus
ef	Print exception frame
env	Show environment
go	Restart execution
help	Display help message
id	Disassemble Instructions
ll	Follow Linked Lists
lsmod	List loaded modules
md	Display memory contents
mdWcN	Display memory contents with width W and count N.
mdr	Display raw memory contents
mds	Display memory contents symbolically
mm	Modify memory contents, words
mmW	Modify memory contents, bytes
reboot	Reboot the machine
rd	Display register contents
rm	Modify register contents
rmmod	Remove a module
sections	List information on all known sections
set	Add/change environment variable
sr	Invoke SysReq commands
ss	Single step a cpu
ssb	Single step a cpu until a branch instruction
.TE
.DE
.P
Some commands can be abbreviated, such commands are indicated by a
non-zero \fIminlen\fP parameter to \fBkdb_register\fP; the value of
\fIminlen\fP being the minimum length to which the command can be
abbreviated (for example, the \fBgo\fP command can be abbreviated
legally to \fBg\fP).
.P
If an input string does not match a command in the command table, 
it is treated as an address expression and the corresponding address
value and nearest symbol are shown.
.P
Some of the commands are described here.
Information on the more complicated commands can be found in the
appropriate manual pages.
.TP 8
cpu
With no parameters, it lists the available cpus, '*' after a cpu number
indicates a cpu that did not respond to the kdb stop signal.
.I cpu
followed by a number will switch to that cpu, you cannot switch to
a cpu marked '*'.
This command is only available if the kernel was configured for SMP.
.TP 8
go
Continue normal execution.
Active breakpoints are reestablished and the processor(s) allowed to
run normally.
To continue at a specific address, use
.I rm
to change the instruction pointer then go.
.TP 8
id
Disassemble instructions starting at an address.
Environment variable IDCOUNT controls how many lines of disassembly
output the command produces.
.TP 8
lsmod
Internal command to list modules.
This does not use any kernel nor user space services so can be used at any time.
.TP 8
reboot
Reboot the system, with no attempt to do a clean close down.
.TP 8
rmmod
Internal command to remove a module.
This does not use any user space services, however it calls the module
cleanup routine and that routine may try to use kernel services.
Because kdb runs disabled there is no guarantee that the module cleanup
routine will succeed, there is a real risk of the routine hanging and
taking kdb with it.
Use the
.I rmmod
command with extreme care.
.TP 8
sections
List information for all known sections.  The output is one line per
module plus the kernel, starting with the module name.  This is
followed by one or more repeats of section name, section start,
section end and section flags.  This data is not designed for human
readability, it is intended to tell external debuggers where each
section has been loaded.
.TP 8
sr
Invoke the SysReq code.
This command takes a single character which is passed to SysReq
processing, as if you had entered the SysReq key sequence followed by
that character.
.SH INITIAL KDB COMMANDS
kdb/kdb_cmds is a plain text file where you can define kdb commands
which are to be issued during kdb_init().  One command per line, blank
lines are ignored, lines starting with '#' are ignored.  kdb_cmds is
intended for per user customization of kdb, you can use it to set
environment variables to suit your hardware or to set standard
breakpoints for the problem you are debugging.  This file is converted
to a small C object, compiled and linked into the kernel.  You must
rebuild and reinstall the kernel after changing kdb_cmds.  This file
will never be shipped with any useful data so you can always override
it with your local copy.  Sample kdb_cmds:
.P
.nf
# Initial commands for kdb, alter to suit your needs.
# These commands are executed in kdb_init() context, no SMP, no
# processes.  Commands that require process data (including stack or
# registers) are not reliable this early.  set and bp commands should
# be safe.  Global breakpoint commands affect each cpu as it is booted.

set LINES=50
set MDCOUNT=25
set RECURSE=1
bp sys_init_module
.fi
.SH INTERRUPTS AND KDB
When a kdb event occurs, one cpu (the initial cpu) enters kdb state.
It uses a cross system interrupt to interrupt the
other cpus and bring them all into kdb state.  All cpus run with
interrupts disabled while they are inside kdb, this prevents most
external events from disturbing the kernel while kdb is running.
.B Note:
Disabled interrupts means that any I/O that relies on interrupts cannot
proceed while kdb is in control, devices can time out.  The clock tick
is also disabled, machines will lose track of time while they are
inside kdb.
.P
Even with interrupts disabled, some non-maskable interrupt events will
still occur, these can disturb the kernel while you are debugging it.  
The initial cpu will still accept NMI events, assuming that kdb was not
entered for an NMI event.  Any cpu where you use the SS or SSB commands
will accept NMI events, even after the instruction has finished and the
cpu is back in kdb.  This is an unavoidable side effect of the fact that
doing SS[B] requires the cpu to drop all the way out of kdb, including
exiting from the event that brought the cpu into kdb.  Under normal
circumstances the only NMI event is for the NMI oopser and that is kdb
aware so it does not disturb the kernel while kdb is running.
.P
Sometimes doing SS or SSB on ix86 will allow one interrupt to proceed,
even though the cpu is disabled for interrupts.  I have not been able
to track this one down but I suspect that the interrupt was pending
when kdb was entered and it runs when kdb exits through IRET even
though the popped flags are marked as cli().  If any ix86 hardware
expert can shed some light on this problem, please notify the kdb
maintainer.
.SH RECOVERING FROM KDB ERRORS
If a kdb command breaks and kdb has enough of a recovery environment
then kdb will abort the command and drop back into mainline kdb code.
This means that user written kdb commands can follow bad pointers
without killing kdb.  Ideally all code should verify that data areas
are valid (using kdb_getarea) before accessing it but lots of calls to
kdb_getarea can be clumsy.
.P
The sparc64 port does not currently provide this error recovery.
If someone would volunteer to write the necessary longjmp/setjmp
code, their efforts would be greatly appreciated. In the
meantime, it is possible for kdb to trigger a panic by accessing
a bad address.
.SH DEBUGGING THE DEBUGGER
kdb has limited support for debugging problems within kdb.  If you
suspect that kdb is failing, you can set environment variable KDBDEBUG
to a bit pattern which will activate kdb_printf statements within kdb.
See include/linux/kdb.h, KDB_DEBUG_FLAG_xxx defines.  For example
.nf
  set KDBDEBUG=0x60
.fi
activates the event callbacks into kdb plus state tracing in sections
of kdb.
.nf
  set KDBDEBUG=0x18
.fi
gives lots of tracing as kdb tries to decode the process stack.
.P
You can also perform one level of recursion in kdb.  If environment
variable RECURSE is not set or is 0 then kdb will either recover from
an error (if the recovery environment is satisfactory) or kdb will
allow the error to percolate, usually resulting in a dead system.  When
RECURSE is 1 then kdb will recover from an error or, if there is no
satisfactory recovery environment, it will drop into kdb state to let
you diagnose the problem.  When RECURSE is 2 then all errors drop into
kdb state, kdb does not attempt recovery first.  Errors while in
recursive state all drop through, kdb does not even attempt to recover
from recursive errors.
.SH WRITING NEW COMMANDS
TBD
.SH AUTHORS
Scott Lurndal, Richard Bass, Scott Foehner, Srinivasa Thirumalachar,
Masahiro Adegawa, Marc Esipovich, Ted Kline, Steve Lord, Andi Kleen.
.br
Keith Owens <kaos@ocs.com.au> - kdb maintainer.
.SH SEE ALSO
.P
linux/Documentation/kdb/kdb_{bp,bt,env,ll,md,rd,ss}.man