387 lines
12 KiB
Groff
387 lines
12 KiB
Groff
.\" -*- nroff -*-
|
|
.\"
|
|
.\" $NetBSD: ddb.4,v 1.10 1997/03/11 16:58:55 sommerfe Exp $
|
|
.\"
|
|
.\" Mach Operating System
|
|
.\" Copyright (c) 1991,1990 Carnegie Mellon University
|
|
.\" All Rights Reserved.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this software and its
|
|
.\" documentation is hereby granted, provided that both the copyright
|
|
.\" notice and this permission notice appear in all copies of the
|
|
.\" software, derivative works or modified versions, and any portions
|
|
.\" thereof, and that both notices appear in supporting documentation.
|
|
.\"
|
|
.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
|
|
.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
|
|
.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" Carnegie Mellon requests users of this software to return to
|
|
.\"
|
|
.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
|
|
.\" School of Computer Science
|
|
.\" Carnegie Mellon University
|
|
.\" Pittsburgh PA 15213-3890
|
|
.\"
|
|
.\" any improvements or extensions that they make and grant Carnegie Mellon
|
|
.\" the rights to redistribute these changes.
|
|
.\"
|
|
.TH DDB 4
|
|
.SH NAME
|
|
ddb \- kernel debugger
|
|
.de XX
|
|
.sp
|
|
.ti -4n
|
|
\\$1
|
|
.br
|
|
.sp
|
|
..
|
|
.de XS
|
|
.nr )R +\\$1
|
|
..
|
|
.de XE
|
|
.nr )R -\\$1
|
|
..
|
|
.SH SYNOPSIS
|
|
.B "options DDB"
|
|
.SH DESCRIPTION
|
|
.br
|
|
.sp
|
|
The kernel debugger has most of the features of the old kdb,
|
|
but with a more rational (gdb-like) syntax.
|
|
.sp
|
|
The current location is called 'dot'. The 'dot' is displayed with
|
|
a hexadecimal format at a prompt.
|
|
Examine and write commands update 'dot' to the address of the last line
|
|
examined or the last location modified, and set 'next' to the address of
|
|
the next location to be examined or changed.
|
|
Other commands don't change 'dot', and set 'next' to be the same as 'dot'.
|
|
.sp
|
|
The general command syntax is:
|
|
.sp
|
|
.ti +4n
|
|
\fIcommand[/modifier] address [,count]\fR
|
|
.sp
|
|
A blank line repeats from the address 'next' with count 1 and no modifiers.
|
|
Specifying 'address' sets 'dot' to the address.
|
|
Omitting 'address' uses 'dot'.
|
|
A missing 'count' is taken to be 1 for printing commands or infinity
|
|
for stack traces.
|
|
.sp
|
|
"\fBddb\fR" has a feature like a command "\fBmore\fR"
|
|
for the output. If an output line exceeds the number set in the $lines
|
|
variable, it displays "\fI--db_more--\fR"
|
|
and waits for a response.
|
|
The valid responses for it are:
|
|
.XS 4n
|
|
.IP \fI\<space>\fR 10n
|
|
one more page
|
|
.IP \fI\<return>\fR 10n
|
|
one more line
|
|
.IP \fB\q\fR 10n
|
|
abort the current command, and return to the command input mode.
|
|
.LP
|
|
.sp
|
|
.XE 4n
|
|
.LP
|
|
.B COMMANDS
|
|
.sp
|
|
.XS 4n
|
|
.LP
|
|
.XX "\fBexamine(x) \fI[/<modifier>] <addr>[,<count>]\fR"
|
|
Display the addressed locations according to the formats in the modifier.
|
|
Multiple modifier formats display multiple locations.
|
|
If no format is specified, the last formats specified for this command
|
|
is used.
|
|
.br
|
|
The format characters are
|
|
.sp
|
|
.LP
|
|
.XS 2n
|
|
.IP b 5n
|
|
look at by bytes(8 bits)
|
|
.IP h 5n
|
|
look at by half words(16 bits)
|
|
.IP l 5n
|
|
look at by long words(32 bits)
|
|
.IP a 5n
|
|
print the location being displayed
|
|
.IP A 5n
|
|
print the location with a line number if possible
|
|
.IP x 5n
|
|
display in unsigned hex
|
|
.IP z 5n
|
|
display in signed hex
|
|
.IP o 5n
|
|
display in unsigned octal
|
|
.IP d 5n
|
|
display in signed decimal
|
|
.IP u 5n
|
|
display in unsigned decimal
|
|
.IP r 5n
|
|
display in current radix, signed
|
|
.IP c 5n
|
|
display low 8 bits as a character.
|
|
Non-printing characters are displayed as an octal escape code (e.g. '\\000').
|
|
.IP s 5n
|
|
display the null-terminated string at the location.
|
|
Non-printing characters are displayed as octal escapes.
|
|
.IP m 5n
|
|
display in unsigned hex with character dump at the end of each line.
|
|
The location is also displayed in hex at the beginning of each line.
|
|
.IP i 5n
|
|
display as an instruction
|
|
.IP I 5n
|
|
display as an instruction with possible alternative formats depending on the
|
|
machine:
|
|
.XE 2n
|
|
.LP
|
|
.XS 5n
|
|
.LP
|
|
.IP vax 6n
|
|
don't assume that each external label is a procedure entry mask
|
|
.IP i386 6n
|
|
don't round to the next long word boundary
|
|
.IP mips 6n
|
|
print register contents
|
|
.LP
|
|
.XE 5n
|
|
.LP
|
|
.XX xf
|
|
Examine forward.
|
|
It executes an examine command with the last specified parameters to it
|
|
except that the next address displayed by it is used as the start address.
|
|
.XX xb
|
|
Examine backward.
|
|
It executes an examine command with the last specified parameters to it
|
|
except that the last start address subtracted by the size displayed by it
|
|
is used as the start address.
|
|
.XX "\fBprint[/axzodurc] \fI<addr1> [ <addr2> ... ]\fR"
|
|
Print 'addr's according to the modifier character.
|
|
Valid formats are: a x z o d u r c.
|
|
If no modifier is specified, the last one specified to it is used. 'addr'
|
|
can be a string, and it is printed as it is. For example,
|
|
.br
|
|
.sp
|
|
.ti +4n
|
|
print/x "eax = " $eax "\\necx = " $ecx "\\n"
|
|
.br
|
|
.sp
|
|
will print like
|
|
.sp
|
|
.in +4n
|
|
eax = xxxxxx
|
|
.br
|
|
ecx = yyyyyy
|
|
.in -4n
|
|
.sp
|
|
.br
|
|
.XX "\fBwrite[/bhl] \fI<addr> <expr1> [ <expr2> ... ]\fR"
|
|
Write the expressions at succeeding locations.
|
|
The write unit size can be specified in the modifier with a letter
|
|
b (byte), h (half word) or l(long word) respectively. If omitted,
|
|
long word is assumed.
|
|
.br
|
|
Warning: since there is no delimiter between expressions, strange
|
|
things may happen.
|
|
It's best to enclose each expression in parentheses.
|
|
.XX "\fBset \fI$<variable> [=] <expr>\fR"
|
|
Set the named variable or register with the value of 'expr'.
|
|
Valid variable names are described below.
|
|
.XX "\fBbreak[/u] \fI<addr>[,<count>]\fR"
|
|
Set a break point at 'addr'.
|
|
If count is supplied, continues (count-1) times before stopping at the
|
|
break point. If the break point is set, a break point number is
|
|
printed with '#'. This number can be used in deleting the break point
|
|
or adding conditions to it.
|
|
.LP
|
|
.XS 2n
|
|
.IP u 5n
|
|
Set a break point in user space address. Without 'u' option,
|
|
the address is considered in the kernel space, and wrong space address
|
|
is rejected with an error message.
|
|
This option can be used only if it is supported by machine dependent
|
|
routines.
|
|
.LP
|
|
.XE 2n
|
|
Warning: if a user text is shadowed by a normal user space debugger,
|
|
user space break points may not work correctly. Setting a break
|
|
point at the low-level code paths may also cause strange behavior.
|
|
.XX "\fBdelete \fI<addr>|#<number>\fR"
|
|
Delete the break point. The target break point can be specified by a
|
|
break point number with '#', or by 'addr' like specified in 'break'
|
|
command.
|
|
.XX "\fBstep[/p] \fI[,<count>]\fR"
|
|
Single step 'count' times.
|
|
If 'p' option is specified, print each instruction at each step.
|
|
Otherwise, only print the last instruction.
|
|
.br
|
|
.sp
|
|
Warning: depending on 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.
|
|
.XX "\fBcontinue[/c]\fR"
|
|
Continue execution until a breakpoint or watchpoint.
|
|
If /c, count instructions while executing.
|
|
Some machines (e.g., pmax) also count loads and stores.
|
|
.br
|
|
.sp
|
|
Warning: when counting, the debugger is really silently single-stepping.
|
|
This means that single-stepping on low-level code may cause strange
|
|
behavior.
|
|
.XX "\fBuntil[/p]\fR"
|
|
Stop at the next call or return instruction.
|
|
If 'p' option 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.
|
|
.XX "\fBnext[/p]\fR"
|
|
Stop at the matching return instruction.
|
|
If 'p' option 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.
|
|
.XX "\fBmatch[/p]\fR"
|
|
A synonym for 'next'.
|
|
.XX "\fBtrace[/u] \fI[ <frame_addr> ][,<count>]\fR"
|
|
Stack trace. 'u' option traces user space; if omitted, only traces
|
|
kernel space. 'count' is the number of frames to be traced.
|
|
If the 'count' is omitted, all frames are printed.
|
|
.br
|
|
.sp
|
|
Warning: User space stack trace is valid
|
|
only if the machine dependent code supports it.
|
|
.XX "\fBtrace/t \fI[ <pid> ][,<count>]\fR"
|
|
Stack trace by "thread" (process, on NetBSD) rather than by stack
|
|
frame address. Note that pid is interpreted using the current radix,
|
|
while ps displays pids in decimal; prefix the pid with "0t" to force
|
|
it to be interpreted as decimal.
|
|
.sp
|
|
Warning: trace by pid is valid only if the machine dependent code
|
|
supports it.
|
|
.XX "\fBsearch[/bhl] \fI<addr> <value> [<mask>] [,<count>]\fR"
|
|
Search memory for a value. This command might fail in interesting
|
|
ways if it doesn't find the searched-for value. This is because
|
|
ddb doesn't always recover from touching bad memory. The optional
|
|
count argument limits the search.
|
|
.XX "\fBshow all procs[/m]\fR"
|
|
Display all process information.
|
|
This version of "\fBddb\fR"
|
|
prints more information than previous one.
|
|
It shows UNIX process information like "ps".
|
|
The UNIX process information may not be shown if it is not
|
|
supported in the machine, or the bottom of the stack of the
|
|
target process is not in the main memory at that time.
|
|
The 'm' options will alter the 'ps' display to show vm_map
|
|
addresses for the process and not show other info.
|
|
.br
|
|
.XX "\fBps[/m]\fR"
|
|
A synonym for 'show all procs'.
|
|
.XX "\fBshow registers\fR"
|
|
Display the register set.
|
|
If 'u' option is specified, it displays user registers instead of
|
|
kernel or currently saved one.
|
|
.br
|
|
.sp
|
|
Warning: The support of 'u' option depends on the machine. If
|
|
not supported, incorrect information will be displayed.
|
|
.XX "\fBshow map[/f] \fI<addr>\fR"
|
|
Prints the vm_map at 'addr'. If the 'f' option is specified the
|
|
complete map is printed.
|
|
.XX "\fBshow object[/f] \fI<addr>\fR"
|
|
Prints the vm_object at 'addr'. If the 'f' option is specified the
|
|
complete object is printed.
|
|
.XX "\fBshow watches\fR"
|
|
Displays all watchpoints.
|
|
.XX "\fBwatch \fI<addr>,<size>\fR"
|
|
Set a watchpoint for a region. Execution stops
|
|
when an attempt to modify the region occurs.
|
|
The 'size' argument defaults to 4.
|
|
.br
|
|
If you specify a wrong space address, the request is rejected
|
|
with an error message.
|
|
.br
|
|
.sp
|
|
Warning: Attempts to watch wired kernel memory
|
|
may cause unrecoverable error in some systems such as i386.
|
|
Watchpoints on user addresses work best.
|
|
.br
|
|
.LP
|
|
.XE 4n
|
|
.LP
|
|
.sp
|
|
.B VARIABLES
|
|
.sp
|
|
The debugger accesses registers and variables as
|
|
.I $<name>.
|
|
Register names are as in the "\fBshow registers\fR"
|
|
command.
|
|
Some variables are suffixed with numbers, and may have some modifier
|
|
following a colon immediately after the variable name.
|
|
For example, register variables can have 'u' modifier to indicate
|
|
user register (e.g. $eax:u).
|
|
.br
|
|
.sp
|
|
Built-in variables currently supported are:
|
|
.sp
|
|
.IP radix 12n
|
|
Input and output radix
|
|
.IP maxoff 12n
|
|
Addresses are printed as 'symbol'+offset unless offset is greater than maxoff.
|
|
.IP maxwidth 12n
|
|
The width of the displayed line.
|
|
.IP lines 12n
|
|
The number of lines. It is used by "more" feature.
|
|
.IP tabstops 12n
|
|
Tab stop width.
|
|
.IP onpanic 12n
|
|
If non-zero, the debugger will be called when the kernel panics. Default
|
|
is "on", and may be initialzed at build time with the "DDB_ONPANIC=0"
|
|
option set in the kernel configuration file.
|
|
.IP work\fIxx\fR
|
|
Work variable.
|
|
.I 'xx'
|
|
can be 0 to 31.
|
|
.LP
|
|
All built-in variables are accessible via sysctl(3).
|
|
.LP
|
|
.sp
|
|
.B EXPRESSIONS
|
|
.sp
|
|
Almost all expression operators in C are supported except '~', '^',
|
|
and unary '&'.
|
|
Special rules in "\fBddb\fR"
|
|
are:
|
|
.br
|
|
.IP "<identifier>" 15n
|
|
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,
|
|
[\fI<file_name>\fR:]\fI<func>\fR[:\fI<line_number>\fR]
|
|
[\fI<file_name>\fR:]\fI<variable>\fR, and
|
|
\fI<file_name>\fR[:\fI<line_number>\fR]
|
|
can be accepted as a symbol.
|
|
The symbol may be prefixed with '\fI<symbol_table_name>\fR::'
|
|
like 'emulator::mach_msg_trap' to specify other than kernel symbols.
|
|
.IP "<number>" 15n
|
|
radix is determined by the first two letters:
|
|
0x: hex, 0o: octal, 0t: decimal, otherwise, follow current radix.
|
|
.IP \. 15n
|
|
\'dot'
|
|
.IP \+ 15n
|
|
\'next'
|
|
.IP \.. 15n
|
|
address of the start of the last line examined.
|
|
Unlike 'dot' or 'next', this is only changed by "examine" or
|
|
"write" command.
|
|
.IP \' 15n
|
|
last address explicitly specified.
|
|
.IP "$<variable>" 15n
|
|
register name or variable. It is translated to the value of it.
|
|
It may be followed by a ':' and modifiers as described above.
|
|
.IP \# 15n
|
|
a binary operator which rounds up the left hand side to the next
|
|
multiple of right hand side.
|
|
.IP "*<expr>" 15n
|
|
indirection. It may be followed by a ':' and modifiers as described above.
|