Page MenuHomeFreeBSD
Differential D21460 Diff 63411 head/share/man/man4/ddb.4

Changeset View

Standalone View

View Options

head/share/man/man4/ddb.4

Show All 18 Lines
.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
.\" School of Computer Science .\" School of Computer Science
.\" Carnegie Mellon University .\" Carnegie Mellon University
.\" Pittsburgh PA 15213-3890 .\" Pittsburgh PA 15213-3890
.\" .\"
.\" any improvements or extensions that they make and grant Carnegie Mellon .\" any improvements or extensions that they make and grant Carnegie Mellon
.\" the rights to redistribute these changes. .\" 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$ .\" $FreeBSD$
.\" .\"
.Dd October 10, 2019 .Dd October 17, 2019
.Dt DDB 4 .Dt DDB 4
.Os .Os
.Sh NAME .Sh NAME
.Nm ddb .Nm ddb
.Nd interactive kernel debugger .Nd interactive kernel debugger
.Sh SYNOPSIS .Sh SYNOPSIS
In order to enable kernel debugging facilities include: In order to enable kernel debugging facilities include:
.Bd -ragged -offset indent .Bd -ragged -offset indent
▲ Show 20 Lines • Show All 135 Lines • ▼ Show 20 Lines
the the
.Nm emacs .Nm emacs
control keys, the usual control keys, the usual
.Tn ANSI .Tn ANSI
arrow keys may be used to arrow keys may be used to
browse through the history buffer, and move the cursor within the browse through the history buffer, and move the cursor within the
current line. current line.
.Sh COMMANDS .Sh COMMANDS
.Ss COMMON DEBUGGER COMMANDS
.Bl -tag -width indent -compact .Bl -tag -width indent -compact
.It Ic help
Print a short summary of the available commands and command
abbreviations.
.Pp
.It Xo .It Xo
.Ic examine Ns Op Li / Ns Cm AISabcdghilmorsuxz ... .Ic examine Ns Op Li / Ns Cm AISabcdghilmorsuxz ...
.Oo Ar addr Oc Ns Op , Ns Ar count .Oo Ar addr Oc Ns Op , Ns Ar count
.Xc .Xc
.It Xo .It Xo
.Ic x Ns Op Li / Ns Cm AISabcdghilmorsuxz ... .Ic x Ns Op Li / Ns Cm AISabcdghilmorsuxz ...
.Oo Ar addr Oc Ns Op , Ns Ar count .Oo Ar addr Oc Ns Op , Ns Ar count
.Xc .Xc
▲ Show 20 Lines • Show All 167 Lines • ▼ Show 20 Lines
.Ar addr .Ar addr
specified in the original specified in the original
.Ic break .Ic break
command, or by omitting command, or by omitting
.Ar addr .Ar addr
to get the default address of to get the default address of
.Va dot . .Va dot .
.Pp .Pp
.It Ic halt
Halt the system.
.Pp
.It Ic watch Oo Ar addr Oc Ns Op , Ns Ar size .It Ic watch Oo Ar addr Oc Ns Op , Ns Ar size
Set a watchpoint for a region. Set a watchpoint for a region.
Execution stops when an attempt to modify the region occurs. Execution stops when an attempt to modify the region occurs.
The The
.Ar size .Ar size
argument defaults to 4. argument defaults to 4.
If you specify a wrong space address, the request is rejected If you specify a wrong space address, the request is rejected
with an error message. with an error message.
Show All 17 Lines
Use Use
.Ic hwatch .Ic hwatch
for setting watchpoints on kernel address locations only, and avoid for setting watchpoints on kernel address locations only, and avoid
its use on user mode address spaces. its use on user mode address spaces.
.Pp .Pp
.It Ic dhwatch Oo Ar addr Oc Ns Op , Ns Ar size .It Ic dhwatch Oo Ar addr Oc Ns Op , Ns Ar size
Delete specified hardware watchpoint. Delete specified hardware watchpoint.
.Pp .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 step Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count .It Ic step Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count
.It Ic s Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count .It Ic s Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count
Single step Single step
.Ar count .Ar count
times. times.
If the If the
.Cm p .Cm p
modifier is specified, print each instruction at each step. modifier is specified, print each instruction at each step.
▲ Show 20 Lines • Show All 84 Lines • ▼ Show 20 Lines
.Xc .Xc
Search memory for Search memory for
.Ar value . .Ar value .
The optional The optional
.Ar count .Ar count
argument limits the search. argument limits the search.
.\" .\"
.Pp .Pp
.It Ic reboot Op Ar seconds
.It Ic reset Op Ar seconds
Hard reset the system.
If the optional argument
.Ar seconds
is given, the debugger will wait for this long, at most a week,
before rebooting.
.Pp
.It Ic thread Ar addr | tid
Switch the debugger to the thread with ID
.Ar tid ,
if the argument is a decimal number, or address
.Ar addr ,
otherwise.
.El
.Pp
.Ss SPECIALIZED HELPER COMMANDS
.Pp
.Bl -tag -width indent -compact
.It Xo .It Xo
.Ic findstack .Ic findstack
.Ar addr .Ar addr
.Xc .Xc
Prints the thread address for a thread kernel-mode stack of which contains the Prints the thread address for a thread kernel-mode stack of which contains the
specified address. specified address.
If the thread is not found, search the thread stack cache and prints the If the thread is not found, search the thread stack cache and prints the
cached stack address. cached stack address.
▲ Show 20 Lines • Show All 629 Lines • ▼ Show 20 Lines
Displays all watchpoints. Displays all watchpoints.
Shows watchpoints set with "watch" command. Shows watchpoints set with "watch" command.
.\" .\"
.Pp .Pp
.It Ic show Cm witness .It Ic show Cm witness
Shows information about lock acquisition coming from the Shows information about lock acquisition coming from the
.Xr witness 4 .Xr witness 4
subsystem. subsystem.
.\" .El
.Pp .Pp
.Ss OFFLINE DEBUGGING COMMANDS
.Bl -tag -width indent -compact
.It Ic gdb .It Ic gdb
Toggles between remote GDB and DDB mode. Switches to remote GDB mode.
In remote GDB mode, another machine is required that runs In remote GDB mode, another machine is required that runs
.Xr gdb 1 .Xr gdb 1
using the remote debug feature, with a connection to the serial using the remote debug feature, with a connection to the serial
console port on the target machine. console port on the target machine.
Currently only available on the
i386
architecture.
.Pp .Pp
.It Ic halt .It Ic netdump Fl s Ar server Oo Fl g Ar gateway Oc Fl c Ar client Fl i Ar iface
Halt the system. Configure
.Xr netdump 4
with the provided parameters, and immediately perform a netdump.
.Pp .Pp
.It Ic kill Ar sig pid There are some known limitations.
Send signal Principally,
.Ar sig .Xr netdump 4
to process only supports IPv4 at this time.
.Ar pid . The address arguments to the
The signal is acted on upon returning from the debugger. .Ic netdump
This command can be used to kill a process causing resource contention command must be dotted decimal IPv4 addresses.
in the case of a hung system. (Hostnames are not supported.)
See At present, the command only works if the machine is in a panic state.
.Xr signal 3 Finally, the
for a list of signals. .Nm
Note that the arguments are reversed relative to .Ic netdump
.Xr kill 2 . command does not provide any way to configure compression or encryption.
.Pp .Pp
.It Ic reboot Op Ar seconds
.It Ic reset Op Ar seconds
Hard reset the system.
If the optional argument
.Ar seconds
is given, the debugger will wait for this long, at most a week,
before rebooting.
.Pp
.It Ic help
Print a short summary of the available commands and command
abbreviations.
.Pp
.It Ic capture on .It Ic capture on
.It Ic capture off .It Ic capture off
.It Ic capture reset .It Ic capture reset
.It Ic capture status .It Ic capture status
.Nm .Nm
supports a basic output capture facility, which can be used to retrieve the supports a basic output capture facility, which can be used to retrieve the
results of debugging commands from userspace using results of debugging commands from userspace using
.Xr sysctl 3 . .Xr sysctl 3 .
▲ Show 20 Lines • Show All 55 Lines • ▼ Show 20 Lines
The The
.Ic textdump set .Ic textdump set
command may be used to force the next kernel core dump to be a textdump command may be used to force the next kernel core dump to be a textdump
rather than a traditional memory dump or minidump. rather than a traditional memory dump or minidump.
.Ic textdump status .Ic textdump status
reports whether a textdump has been scheduled. reports whether a textdump has been scheduled.
.Ic textdump unset .Ic textdump unset
cancels a request to perform a textdump as the next kernel core dump. cancels a request to perform a textdump as the next kernel core dump.
.Pp
.It Ic thread Ar addr | tid
Switch the debugger to the thread with ID
.Ar tid ,
if the argument is a decimal number, or address
.Ar addr ,
otherwise.
.El .El
.Sh VARIABLES .Sh VARIABLES
The debugger accesses registers and variables as The debugger accesses registers and variables as
.Li $ Ns Ar name . .Li $ Ns Ar name .
Register names are as in the Register names are as in the
.Dq Ic show Cm registers .Dq Ic show Cm registers
command. command.
Some variables are suffixed with numbers, and may have some modifier Some variables are suffixed with numbers, and may have some modifier
▲ Show 20 Lines • Show All 325 Lines • Show Last 20 Lines