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 panics.
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
.
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
-
+++++
(five plus signs)
<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
-
+++++
(five plus signs)
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.
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:
- Xo
-
!
address
[(expression [,...] )]
A synonym for
call.
- Xo
-
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 breakpoint at the low-level code paths may also cause
strange behavior.
- Xo
-
bt[/ul]
[frame-address]
[,count]
A synonym for
trace.
- Xo
-
bt/t[/ul]
[pid]
[,count]
A synonym for
trace/t.
- Xo
-
bt/a[/ul]
[lwpaddr]
[,count]
A synonym for
trace/a.
- Xo
-
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.
- Xo
-
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
`#'.
- Xo
-
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.
- Xo
-
dwatch
address
Delete the watchpoint at
address
that was previously set with
watch
command.
- Xo
-
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.,
`\000').
- s
-
display the NUL terminated string at the location.
Non-printing characters are displayed as octal escapes.
- m
-
display in unsigned hex with a character dump at the end of each line.
The location is displayed as hex at the beginning of each line.
- i
-
display as a machine instruction.
- I
-
display as a machine instruction, with possible alternative formats
depending upon the machine:
- alpha
-
print register operands
- m68k
-
use Motorola syntax
- vax
-
don't assume that each external label is a procedure entry mask
- Xo
-
kill
pid[,signal_number]
Send a signal to the process specified by the
pid.
Note that
pid
is interpreted using the current radix (see
trace/t
command for details).
If
signal_number
isn't specified, the SIGTERM signal is sent.
- match[/p]
-
A synonym for
next.
- next[/p]
-
Stop at the matching return instruction.
If
/p
is specified, print the call nesting depth and the
cumulative instruction count at each call or return.
Otherwise, only print when the matching return is hit.
- Xo
-
print[/axzodurc]
address[ address ...]
Print addresses
address
according to the modifier character, as per
examine.
Valid modifiers are:
/a,
/x,
/z,
/o,
/d,
/u,
/r,
and
/c
(as per
examine).
If no modifier is specified, the most recent one specified is used.
address
may be a string, and is printed
``as-is''.
For example:
-
print/x "eax = " $eax "\necx = " $ecx "\n"
will produce:
-
eax = xxxxxx
ecx = yyyyyy
- Xo
-
ps
[/a]
[/n]
[/w]
[/l]
A synonym for
show all procs.
- reboot[ flags]
-
Reboot, using the optionally supplied boot
flags,
which is a bitmask supporting the same values as for
reboot(2).
Some of the more useful flags:
Value | Name | Description
|
0x1 | RB_ASKNAME | Ask for file name to reboot from
|
0x2 | RB_SINGLE | Reboot to single user mode
|
0x4 | RB_NOSYNC | Don't sync before reboot
|
0x8 | RB_HALT | Halt instead of reboot
|
0x40 | RB_KDB | Boot into kernel debugger
|
0x100 | RB_DUMP | Dump unconditionally before reboot
|
0x808 | RB_POWERDOWN | Power off (or at least halt)
|
Note: Limitations of the command line interface preclude
specification of a boot string.
- Xo
-
search[/bhl]
address
value
[mask]
[,count]
Search memory from
address
for
value.
The unit size is specified with a modifier character, as per
examine.
Valid modifiers are:
/b,
/h,
and
/l.
If no modifier is specified,
/l
is used.
This command might fail in interesting ways if it doesn't find
value.
This is because
ddb
doesn't always recover from touching bad memory.
The optional
count
limits the search.
- Xo
-
set
$variable
[=]
expression
Set the named variable or register to the value of
expression.
Valid variable names are described in
VARIABLES.
- show all callout
-
Display information about callouts in the system.
See
callout(9)
for more information on callouts.
- show all pages
-
Display basic information about all physical pages managed by the VM system.
For more detailed information about a single page, use
show page.
- show all pools[/clp]
-
Display all pool information.
Modifiers are the same as
show pool.
- Xo
-
show all procs
[/a]
[/n]
[/w]
[/l]
Display all process information.
Valid modifiers:
- /n
-
show process information in a
ps(1)
style format.
Information printed includes: process ID, parent process ID,
process group, UID, process status, process flags, process
command name, and process wait channel message.
- /a
-
show the kernel virtual addresses of each process'
proc structure, u-area, and vmspace structure.
The vmspace address is also the address of the process'
vm_map structure, and can be used in the
show map
command.
- /w
-
show each process' PID, command, system call emulation, wait channel
address, and wait channel message.
- /l
-
show each process' associated LWP information, including each LWP's
LID, flags, kernel LWP structure address, u-area, and wait channel.
This is the default.
- show arptab
-
Dump the entire
AF_INET
routing table.
This command is available only on systems which support inet and ARP.
- show breaks
-
Display all breakpoints.
- Xo
-
show buf[/f]
address
Print the struct buf at
address.
The
/f
does nothing at this time.
- Xo
-
show event[/f]
Print all the non-zero
evcnt(9)
event counters.
If
/f
is specified, all event counters with a count of zero are printed as well.
- Xo
-
show files
address
Display information about the vnodes of the files that are currently
open by the process associated with the proc structure at
address.
This address can be found using the
show all procs /a
command.
If the kernel is compiled with
options LOCKDEBUG
then details about the locking of the underlying uvm object will also
be displayed.
- Xo
-
show lock
address
Display information about a lock at
address.
This command is useful only if a kernel is compiled with
options LOCKDEBUG.
- Xo
-
show malloc
address
If
address
is supplied, display the kernel memory allocator's idea on the
allocation status for it.
Also, print out global statistics for the memory allocator.
This command is useful only if a kernel is compiled with
options MALLOC_DEBUG.
- Xo
-
show map[/f]
address
Print the vm_map at
address.
If
/f
is specified, the complete map is printed.
- Xo
-
show mount[/f]
address
Print the mount structure at
address.
If
/f
is specified, the complete vnode list is printed.
- Xo
-
show mbuf[/c]
address
Print the mbuf structure at
address.
If
/c
is specified, the mbufs in the chain are followed.
- show ncache address
-
Dump the namecache list associated with vnode at
address.
- Xo
-
show object[/f]
address
Print the vm_object at
address.
If
/f
is specified, the complete object is printed.
- Xo
-
show page[/f]
address
Print the vm_page at
address.
If
/f
is specified, the complete page is printed.
- Xo
-
show pool[/clp]
address
Print the pool at
address.
Valid modifiers:
- /c
-
Print the cachelist and its statistics for this pool.
- /l
-
Print the log entries for this pool.
- /p
-
Print the pagelist for this pool.
- show registers[/u]
-
Display the register set.
If
/u
is specified, display user registers instead of kernel registers
or the currently save one.
Warning: support for
/u
is machine dependent.
If not supported, incorrect information will be displayed.
- show sched_qs
-
Print the state of the scheduler's run queues.
For each run queue that has an LWP, the run queue index and the list
of LWPs will be shown.
If the run queue has LWPs, but the sched_whichqs bit is not set for that
queue, the queue index will be prefixed with a
`!'.
- show uvmexp
-
Print a selection of UVM counters and statistics.
- Xo
-
uvmhist
Dumps the UVM histories.
This command is available only if a kernel is compiled with
options UVMHIST.
- Xo
-
show vnode[/f]
address
Print the vnode at
address.
If
/f
is specified, the complete vnode is printed.
- show watches
-
Display all watchpoints.
- Xo
-
sifting[/F]
string
Search the symbol tables for all symbols of which
string
is a substring, and display them.
If
/F
is specified, a character is displayed immediately after each symbol
name indicating the type of symbol.
For
a.out(5)-format
symbol tables,
absolute symbols display
@,
text segment symbols display
*,
data segment symbols display
+,
BSS
segment symbols display
-,
and filename symbols display
/.
For
ELF-format
symbol tables,
object symbols display
+,
function symbols display
*,
section symbols display
&,
and file symbols display
/.
To sift for a string beginning with a number, escape the first
character with a backslash as:
-
sifting \386
- Xo
-
step[/p]
[,count]
Single-step
count
times.
If
/p
is specified, print each instruction at each step.
Otherwise, only print the last instruction.
Warning: depending on the machine type, it may not be possible
to single-step through some low-level code paths or user-space
code.
On machines with software-emulated single-stepping (e.g., pmax),
stepping through code executed by interrupt handlers will probably
do the wrong thing.
- sync
-
Force a crash dump, and then reboot.
- Xo
-
trace[/u[l]]
[frame-address]
[,count]
Stack trace from
frame-address.
If
/u
is specified, trace user-space, otherwise trace kernel-space.
count
is the number of frames to be traced.
If
count
is omitted, all frames are printed.
If
/l
is specified, the trace is printed and also stored in the kernel
message buffer.
Warning: user-space stack trace is valid only if the machine dependent
code supports it.
- Xo
-
trace/t[l]
[pid]
[,count]
Stack trace by
``thread''
(process, on
NetBSD)
rather than by stack frame address.
Note that
pid
is interpreted using the current radix, whilst
ps
displays pids in decimal; prefix
pid
with
`0t'
to force it to be interpreted as decimal (see
VARIABLES
section for radix).
If
/l
is specified, the trace is printed and also stored in the kernel
message buffer.
Warning: trace by pid is valid only if the machine dependent code
supports it.
- Xo
-
trace/a[l]
[lwpaddr]
[,count]
Stack trace by light weight process (LWP) address
rather than by stack frame address.
If
/l
is specified, the trace is printed and also stored in the kernel
message buffer.
Warning: trace by LWP address is valid only if the machine dependent
code supports it.
- until[/p]
-
Stop at the next call or return instruction.
If
/p
is specified, print the call nesting depth and the
cumulative instruction count at each call or return.
Otherwise, only print when the matching return is hit.
- Xo
-
watch
address
[,size]
Set a watchpoint for a region.
Execution stops when an attempt to modify the region occurs.
size
defaults to 4.
If you specify a wrong space address, the request is
rejected with an error message.
Warning: attempts to watch wired kernel memory may cause
an unrecoverable error in some systems such as i386.
Watchpoints on user addresses work the best.
- Xo
-
whatis
address
Describe what an address is.
- Xo
-
write[/bhl]
address
expression[ expression ...]
Write the
expressions
at succeeding locations.
The unit size is specified with a modifier character, as per
examine.
Valid modifiers are:
/b,
/h,
and
/l.
If no modifier is specified,
/l
is used.
Warning: since there is no delimiter between
expressions,
strange things may occur.
It's best to enclose each
expression
in parentheses.
- Xo
-
x[/modifier]
address[,count]
A synonym for
examine.
MACHINE-SPECIFIC COMMANDS
The "glue" code that hooks
ddb
into the
NetBSD
kernel for any given port can also add machine specific commands
to the
ddb
command parser.
All of these commands are preceded by the command word
machine
to indicate that they are part of the machine-specific command
set (e.g.
machine reboot).
Some of these commands are:
ALPHA
- halt
-
Call the PROM monitor to halt the CPU.
- reboot
-
Call the PROM monitor to reboot the CPU.
ARM32
- panic
-
Print the current "panic" string.
- frame
-
Given a trap frame address, print out the trap frame.
MIPS
- cp0
-
Dump CP0 (coprocessor 0) register values.
- kvtop
-
Print the physical address for a given kernel virtual address.
- tlb
-
Print out the Translation Lookaside Buffer (TLB).
Only works in
NetBSD
kernels compiled with
DEBUG
option.
SH3
- tlb
-
Print TLB entries
- cache
-
Print cache entries
- frame
-
Print switch frame and trap frames.
- stack
-
Print kernel stack usage.
Only works in
NetBSD
kernels compiled with the
KSTACK_DEBUG
option.
SPARC
- prom
-
Exit to the Sun PROM monitor.
SPARC64
- ctx
-
Print process context information.
- cpu
-
Switch to another cpu.
- dtlb
-
Print data translation look-aside buffer context information.
- dtsb
-
Display data translation storage buffer information.
- kmap
-
Display information about the listed mapping in the kernel pmap.
Use the
``f''
modifier to get a full listing.
- extract
-
Extract the physical address for a given virtual address from the kernel pmap.
- fpstate
-
Dump the FPU state.
- itlb
-
Print instruction translation look-aside buffer context information.
- itsb
-
Display instruction translation storage buffer information.
- lwp
-
Display a struct lwp
- pcb
-
Display information about the
``struct pcb''
listed.
- pctx
-
Attempt to change process context.
- page
-
Display the pointer to the
``struct vm_page''
for this physical address.
- phys
-
Display physical memory.
- pmap
-
Display the pmap.
Use the
``f''
modifier to get a fuller listing.
- proc
-
Display some information about the process pointed to, or curproc.
- prom
-
Enter the OFW PROM.
- pv
-
Display the
``struct pv_entry''
pointed to.
- sir
-
Reset the machine and enter prom (do a Software Initiated Reset).
- stack
-
Dump the window stack.
Use the
``u''
modifier to get userland information.
- tf
-
Display full trap frame state.
This is most useful for inclusion with bug reports.
- ts
-
Display trap state.
- traptrace
-
Display or set trap trace information.
Use the
``r''
and
``f''
modifiers to get reversed and full information, respectively.
- watch
-
Set or clear a physical or virtual hardware watchpoint.
Pass the address to be watched, or
``0''
(or omit the address) to clear the watchpoint.
Optional modifiers are
``p''
for physical address,
``r''
for trap on read access (default: trap on write access only),
``b''
for 8 bit width,
``h''
for 16 bit,
``l''
for 32 bit or
``L''
for 64 bit.
- window
-
Print register window information. Argument is a stack frame number (0 is
top of stack, which is used when no index is given).
SUN3 and SUN3X
- abort
-
Drop into monitor via abort (allows continue).
- halt
-
Exit to Sun PROM monitor as in
halt(8).
- reboot
-
Reboot the machine as in
reboot(8).
- pgmap
-
Given an address, print the address, segment map, page map, and
Page Table Entry (PTE).
VARIABLES
ddb
accesses registers and variables as
$name.
Register names are as per the
show registers
command.
Some variables are suffixed with numbers, and may have a modifier
following a colon immediately after the variable name.
For example, register variables may have a
`u'
modifier to indicate user register
(e.g.,
$eax:u
).
Built-in variables currently supported are:
- lines
-
The number of lines.
This is used by the
more
feature.
When this variable is set to zero the
more
feature is disabled.
- maxoff
-
Addresses are printed as
'symbol'+offset
unless
offset
is greater than
maxoff.
- maxwidth
-
The width of the displayed line.
ddb
wraps the current line by printing new line when
maxwidth
column is reached.
When this variable is set to zero
ddb
doesn't perform any wrapping.
- onpanic
-
If non-zero (the default),
ddb
will be invoked when the kernel panics.
If the kernel configuration option
options DDB_ONPANIC=0
is used,
onpanic
will be initialized to off.
- fromconsole
-
If non-zero (the default),
the kernel allows to enter
ddb
from the console (by break signal or special key sequence).
If the kernel configuration option
options DDB_FROMCONSOLE=0
is used,
fromconsole
will be initialized to off.
- radix
-
Input and output radix.
- tabstops
-
Tab stop width.
- tee_msgbuf
-
If explicitly set to non zero (zero is the default) all
ddb
output will not only be displayed on screen but
also be fed to the msgbuf.
The default of the variable can be set using the kernel configuration option
options DDB_TEE_MSGBUF=1
which will initialize
tee_msgbuf
to be 1.
This option is especially handy for poor souls
who don't have a serial console but want to recall
ddb
output from a crash investigation.
This option is more generic than the /l command modifier possible for
selected commands as discussed above to log the output.
Mixing both /l
and this setting can give double loggings.
All built-in variables are accessible via
sysctl(3).
EXPRESSIONS
Almost all expression operators in C are supported, except
`~',
`^',
and unary
`&'.
Special rules in
ddb
are:
- identifier
-
name of a symbol.
It is translated to the address (or value) of it.
`.'
and
`:'
can be used in the identifier.
If supported by an object format dependent routine,
filename[.blm Pp:]
function
:line number[.blm Pp,]
filename[.blm Pp:]
variable,
and
filename
:line number[.blm Pp,]
can be accepted as a symbol.
The symbol may be prefixed with
symbol_table_name::
(e.g.,
emulator::mach_msg_trap
)
to specify other than kernel symbols.
- number
-
number.
Radix is determined by the first two characters:
`0x'
- hex,
`0o'
- octal,
`0t'
- decimal,
otherwise follow current radix.
- .
dot
- +
-
next
- ..
-
address of the start of the last line examined.
Unlike
dot
or
next,
this is only changed by the
examine
or
write
commands.
- "
-
last address explicitly specified.
- $name
-
register name or variable.
It is translated to the value of it.
It may be followed by a
`:'
and modifiers as described above.
- #
-
a binary operator which rounds up the left hand side to the next
multiple of right hand side.
- *expr
-
expression indirection.
It may be followed by a
`:'
and modifiers as described above.
SEE ALSO
reboot(2),
options(4),
reboot(8),
sysctl(8),
cnmagic(9)
HISTORY
The
ddb
kernel debugger was written as part of the MACH project at
Carnegie-Mellon University.