936 lines
22 KiB
Groff
936 lines
22 KiB
Groff
.\"
|
|
.\" Mach Operating System
|
|
.\" Copyright (c) 1991,1990 Carnegie Mellon University
|
|
.\" Copyright (c) 2007 Robert N. M. Watson
|
|
.\" 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.
|
|
.\"
|
|
.\" changed a \# to #, since groff choked on it.
|
|
.\"
|
|
.\" HISTORY
|
|
.\" ddb.4,v
|
|
.\" Revision 1.1 1993/07/15 18:41:02 brezak
|
|
.\" Man page for DDB
|
|
.\"
|
|
.\" Revision 2.6 92/04/08 08:52:57 rpd
|
|
.\" Changes from OSF.
|
|
.\" [92/01/17 14:19:22 jsb]
|
|
.\" Changes for OSF debugger modifications.
|
|
.\" [91/12/12 tak]
|
|
.\"
|
|
.\" Revision 2.5 91/06/25 13:50:22 rpd
|
|
.\" Added some watchpoint explanation.
|
|
.\" [91/06/25 rpd]
|
|
.\"
|
|
.\" Revision 2.4 91/06/17 15:47:31 jsb
|
|
.\" Added documentation for continue/c, match, search, and watchpoints.
|
|
.\" I've not actually explained what a watchpoint is; maybe Rich can
|
|
.\" do that (hint, hint).
|
|
.\" [91/06/17 10:58:08 jsb]
|
|
.\"
|
|
.\" Revision 2.3 91/05/14 17:04:23 mrt
|
|
.\" Correcting copyright
|
|
.\"
|
|
.\" Revision 2.2 91/02/14 14:10:06 mrt
|
|
.\" Changed to new Mach copyright
|
|
.\" [91/02/12 18:10:12 mrt]
|
|
.\"
|
|
.\" Revision 2.2 90/08/30 14:23:15 dbg
|
|
.\" Created.
|
|
.\" [90/08/30 dbg]
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 26, 2007
|
|
.Dt DDB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ddb
|
|
.Nd interactive kernel debugger
|
|
.Sh SYNOPSIS
|
|
.Cd options KDB
|
|
.Cd options DDB
|
|
.Pp
|
|
To prevent activation of the debugger on kernel
|
|
.Xr panic 9 :
|
|
.Cd options KDB_UNATTENDED
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
kernel debugger has most of the features of the old
|
|
.Nm kdb ,
|
|
but with a more rational syntax
|
|
inspired by
|
|
.Xr gdb 1 .
|
|
If linked into the running kernel,
|
|
it can be invoked locally with the
|
|
.Ql debug
|
|
.Xr keymap 5
|
|
action.
|
|
The debugger is also invoked on kernel
|
|
.Xr panic 9
|
|
if the
|
|
.Va debug.debugger_on_panic
|
|
.Xr sysctl 8
|
|
MIB variable is set non-zero,
|
|
which is the default
|
|
unless the
|
|
.Dv KDB_UNATTENDED
|
|
option is specified.
|
|
.Pp
|
|
The current location is called
|
|
.Va dot .
|
|
The
|
|
.Va dot
|
|
is displayed with
|
|
a hexadecimal format at a prompt.
|
|
The commands
|
|
.Ic examine
|
|
and
|
|
.Ic write
|
|
update
|
|
.Va dot
|
|
to the address of the last line
|
|
examined or the last location modified, and set
|
|
.Va next
|
|
to the address of
|
|
the next location to be examined or changed.
|
|
Other commands do not change
|
|
.Va dot ,
|
|
and set
|
|
.Va next
|
|
to be the same as
|
|
.Va dot .
|
|
.Pp
|
|
The general command syntax is:
|
|
.Ar command Ns Op Li / Ns Ar modifier
|
|
.Ar address Ns Op Li , Ns Ar count
|
|
.Pp
|
|
A blank line repeats the previous command from the address
|
|
.Va next
|
|
with
|
|
count 1 and no modifiers.
|
|
Specifying
|
|
.Ar address
|
|
sets
|
|
.Va dot
|
|
to the address.
|
|
Omitting
|
|
.Ar address
|
|
uses
|
|
.Va dot .
|
|
A missing
|
|
.Ar count
|
|
is taken
|
|
to be 1 for printing commands or infinity for stack traces.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
debugger has a pager feature (like the
|
|
.Xr more 1
|
|
command)
|
|
for the output.
|
|
If an output line exceeds the number set in the
|
|
.Va lines
|
|
variable, it displays
|
|
.Dq Li --More--
|
|
and waits for a response.
|
|
The valid responses for it are:
|
|
.Pp
|
|
.Bl -tag -compact -width ".Li SPC"
|
|
.It Li SPC
|
|
one more page
|
|
.It Li RET
|
|
one more line
|
|
.It Li q
|
|
abort the current command, and return to the command input mode
|
|
.El
|
|
.Pp
|
|
Finally,
|
|
.Nm
|
|
provides a small (currently 10 items) command history, and offers
|
|
simple
|
|
.Nm emacs Ns -style
|
|
command line editing capabilities.
|
|
In addition to
|
|
the
|
|
.Nm emacs
|
|
control keys, the usual
|
|
.Tn ANSI
|
|
arrow keys might be used to
|
|
browse through the history buffer, and move the cursor within the
|
|
current line.
|
|
.Sh COMMANDS
|
|
.Bl -tag -width indent -compact
|
|
.It Ic examine
|
|
.It Ic x
|
|
Display the addressed locations according to the formats in the modifier.
|
|
Multiple modifier formats display multiple locations.
|
|
If no format is specified, the last format specified for this command
|
|
is used.
|
|
.Pp
|
|
The format characters are:
|
|
.Bl -tag -compact -width indent
|
|
.It Cm b
|
|
look at by bytes (8 bits)
|
|
.It Cm h
|
|
look at by half words (16 bits)
|
|
.It Cm l
|
|
look at by long words (32 bits)
|
|
.It Cm a
|
|
print the location being displayed
|
|
.It Cm A
|
|
print the location with a line number if possible
|
|
.It Cm x
|
|
display in unsigned hex
|
|
.It Cm z
|
|
display in signed hex
|
|
.It Cm o
|
|
display in unsigned octal
|
|
.It Cm d
|
|
display in signed decimal
|
|
.It Cm u
|
|
display in unsigned decimal
|
|
.It Cm r
|
|
display in current radix, signed
|
|
.It Cm c
|
|
display low 8 bits as a character.
|
|
Non-printing characters are displayed as an octal escape code (e.g.,
|
|
.Ql \e000 ) .
|
|
.It Cm s
|
|
display the null-terminated string at the location.
|
|
Non-printing characters are displayed as octal escapes.
|
|
.It Cm m
|
|
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.
|
|
.It Cm i
|
|
display as an instruction
|
|
.It Cm I
|
|
display as an instruction with possible alternate formats depending on the
|
|
machine:
|
|
.Bl -tag -width ".Tn powerpc" -compact
|
|
.It Tn alpha
|
|
Show the registers of the instruction.
|
|
.It Tn amd64
|
|
No alternate format.
|
|
.It Tn i386
|
|
No alternate format.
|
|
.It Tn ia64
|
|
No alternate format.
|
|
.It Tn powerpc
|
|
No alternate format.
|
|
.It Tn sparc64
|
|
No alternate format.
|
|
.El
|
|
.It Cm S
|
|
display a symbol name for the pointer stored at the address
|
|
.El
|
|
.Pp
|
|
.It Ic xf
|
|
Examine forward:
|
|
execute an
|
|
.Ic examine
|
|
command with the last specified parameters to it
|
|
except that the next address displayed by it is used as the start address.
|
|
.Pp
|
|
.It Ic xb
|
|
Examine backward:
|
|
execute an
|
|
.Ic 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.
|
|
.Pp
|
|
.It Ic print Ns Op Li / Ns Cm acdoruxz
|
|
.It Ic p Ns Op Li / Ns Cm acdoruxz
|
|
Print
|
|
.Ar addr Ns s
|
|
according to the modifier character (as described above for
|
|
.Cm examine ) .
|
|
Valid formats are:
|
|
.Cm a , x , z , o , d , u , r ,
|
|
and
|
|
.Cm c .
|
|
If no modifier is specified, the last one specified to it is used.
|
|
The argument
|
|
.Ar addr
|
|
can be a string, in which case it is printed as it is.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
print/x "eax = " $eax "\enecx = " $ecx "\en"
|
|
.Ed
|
|
.Pp
|
|
will print like:
|
|
.Bd -literal -offset indent
|
|
eax = xxxxxx
|
|
ecx = yyyyyy
|
|
.Ed
|
|
.Pp
|
|
.It Xo
|
|
.Ic write Ns Op Li / Ns Cm bhl
|
|
.Ar addr expr1 Op Ar expr2 ...
|
|
.Xc
|
|
.It Xo
|
|
.Ic w Ns Op Li / Ns Cm bhl
|
|
.Ar addr expr1 Op Ar expr2 ...
|
|
.Xc
|
|
Write the expressions specified after
|
|
.Ar addr
|
|
on the command line at succeeding locations starting with
|
|
.Ar addr .
|
|
The write unit size can be specified in the modifier with a letter
|
|
.Cm b
|
|
(byte),
|
|
.Cm h
|
|
(half word) or
|
|
.Cm l
|
|
(long word) respectively.
|
|
If omitted,
|
|
long word is assumed.
|
|
.Pp
|
|
.Sy Warning :
|
|
since there is no delimiter between expressions, strange
|
|
things may happen.
|
|
It is best to enclose each expression in parentheses.
|
|
.Pp
|
|
.It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr
|
|
Set the named variable or register with the value of
|
|
.Ar expr .
|
|
Valid variable names are described below.
|
|
.Pp
|
|
.It Ic break Ns Op Li / Ns Cm u
|
|
.It Ic b Ns Op Li / Ns Cm u
|
|
Set a break point at
|
|
.Ar addr .
|
|
If
|
|
.Ar count
|
|
is supplied, continues
|
|
.Ar count
|
|
\- 1 times before stopping at the
|
|
break point.
|
|
If the break point is set, a break point number is
|
|
printed with
|
|
.Ql # .
|
|
This number can be used in deleting the break point
|
|
or adding conditions to it.
|
|
.Pp
|
|
If the
|
|
.Cm u
|
|
modifier is specified, this command sets a break point in user space
|
|
address.
|
|
Without the
|
|
.Cm u
|
|
option, the address is considered in the kernel
|
|
space, and wrong space address is rejected with an error message.
|
|
This modifier can be used only if it is supported by machine dependent
|
|
routines.
|
|
.Pp
|
|
.Sy 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.
|
|
.Pp
|
|
.It Ic delete Ar addr
|
|
.It Ic d Ar addr
|
|
.It Ic delete Li # Ns Ar number
|
|
.It Ic d Li # Ns Ar number
|
|
Delete the break point.
|
|
The target break point can be specified by a
|
|
break point number with
|
|
.Ql # ,
|
|
or by using the same
|
|
.Ar addr
|
|
specified in the original
|
|
.Ic break
|
|
command.
|
|
.Pp
|
|
.It Ic watch Ar addr Ns Li , Ns Ar size
|
|
Set a watchpoint for a region.
|
|
Execution stops when an attempt to modify the region occurs.
|
|
The
|
|
.Ar size
|
|
argument defaults to 4.
|
|
If you specify a wrong space address, the request is rejected
|
|
with an error message.
|
|
.Pp
|
|
.Sy Warning :
|
|
Attempts to watch wired kernel memory
|
|
may cause unrecoverable error in some systems such as i386.
|
|
Watchpoints on user addresses work best.
|
|
.Pp
|
|
.It Ic hwatch Ar addr Ns Li , Ns Ar size
|
|
Set a hardware watchpoint for a region if supported by the
|
|
architecture.
|
|
Execution stops when an attempt to modify the region occurs.
|
|
The
|
|
.Ar size
|
|
argument defaults to 4.
|
|
.Pp
|
|
.Sy Warning :
|
|
The hardware debug facilities do not have a concept of separate
|
|
address spaces like the watch command does.
|
|
Use
|
|
.Ic hwatch
|
|
for setting watchpoints on kernel address locations only, and avoid
|
|
its use on user mode address spaces.
|
|
.Pp
|
|
.It Ic dhwatch Ar addr Ns Li , Ns Ar size
|
|
Delete specified hardware watchpoint.
|
|
.Pp
|
|
.It Ic step Ns Op Li / Ns Cm p
|
|
.It Ic s Ns Op Li / Ns Cm p
|
|
Single step
|
|
.Ar count
|
|
times (the comma is a mandatory part of the syntax).
|
|
If the
|
|
.Cm p
|
|
modifier is specified, print each instruction at each step.
|
|
Otherwise, only print the last instruction.
|
|
.Pp
|
|
.Sy 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.
|
|
.Pp
|
|
.It Ic continue Ns Op Li / Ns Cm c
|
|
.It Ic c Ns Op Li / Ns Cm c
|
|
Continue execution until a breakpoint or watchpoint.
|
|
If the
|
|
.Cm c
|
|
modifier is specified, count instructions while executing.
|
|
Some machines (e.g., pmax) also count loads and stores.
|
|
.Pp
|
|
.Sy Warning :
|
|
when counting, the debugger is really silently single-stepping.
|
|
This means that single-stepping on low-level code may cause strange
|
|
behavior.
|
|
.Pp
|
|
.It Ic until Ns Op Li / Ns Cm p
|
|
Stop at the next call or return instruction.
|
|
If the
|
|
.Cm p
|
|
modifier 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.
|
|
.Pp
|
|
.It Ic next Ns Op Li / Ns Cm p
|
|
.It Ic match Ns Op Li / Ns Cm p
|
|
Stop at the matching return instruction.
|
|
If the
|
|
.Cm p
|
|
modifier 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.
|
|
.Pp
|
|
.It Xo
|
|
.Ic trace Ns Op Li / Ns Cm u
|
|
.Op Ar pid | tid
|
|
.Op Li , Ns Ar count
|
|
.Xc
|
|
.It Xo
|
|
.Ic t Ns Op Li / Ns Cm u
|
|
.Op Ar pid | tid
|
|
.Op Li , Ns Ar count
|
|
.Xc
|
|
.It Xo
|
|
.Ic where Ns Op Li / Ns Cm u
|
|
.Op Ar pid | tid
|
|
.Op Li , Ns Ar count
|
|
.Xc
|
|
.It Xo
|
|
.Ic bt Ns Op Li / Ns Cm u
|
|
.Op Ar pid | tid
|
|
.Op Li , Ns Ar count
|
|
.Xc
|
|
Stack trace.
|
|
The
|
|
.Cm u
|
|
option traces user space; if omitted,
|
|
.Ic trace
|
|
only traces
|
|
kernel space.
|
|
The optional argument
|
|
.Ar count
|
|
is the number of frames to be traced.
|
|
If
|
|
.Ar count
|
|
is omitted, all frames are printed.
|
|
.Pp
|
|
.Sy Warning :
|
|
User space stack trace is valid
|
|
only if the machine dependent code supports it.
|
|
.Pp
|
|
.It Xo
|
|
.Ic search Ns Op Li / Ns Cm bhl
|
|
.Ar addr
|
|
.Ar value
|
|
.Op Ar mask
|
|
.Op Li , Ns Ar count
|
|
.Xc
|
|
Search memory for
|
|
.Ar value .
|
|
This command might fail in interesting
|
|
ways if it does not find the searched-for value.
|
|
This is because
|
|
.Nm
|
|
does not always recover from touching bad memory.
|
|
The optional
|
|
.Ar count
|
|
argument limits the search.
|
|
.Pp
|
|
.It Ic show Cm all procs Ns Op Li / Ns Cm m
|
|
.It Ic ps Ns Op Li / Ns Cm m
|
|
Display all process information.
|
|
The 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
|
|
.Cm m
|
|
modifier will alter the display to show VM map
|
|
addresses for the process and not show other info.
|
|
.Pp
|
|
.It Ic show Cm registers Ns Op Li / Ns Cm u
|
|
Display the register set.
|
|
If the
|
|
.Cm u
|
|
modifier is specified, it displays user registers instead of
|
|
kernel or currently saved one.
|
|
.Pp
|
|
.Sy Warning :
|
|
The support of the
|
|
.Cm u
|
|
modifier depends on the machine.
|
|
If not supported, incorrect information will be displayed.
|
|
.Pp
|
|
.It Ic show Cm sysregs
|
|
Show system registers (e.g.,
|
|
.Li cr0-4
|
|
on i386.)
|
|
Not present on some platforms.
|
|
.Pp
|
|
.It Ic show Cm geom Op Ar addr
|
|
If the
|
|
.Ar addr
|
|
argument is not given, displays the entire GEOM topology.
|
|
If the
|
|
.Ar addr
|
|
is given, displays details about the given GEOM object (class, geom, provider
|
|
or consumer).
|
|
.Pp
|
|
.It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr
|
|
Prints the VM map at
|
|
.Ar addr .
|
|
If the
|
|
.Cm f
|
|
modifier is specified the
|
|
complete map is printed.
|
|
.Pp
|
|
.It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr
|
|
Prints the VM object at
|
|
.Ar addr .
|
|
If the
|
|
.Cm f
|
|
option is specified the
|
|
complete object is printed.
|
|
.Pp
|
|
.It Ic show Cm vnode Ar addr
|
|
Displays details about the given vnode.
|
|
.Pp
|
|
.It Ic show Cm watches
|
|
Displays all watchpoints.
|
|
.Pp
|
|
.It Ic gdb
|
|
Toggles between remote GDB and DDB mode.
|
|
In remote GDB mode, another machine is required that runs
|
|
.Xr gdb 1
|
|
using the remote debug feature, with a connection to the serial
|
|
console port on the target machine.
|
|
Currently only available on the
|
|
i386
|
|
architecture.
|
|
.Pp
|
|
.It Ic halt
|
|
Halt the system.
|
|
.Pp
|
|
.It Ic kill Ar sig pid
|
|
Send signal
|
|
.Ar sig
|
|
to process
|
|
.Ar pid .
|
|
The signal is acted on upon returning from the debugger.
|
|
This command can be used to kill a process causing resource contention
|
|
in the case of a hung system.
|
|
See
|
|
.Xr signal 3
|
|
for a list of signals.
|
|
Note that the arguments are reversed relative to
|
|
.Xr kill 2 .
|
|
.Pp
|
|
.It Ic reboot
|
|
.It Ic reset
|
|
Hard reset the system.
|
|
.Pp
|
|
.It Ic help
|
|
Print a short summary of the available commands and command
|
|
abbreviations.
|
|
.Pp
|
|
.It Ic capture on
|
|
.It Ic capture off
|
|
.It Ic capture reset
|
|
.It Ic capture status
|
|
.Nm
|
|
supports a basic output capture facility, which can be used to retrieve the
|
|
results of debugging commands from userpsace using
|
|
.Xr sysctl 2 .
|
|
.Ic capture on
|
|
enables output capture;
|
|
.Ic capture off
|
|
disables capture.
|
|
.Ic capture reset
|
|
will clear the capture buffer and disable capture.
|
|
.Ic capture status
|
|
will report current buffer use, buffer size, and disposition of output
|
|
capture.
|
|
.Pp
|
|
Userspace processes may inspect and manage
|
|
.Nm
|
|
capture state using
|
|
.Xr sysctl 8 :
|
|
.Pp
|
|
.Dv debug.ddb.capture.bufsize
|
|
may be used to query or set the current capture buffer size.
|
|
.Pp
|
|
.Dv debug.ddb.capture.maxbufsize
|
|
may be used to query the compile-time limit on the capture buffer size.
|
|
.Pp
|
|
.Dv debug.ddb.capture.bytes
|
|
may be used to query the number of bytes of output currently in the capture
|
|
buffer.
|
|
.Pp
|
|
.Dv debug.ddb.capture.data
|
|
returns the contents of the buffer as a string to an appropriately privileged
|
|
process.
|
|
.Pp
|
|
This facility is particularly useful in concert with the scripting and
|
|
.Xr textdump 4
|
|
facilities, allowing scripted debugging output to be captured and
|
|
committed to disk as part of a textdump for later analysis.
|
|
The contents of the capture buffer may also be inspected in a kernel core dump
|
|
using
|
|
.Xr kgdb 1 .
|
|
.Pp
|
|
.It Ic run
|
|
.It Ic script
|
|
.It Ic scripts
|
|
.It Ic unscript
|
|
Run, define, list, and delete scripts.
|
|
See the
|
|
.Sx SCRIPTING
|
|
section for more information on the scripting facility.
|
|
.Pp
|
|
.It Ic textdump set
|
|
.It Ic textdump status
|
|
.It Ic textdump unset
|
|
The
|
|
.Ic textdump set
|
|
command may be used to force the next kernel core dump to be a textdump
|
|
rather than a traditional memory dump or minidump.
|
|
.Ic textdump status
|
|
reports whether a textdump has been scheduled.
|
|
.Ic textdump unset
|
|
cancels a request to perform a textdump as the next kernel core dump.
|
|
More information may be found in
|
|
.Xr textdump 4 .
|
|
.El
|
|
.Sh VARIABLES
|
|
The debugger accesses registers and variables as
|
|
.Li $ Ns Ar name .
|
|
Register names are as in the
|
|
.Dq Ic show Cm registers
|
|
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 a
|
|
.Cm u
|
|
modifier to indicate user register (e.g.,
|
|
.Dq Li $eax:u ) .
|
|
.Pp
|
|
Built-in variables currently supported are:
|
|
.Pp
|
|
.Bl -tag -width ".Va tabstops" -compact
|
|
.It Va radix
|
|
Input and output radix.
|
|
.It Va maxoff
|
|
Addresses are printed as
|
|
.Dq Ar symbol Ns Li + Ns Ar offset
|
|
unless
|
|
.Ar offset
|
|
is greater than
|
|
.Va maxoff .
|
|
.It Va maxwidth
|
|
The width of the displayed line.
|
|
.It Va lines
|
|
The number of lines.
|
|
It is used by the built-in pager.
|
|
.It Va tabstops
|
|
Tab stop width.
|
|
.It Va work Ns Ar xx
|
|
Work variable;
|
|
.Ar xx
|
|
can take values from 0 to 31.
|
|
.El
|
|
.Sh EXPRESSIONS
|
|
Most expression operators in C are supported except
|
|
.Ql ~ ,
|
|
.Ql ^ ,
|
|
and unary
|
|
.Ql & .
|
|
Special rules in
|
|
.Nm
|
|
are:
|
|
.Bl -tag -width ".No Identifiers"
|
|
.It Identifiers
|
|
The name of a symbol is translated to the value of the symbol, which
|
|
is the address of the corresponding object.
|
|
.Ql \&.
|
|
and
|
|
.Ql \&:
|
|
can be used in the identifier.
|
|
If supported by an object format dependent routine,
|
|
.Sm off
|
|
.Oo Ar filename : Oc Ar func : lineno ,
|
|
.Sm on
|
|
.Oo Ar filename : Oc Ns Ar variable ,
|
|
and
|
|
.Oo Ar filename : Oc Ns Ar lineno
|
|
can be accepted as a symbol.
|
|
.It Numbers
|
|
Radix is determined by the first two letters:
|
|
.Ql 0x :
|
|
hex,
|
|
.Ql 0o :
|
|
octal,
|
|
.Ql 0t :
|
|
decimal; otherwise, follow current radix.
|
|
.It Li \&.
|
|
.Va dot
|
|
.It Li +
|
|
.Va next
|
|
.It Li ..
|
|
address of the start of the last line examined.
|
|
Unlike
|
|
.Va dot
|
|
or
|
|
.Va next ,
|
|
this is only changed by
|
|
.Ic examine
|
|
or
|
|
.Ic write
|
|
command.
|
|
.It Li '
|
|
last address explicitly specified.
|
|
.It Li $ Ns Ar variable
|
|
Translated to the value of the specified variable.
|
|
It may be followed by a
|
|
.Ql \&:
|
|
and modifiers as described above.
|
|
.It Ar a Ns Li # Ns Ar b
|
|
A binary operator which rounds up the left hand side to the next
|
|
multiple of right hand side.
|
|
.It Li * Ns Ar expr
|
|
Indirection.
|
|
It may be followed by a
|
|
.Ql \&:
|
|
and modifiers as described above.
|
|
.El
|
|
.Sh SCRIPTING
|
|
.Nm
|
|
supports a basic scripting facility to allow automating tasks or responses to
|
|
specific events.
|
|
Each script consists of a list of DDB commands to be executed sequentially,
|
|
and is assigned a unique name.
|
|
Certain script names have special meaning, and will be automatically run on
|
|
various
|
|
.Nm
|
|
events if scripts by those names have been defined.
|
|
.Pp
|
|
The
|
|
.Ic script
|
|
command may be used to define a script by name.
|
|
Scripts consist of a series of
|
|
.Nm
|
|
commands separated with the
|
|
.Ic ;
|
|
character.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
script kdb.enter.panic=bt; show pcpu
|
|
script lockinfo=show alllocks; show lockedvnods
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Ic scripts
|
|
command lists currently defined scripts.
|
|
.Pp
|
|
The
|
|
.Ic run
|
|
command execute a script by name.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
run lockinfo
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Ic unscript
|
|
command may be used to delete a script by name.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
unscript kdb.enter.panic
|
|
.Ed
|
|
.Pp
|
|
These functions may also be performed from userspace using the
|
|
.Xr ddb 8
|
|
command.
|
|
.Pp
|
|
Certain scripts are run automatically, if defined, for specific
|
|
.Nm
|
|
events.
|
|
The follow scripts are run when various events occur:
|
|
.Bl -tag -width kdb.enter.powerfail
|
|
.It Dv kdb.enter.acpi
|
|
The kernel debugger was entered as a result of an
|
|
.Xr acpi 4
|
|
event.
|
|
.It Dv kdb.enter.bootflags
|
|
The kernel debugger was entered at boot as a result of the debugger boot
|
|
flag being set.
|
|
.It Dv kdb.enter.break
|
|
The kernel debugger was entered as a result of a serial or console break.
|
|
.It Dv kdb.enter.cam
|
|
The kernel debugger was entered as a result of a
|
|
.Xr CAM 4
|
|
event.
|
|
.It Dv kdb.enter.mac
|
|
The kernel debugger was entered as a result of an assertion failure in the
|
|
.Xr mac_test 4
|
|
module of the
|
|
TrustedBSD MAC Framework.
|
|
.It Dv kdb.enter.ndis
|
|
The kernel debugger was entered as a result of an
|
|
.Xr ndis 4
|
|
breakpoint event.
|
|
.It Dv kdb.enter.netgraph
|
|
The kernel debugger was entered as a result of a
|
|
.Xr netgraph 4
|
|
event.
|
|
.It Dv kdb.enter.panic
|
|
.Xr panic 9
|
|
was called.
|
|
.It Dv kdb.enter.powerfail
|
|
The kernel debugger was entered as a result of a powerfail NMI on the sparc64
|
|
platform.
|
|
.It Dv kdb.enter.powerpc
|
|
The kernel debugger was entered as a result of an unimplemented interrupt
|
|
type on the powerpc platform.
|
|
.It Dv kdb.enter.sysctl
|
|
The kernel debugger was entered as a result of the
|
|
.Dv debug.kdb.enter
|
|
sysctl being set.
|
|
.It Dv kdb.enter.trapsig
|
|
The kernel debugger was entered as a result of a trapsig event on the sparc64
|
|
or sun4v platform.
|
|
.It Dv kdb.enter.unionfs
|
|
The kernel debugger was entered as a result of an assertion failure in the
|
|
union file system.
|
|
.It Dv kdb.enter.unknown
|
|
The kernel debugger was entered, but no reason has been set.
|
|
.It Dv kdb.enter.vfslock
|
|
The kernel debugger was entered as a result of a VFS lock violation.
|
|
.It Dv kdb.enter.watchdog
|
|
The kernel debugger was entered as a result of a watchdog firing.
|
|
.It Dv kdb.enter.witness
|
|
The kernel debugger was entered as a result of a
|
|
.Xr witness 4
|
|
violation.
|
|
.El
|
|
.Pp
|
|
In the event that none of these scripts is found,
|
|
.Nm
|
|
will attempt to execute a default script:
|
|
.Bl -tag -width kdb.enter.powerfail
|
|
.It Dv kdb.enter.default
|
|
The kernel debugger was entered, but a script exactly matching the reason for
|
|
entering was not defined.
|
|
This can be used as a catch-all to handle cases not specifically of interest;
|
|
for example,
|
|
.Dv kdb.enter.witness
|
|
might be defined to have special handling, and
|
|
.Dv kdb.enter.default
|
|
might be defined to simply panic and reboot.
|
|
.El
|
|
.Sh HINTS
|
|
On machines with an ISA expansion bus, a simple NMI generation card can be
|
|
constructed by connecting a push button between the A01 and B01 (CHCHK# and
|
|
GND) card fingers.
|
|
Momentarily shorting these two fingers together may cause the bridge chipset to
|
|
generate an NMI, which causes the kernel to pass control to
|
|
.Nm .
|
|
Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary.
|
|
The NMI allows one to break into the debugger on a wedged machine to
|
|
diagnose problems.
|
|
Other bus' bridge chipsets may be able to generate NMI using bus specific
|
|
methods.
|
|
.Sh SEE ALSO
|
|
.Xr gdb 1 ,
|
|
.Xr kgdb 1 ,
|
|
.Xr acpi 4 ,
|
|
.Xr CAM 4 ,
|
|
.Xr mac_text 4 ,
|
|
.Xr ndis 4 ,
|
|
.Xr netgraph 4 ,
|
|
.Xr textdump 4 ,
|
|
.Xr witness 4 ,
|
|
.Xr ddb 8 ,
|
|
.Xr sysctl 8 ,
|
|
.Xr panic 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
debugger was developed for Mach, and ported to
|
|
.Bx 386 0.1 .
|
|
This manual page translated from
|
|
.Xr man 7
|
|
macros by
|
|
.An Garrett Wollman .
|
|
.Pp
|
|
.An Robert N. M. Watson
|
|
added support for
|
|
.Nm
|
|
output capture,
|
|
.Xr textdump 4
|
|
and scripting in
|
|
.Fx 8.0 .
|