DDB(4) BSD Kernel Interfaces Manual DDB(4)
NAME
ddb -- in-kernel debugger
SYNOPSIS
options DDB
To enable history editing:
options DDB_HISTORY_SIZE=integer
To disable entering ddb upon kernel panic:
options DDB_ONPANIC=0
To enable teeing all ddb output to the kernel msgbuf:
options DDB_TEE_MSGBUF=1
To specify commands which will be executed on each entry to ddb:
options DDB_COMMANDONENTER="trace;show registers"
In this case, "trace" and then "show registers" will be executed automatically.
To enable extended online help:
options DDB_VERBOSE_HELP.
DESCRIPTION
ddb is the in-kernel debugger. It may be entered at any time via a special key sequence, and optionally may be invoked when the kernel pan-
ics.
ENTERING THE DEBUGGER
Unless DDB_ONPANIC is set to 0, ddb will be activated whenever the kernel would otherwise panic.
ddb may also be activated from the console. In general, sending a break on a serial console will activate ddb. There are also key sequences
for each port that will activate ddb from the keyboard:
alpha <Ctrl>-<Alt>-<Esc> on PC style keyboards.
amd64 <Ctrl>-<Alt>-<Esc>
<Break> on serial console.
amiga <LAlt>-<LAmiga>-<F10>
atari <Alt>-<LeftShift>-<F9>
hp300 <Shift>-<Reset>
hp700 <Ctrl>-<Alt>-<Esc> on PC style keyboards.
+++++ (five plus signs) on PDC console
<Break> on serial console.
hpcarm <Ctrl>-<Alt>-<Esc>
hpcmips <Ctrl>-<Alt>-<Esc>
hpcsh <Ctrl>-<Alt>-<Esc>
i386 <Ctrl>-<Alt>-<Esc>
<Break> on serial console.
mac68k <Command>-<Power>, or the Interrupt switch.
macppc Some models: <Command>-<Option>-<Power>
mvme68k Abort switch on CPU card.
pmax <Do> on LK-201 rcons console.
<Break> on serial console.
sparc <L1>-A, or <Stop>-A on a Sun keyboard.
<Break> on serial console.
sparc64 <L1>-A, or <Stop>-A on a Sun keyboard.
<Break> on serial console.
sun3 <L1>-A, or <Stop>-A on a Sun keyboard.
<Break> on serial console.
vax <Esc>-<Shift>-D on serial console.
x68k Interrupt switch on the body.
xen dom0 <Ctrl>-<Alt>-<Esc> on PC style keyboards.
+++++ (five plus signs) on serial console.
xen domU +++++ (five plus signs) on serial console.
zaurus <Ctrl>-<Alt>-<Esc>
The key sequence to activate ddb can be changed by modifying ``hw.cnmagic'' with sysctl(8). If the console is not dedicated to ddb the
sequence should not be easily typed by accident. In addition, ddb may be explicitly activated by the debugging code in the kernel if DDB is
configured.
Commands can be automatically run when ddb is entered by using options DDB_COMMANDONENTER or by setting ddb.commandonenter with sysctl(8).
Multiple commands can be separated by a semi-colon.
COMMAND SYNTAX
The general command syntax is:
command[/modifier] address [,count]
The current memory location being edited is referred to as dot, and the next location is next. They are displayed as hexadecimal numbers.
Commands that examine and/or modify memory update dot to the address of the last line examined or the last location modified, and set next to
the next location to be examined or modified. Other commands don't change dot, and set next to be the same as dot.
A blank line repeats the previous command from the address next with the previous count and no modifiers. Specifying address sets dot to the
address. If address is omitted, dot is used. A missing count is taken to be 1 for printing commands, and infinity for stack traces.
The syntax:
,count
repeats the previous command, just as a blank line does, but with the specified count.
ddb has a more(1)-like functionality; if a number of lines in a command's output exceeds the number defined in the lines variable, then ddb
displays ``--db more--'' and waits for a response, which may be one of:
<return> one more line.
<space> one more page.
q abort the current command, and return to the command input mode.
You can set lines variable to zero to disable this feature.
If ddb history editing is enabled (by defining the
options DDB_HISTORY_SIZE=num
kernel option), then a history of the last num commands is kept. The history can be manipulated with the following key sequences:
<Ctrl>-P retrieve previous command in history (if any).
<Ctrl>-N retrieve next command in history (if any).
COMMANDS
ddb supports the following commands:
!address[(expression[,...])]
A synonym for call.
break[/u] address[,count]
Set a breakpoint at address. If count is supplied, continues (count-1) times before stopping at the breakpoint. If the breakpoint is
set, a breakpoint number is printed with '#'. This number can be used to delete the breakpoint, or to add conditions to it.
If /u is specified, set a breakpoint at a user-space address. Without /u, address is considered to be in the kernel-space, and an
address in the wrong space will be rejected, and an error message will be emitted. This modifier may only be used if it is supported
by machine dependent routines.
Warning: if a user text is shadowed by a normal user-space debugger, user-space breakpoints may not work correctly. Setting a break-
point at the low-level code paths may also cause strange behavior.
bt[/ul] [frame-address][,count]
A synonym for trace.
bt/t[/ul] [pid][,count]
A synonym for trace/t.
bt/a[/ul] [lwpaddr][,count]
A synonym for trace/a.
call address[(expression[,...])]
Call the function specified by address with the argument(s) listed in parentheses. Parentheses may be omitted if the function takes
no arguments. The number of arguments is currently limited to 10.
continue[/c]
Continue execution until a breakpoint or watchpoint. If /c is specified, count instructions while executing. Some machines (e.g.,
pmax) also count loads and stores.
Warning: when counting, the debugger is really silently single-stepping. This means that single-stepping on low-level may cause
strange behavior.
delete address | #number
Delete a breakpoint. The target breakpoint may be specified by address, as per break, or by the breakpoint number returned by break
if it's prefixed with '#'.
dmesg [count]
Prints the contents of the kernel message buffer. The optional count argument will limit printing to at most the last count bytes of
the message buffer.
dwatch address
Delete the watchpoint at address that was previously set with watch command.
examine[/modifier] address[,count]
Display the address locations according to the format in modifier. Multiple modifier formats display multiple locations. If modifier
isn't specified, the modifier from the last use of examine is used.
The valid format characters for modifier are:
b examine bytes (8 bits).
h examine half-words (16 bits).
l examine words (legacy ``long'', 32 bits).
L examine long words (implementation dependent)
a print the location being examined.
A print the location with a line number if possible.
x display in unsigned hex.
z display in signed hex.
o display in unsigned octal.
d display in signed decimal.
u display in unsigned decimal.
r display in current radix, signed.
c display low 8 bits as a character. Non-printing characters as displayed as an octal escape code (e.g., '