1276 lines
28 KiB
Groff
1276 lines
28 KiB
Groff
.\" $NetBSD: ddb.4,v 1.95 2006/04/28 06:04:27 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1997 - 2003 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Luke Mewburn
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" ---
|
|
.\" This manual page was derived from a -man.old document which bore
|
|
.\" the following copyright message:
|
|
.\" ---
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.Dd April 27, 2006
|
|
.Dt DDB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ddb
|
|
.Nd in-kernel debugger
|
|
.Sh SYNOPSIS
|
|
.Cd options DDB
|
|
.Pp
|
|
To enable history editing:
|
|
.Cd options DDB_HISTORY_SIZE=integer
|
|
.Pp
|
|
To disable entering
|
|
.\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS
|
|
.Ic ddb
|
|
upon kernel panic:
|
|
.Cd options DDB_ONPANIC=0
|
|
.Pp
|
|
To enable teeing all
|
|
.\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS
|
|
.Ic ddb
|
|
output to the kernel msgbuf:
|
|
.Cd options DDB_TEE_MSGBUF=1
|
|
.Pp
|
|
To specify commands which will be executed on each entry to
|
|
.Ic ddb :
|
|
.Cd options DDB_COMMANDONENTER="trace;show registers"
|
|
In this case, "trace" and then "show registers" will be executed automatically.
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
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.
|
|
.Sh ENTERING THE DEBUGGER
|
|
Unless
|
|
.Dv DDB_ONPANIC
|
|
is set to 0,
|
|
.Nm
|
|
will be activated whenever the kernel would otherwise panic.
|
|
.Pp
|
|
.Nm
|
|
may also be activated from the console.
|
|
In general, sending a break on a serial console will activate
|
|
.Nm .
|
|
There are also key sequences for each port that will activate
|
|
.Nm
|
|
from the keyboard:
|
|
.Bl -tag -offset indent -width "mvme68k" -compact
|
|
.It alpha
|
|
\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] on PC style keyboards.
|
|
.It amiga
|
|
\*[Lt]LAlt\*[Gt]-\*[Lt]LAmiga\*[Gt]-\*[Lt]F10\*[Gt]
|
|
.It atari
|
|
\*[Lt]Alt\*[Gt]-\*[Lt]LeftShift\*[Gt]-\*[Lt]F9\*[Gt]
|
|
.It hp300
|
|
\*[Lt]Shift\*[Gt]-\*[Lt]Reset\*[Gt]
|
|
.It hpcarm
|
|
\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
|
|
.It hpcmips
|
|
\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
|
|
.It hpcsh
|
|
\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
|
|
.It i386
|
|
\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
|
|
.br
|
|
\*[Lt]Break\*[Gt] on serial console.
|
|
.It mac68k
|
|
\*[Lt]Command\*[Gt]-\*[Lt]Power\*[Gt], or the Interrupt switch.
|
|
.It macppc
|
|
Some models:
|
|
\*[Lt]Command\*[Gt]-\*[Lt]Option\*[Gt]-\*[Lt]Power\*[Gt]
|
|
.It mvme68k
|
|
Abort switch on CPU card.
|
|
.It pmax
|
|
\*[Lt]Do\*[Gt] on
|
|
.Tn LK-201
|
|
rcons console.
|
|
.br
|
|
\*[Lt]Break\*[Gt] on serial console.
|
|
.It sparc
|
|
\*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a
|
|
.Tn Sun
|
|
keyboard.
|
|
.br
|
|
\*[Lt]Break\*[Gt] on serial console.
|
|
.It sparc64
|
|
\*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a
|
|
.Tn Sun
|
|
keyboard.
|
|
.br
|
|
\*[Lt]Break\*[Gt] on serial console.
|
|
.It sun3
|
|
\*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a
|
|
.Tn Sun
|
|
keyboard.
|
|
.br
|
|
\*[Lt]Break\*[Gt] on serial console.
|
|
.It vax
|
|
\*[Lt]Esc\*[Gt]-\*[Lt]Shift\*[Gt]-D on serial console.
|
|
.It x68k
|
|
Interrupt switch on the body.
|
|
.It xen
|
|
+++++
|
|
(five plus signs)
|
|
.El
|
|
.Pp
|
|
The key sequence to activate
|
|
.Nm
|
|
can be changed by modifying
|
|
.Dq hw.cnmagic
|
|
with
|
|
.Xr sysctl 8 .
|
|
If the console is not dedicated to
|
|
.Nm
|
|
the sequence should not be easily typed by accident.
|
|
In addition,
|
|
.Nm
|
|
may be explicitly activated by the debugging code in the kernel
|
|
if
|
|
.Cm DDB
|
|
is configured.
|
|
.Sh COMMAND SYNTAX
|
|
The general command syntax is:
|
|
.Bd -ragged -offset indent
|
|
.Ic command Ns Op Cm / Ns Ar modifier
|
|
.Ar address
|
|
.Op Cm , Ns Ar count
|
|
.Ed
|
|
.Pp
|
|
The current memory location being edited is referred to as
|
|
.Ar dot ,
|
|
and the next location is
|
|
.Ar next .
|
|
They are displayed as hexadecimal numbers.
|
|
.Pp
|
|
Commands that examine and/or modify memory update
|
|
.Ar dot
|
|
to the address of the last line examined or the last location
|
|
modified, and set
|
|
.Ar next
|
|
to the next location to be examined or modified.
|
|
Other commands don't change
|
|
.Ar dot ,
|
|
and set
|
|
.Ar next
|
|
to be the same as
|
|
.Ar dot .
|
|
.Pp
|
|
A blank line repeats the previous command from the address
|
|
.Ar next
|
|
with the previous
|
|
.Cm count
|
|
and no modifiers.
|
|
Specifying
|
|
.Cm address
|
|
sets
|
|
.Em dot
|
|
to the address.
|
|
If
|
|
.Cm address
|
|
is omitted,
|
|
.Em dot
|
|
is used.
|
|
A missing
|
|
.Cm count
|
|
is taken to be 1 for printing commands, and infinity for stack traces.
|
|
.Pp
|
|
The syntax:
|
|
.Bd -ragged -offset indent
|
|
.Cm , Ns Ar count
|
|
.Ed
|
|
.Pp
|
|
repeats the previous command, just as a blank line does, but with
|
|
the specified
|
|
.Cm count .
|
|
.Pp
|
|
.Nm
|
|
has a
|
|
.Xr more 1 Ns -like
|
|
functionality; if a number of lines in a command's output exceeds the number
|
|
defined in the
|
|
.Va lines
|
|
variable, then
|
|
.Nm
|
|
displays
|
|
.Dq "--db more--"
|
|
and waits for a response, which may be one of:
|
|
.Bl -tag -offset indent -width "\*[Lt]return\*[Gt]"
|
|
.It Aq return
|
|
one more line.
|
|
.It Aq space
|
|
one more page.
|
|
.It Ic q
|
|
abort the current command, and return to the command input mode.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Nm
|
|
history editing is enabled (by defining the
|
|
.D1 Cd options DDB_HISTORY_SIZE=num
|
|
kernel option), then a history of the last
|
|
.Cm num
|
|
commands is kept.
|
|
The history can be manipulated with the following key sequences:
|
|
.Bl -tag -offset indent -width "\*[Lt]Ctrl\*[Gt]-P"
|
|
.It \*[Lt]Ctrl\*[Gt]-P
|
|
retrieve previous command in history (if any).
|
|
.It \*[Lt]Ctrl\*[Gt]-N
|
|
retrieve next command in history (if any).
|
|
.El
|
|
.Sh COMMANDS
|
|
.Nm
|
|
supports the following commands:
|
|
.Bl -tag -width 5n
|
|
.It Xo
|
|
.Sm off
|
|
.Ic \&!
|
|
.Ar address
|
|
.Oo
|
|
.Cm ( Ar expression
|
|
.Op Ar ,...
|
|
.Cm )
|
|
.Oc
|
|
.Sm on
|
|
.Xc
|
|
A synonym for
|
|
.Ic call .
|
|
.It Xo
|
|
.Ic break Ns Op Cm /u
|
|
.Ar address Ns Op Cm , Ns Ar count
|
|
.Xc
|
|
Set a breakpoint at
|
|
.Ar address .
|
|
If
|
|
.Ar count
|
|
is supplied, continues
|
|
.Pq Ar count Ns -1
|
|
times before stopping at the breakpoint.
|
|
If the breakpoint is set, a breakpoint number is printed with
|
|
.Sq \&# .
|
|
This number can be used to
|
|
.Ic delete
|
|
the breakpoint, or to add
|
|
conditions to it.
|
|
.Pp
|
|
If
|
|
.Cm /u
|
|
is specified,
|
|
set a breakpoint at a user-space address.
|
|
Without
|
|
.Cm /u ,
|
|
.Ar 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.
|
|
.Pp
|
|
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.
|
|
.It Xo
|
|
.Ic bt Ns Op Cm /u
|
|
.Sm off
|
|
.Op Ar frame-address
|
|
.Op Cm , Ar count
|
|
.Sm on
|
|
.Xc
|
|
A synonym for
|
|
.Ic trace .
|
|
.It Xo
|
|
.Ic bt/t
|
|
.Sm off
|
|
.Op Ar pid
|
|
.Op Cm , Ar count
|
|
.Sm on
|
|
.Xc
|
|
A synonym for
|
|
.Ic trace .
|
|
.It Xo
|
|
.Ic call
|
|
.Sm off
|
|
.Ar address
|
|
.Oo
|
|
.Cm ( Ar expression
|
|
.Op Ar ,...
|
|
.Cm )
|
|
.Oc
|
|
.Sm on
|
|
.Xc
|
|
Call the function specified by
|
|
.Ar 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.
|
|
.It Ic continue Ns Op Cm /c
|
|
Continue execution until a breakpoint or watchpoint.
|
|
If
|
|
.Cm /c
|
|
is specified, count instructions while executing.
|
|
Some machines (e.g., pmax) also count loads and stores.
|
|
.Pp
|
|
Warning: when counting, the debugger is really silently
|
|
single-stepping.
|
|
This means that single-stepping on low-level may cause strange
|
|
behavior.
|
|
.It Xo
|
|
.Ic delete
|
|
.Ar "address" |
|
|
.Cm # Ns Ar number
|
|
.Xc
|
|
Delete a breakpoint.
|
|
The target breakpoint may be specified by
|
|
.Ar address ,
|
|
as per
|
|
.Ic break ,
|
|
or by the breakpoint number returned by
|
|
.Ic break
|
|
if it's prefixed with
|
|
.Sq Cm \&# .
|
|
.It Xo
|
|
.Ic dmesg Op Ar count
|
|
.Xc
|
|
Prints the contents of the kernel message buffer.
|
|
The optional
|
|
.Ar count
|
|
argument will limit printing to at most the last
|
|
.Ar count
|
|
bytes of the message buffer.
|
|
.It Xo
|
|
.Ic dwatch
|
|
.Ar address
|
|
.Xc
|
|
Delete the watchpoint at
|
|
.Ar address
|
|
that was previously set with
|
|
.Ic watch
|
|
command.
|
|
.It Xo
|
|
.Ic examine Ns Op Cm / Ns Ar modifier
|
|
.Ar address Ns Op Cm , Ns Ar count
|
|
.Xc
|
|
Display the address locations according to the format in
|
|
.Ar modifier .
|
|
Multiple modifier formats display multiple locations.
|
|
If
|
|
.Ar modifier
|
|
isn't specified, the modifier from the last use of
|
|
.Ic examine
|
|
is used.
|
|
.Pp
|
|
The valid format characters for
|
|
.Ar modifier
|
|
are:
|
|
.Bl -tag -offset indent -width 2n -compact
|
|
.It Cm b
|
|
examine bytes (8 bits).
|
|
.It Cm h
|
|
examine half-words (16 bits).
|
|
.It Cm l
|
|
examine words (legacy
|
|
.Dq long ,
|
|
32 bits).
|
|
.It Cm L
|
|
examine long words (implementation dependent)
|
|
.It Cm a
|
|
print the location being examined.
|
|
.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 as displayed as an octal escape code
|
|
(e.g.,
|
|
.Sq \e000 ) .
|
|
.It Cm s
|
|
display the NUL terminated string at the location.
|
|
Non-printing characters are displayed as octal escapes.
|
|
.It Cm 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.
|
|
.It Cm i
|
|
display as a machine instruction.
|
|
.It Cm I
|
|
display as a machine instruction, with possible alternative formats
|
|
depending upon the machine:
|
|
.Bl -tag -offset indent -width "sparc" -compact
|
|
.It alpha
|
|
print register operands
|
|
.It m68k
|
|
use Motorola syntax
|
|
.It pc532
|
|
print instruction bytes in hex
|
|
.It vax
|
|
don't assume that each external label is a procedure entry mask
|
|
.El
|
|
.El
|
|
.It Xo
|
|
.Ic kill
|
|
.Ar pid Ns Op Cm , Ns Ar signal_number
|
|
.Xc
|
|
Send a signal to the process specified by the
|
|
.Ar pid .
|
|
Note that
|
|
.Ar pid
|
|
is interpreted using the current radix (see
|
|
.Cm trace/t
|
|
command for details).
|
|
If
|
|
.Ar signal_number
|
|
isn't specified, the SIGTERM signal is sent.
|
|
.It Ic match Ns Op Cm /p
|
|
A synonym for
|
|
.Ic next .
|
|
.It Ic next Ns Op Cm /p
|
|
Stop at the matching return instruction.
|
|
If
|
|
.Cm /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.
|
|
.It Xo
|
|
.Ic print Ns Op Cm /axzodurc
|
|
.Ar address Op Ar address ...
|
|
.Xc
|
|
Print addresses
|
|
.Ar address
|
|
according to the modifier character, as per
|
|
.Ic examine .
|
|
Valid modifiers are:
|
|
.Cm /a ,
|
|
.Cm /x ,
|
|
.Cm /z ,
|
|
.Cm /o ,
|
|
.Cm /d ,
|
|
.Cm /u ,
|
|
.Cm /r ,
|
|
and
|
|
.Cm /c
|
|
(as per
|
|
.Ic examine ) .
|
|
If no modifier is specified, the most recent one specified is used.
|
|
.Ar address
|
|
may be a string, and is printed
|
|
.Dq as-is .
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
print/x "eax = " $eax "\enecx = " $ecx "\en"
|
|
.Ed
|
|
.Pp
|
|
will produce:
|
|
.Bd -literal -offset indent
|
|
eax = xxxxxx
|
|
ecx = yyyyyy
|
|
.Ed
|
|
.It Xo
|
|
.Sm off
|
|
.Ic ps
|
|
.Op Cm /a
|
|
.Op Cm /n
|
|
.Op Cm /w
|
|
.Sm on
|
|
.Xc
|
|
A synonym for
|
|
.Ic show all procs .
|
|
.It Ic reboot Op Ar flags
|
|
Reboot, using the optionally supplied boot
|
|
.Ar flags ,
|
|
which is a bitmask supporting the same values as for
|
|
.Xr reboot 2 .
|
|
Some of the more useful flags:
|
|
.Bl -column "Value" "RB_POWERDOWN" "Description"
|
|
.It Sy "Value" Ta Sy "Name" Ta Sy "Description"
|
|
.It 0x1 Ta RB_ASKNAME Ta Ask for file name to reboot from
|
|
.It 0x2 Ta RB_SINGLE Ta Reboot to single user mode
|
|
.It 0x4 Ta RB_NOSYNC Ta Don't sync before reboot
|
|
.It 0x8 Ta RB_HALT Ta Halt instead of reboot
|
|
.It 0x40 Ta RB_KDB Ta Boot into kernel debugger
|
|
.It 0x100 Ta RB_DUMP Ta Dump unconditionally before reboot
|
|
.It 0x808 Ta RB_POWERDOWN Ta Power off (or at least halt)
|
|
.El
|
|
.Pp
|
|
Note: Limitations of the command line interface preclude
|
|
specification of a boot string.
|
|
.It Xo
|
|
.Ic search Ns Op Cm /bhl
|
|
.Ar address
|
|
.Ar value
|
|
.Op Ar mask
|
|
.Op Cm , Ns Ar count
|
|
.Xc
|
|
Search memory from
|
|
.Ar address
|
|
for
|
|
.Ar value .
|
|
The unit size is specified with a modifier character, as per
|
|
.Ic examine .
|
|
Valid modifiers are:
|
|
.Cm /b ,
|
|
.Cm /h ,
|
|
and
|
|
.Cm /l .
|
|
If no modifier is specified,
|
|
.Cm /l
|
|
is used.
|
|
.Pp
|
|
This command might fail in interesting ways if it doesn't find
|
|
.Ar value .
|
|
This is because
|
|
.Nm
|
|
doesn't always recover from touching bad memory.
|
|
The optional
|
|
.Ar count
|
|
limits the search.
|
|
.It Xo
|
|
.Ic set
|
|
.Cm $ Ns Ar variable
|
|
.Op Cm =
|
|
.Ar expression
|
|
.Xc
|
|
Set the named variable or register to the value of
|
|
.Ar expression .
|
|
Valid variable names are described in
|
|
.Sx VARIABLES .
|
|
.It Ic show all pages
|
|
Display basic information about all physical pages managed by the VM system.
|
|
For more detailed information about a single page, use
|
|
.Ic show page .
|
|
.It Ic show all pools Ns Op Cm /clp
|
|
Display all pool information.
|
|
Modifiers are the same as
|
|
.Ic show pool .
|
|
.It Xo
|
|
.Sm off
|
|
.Ic "show\ all\ procs"
|
|
.Op Cm /a
|
|
.Op Cm /n
|
|
.Op Cm /w
|
|
.Sm on
|
|
.Xc
|
|
Display all process information.
|
|
Valid modifiers:
|
|
.Bl -tag -width 3n
|
|
.It Cm /n
|
|
show process information in a
|
|
.Xr ps 1
|
|
style format (this is the default).
|
|
Information printed includes: process ID, parent process ID,
|
|
process group, UID, process status, process flags, process
|
|
command name, and process wait channel message.
|
|
.It Cm /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
|
|
.Ic show map
|
|
command.
|
|
.It Cm /w
|
|
show each process' PID, command, system call emulation, wait channel
|
|
address, and wait channel message.
|
|
.El
|
|
.It Ic show breaks
|
|
Display all breakpoints.
|
|
.It Xo
|
|
.Ic show buf Ns Op Cm /f
|
|
.Ar address
|
|
.Xc
|
|
Print the struct buf at
|
|
.Ar address .
|
|
The
|
|
.Cm /f
|
|
does nothing at this time.
|
|
.It Xo
|
|
.Ic show event Ns Op Cm /f
|
|
.Xc
|
|
Print all the non-zero
|
|
.Xr evcnt 9
|
|
event counters.
|
|
If
|
|
.Cm /f
|
|
is specified, all event counters with a count of zero are printed as well.
|
|
.It Xo
|
|
.Ic show map Ns Op Cm /f
|
|
.Ar address
|
|
.Xc
|
|
Print the vm_map at
|
|
.Ar address .
|
|
If
|
|
.Cm /f
|
|
is specified, the complete map is printed.
|
|
.It Xo
|
|
.Ic show mount Ns Op Cm /f
|
|
.Ar address
|
|
.Xc
|
|
Print the mount structure at
|
|
.Ar address .
|
|
If
|
|
.Cm /f
|
|
is specified, the complete vnode list is printed.
|
|
.It Xo
|
|
.Ic show mbuf Ns Op Cm /c
|
|
.Ar address
|
|
.Xc
|
|
Print the mbuf structure at
|
|
.Ar address .
|
|
If
|
|
.Cm /c
|
|
is specified, the mbufs in the chain are followed.
|
|
.It Ic show ncache Ar address
|
|
Dump the namecache list associated with vnode at
|
|
.Ar address .
|
|
.It Xo
|
|
.Ic show object Ns Op Cm /f
|
|
.Ar address
|
|
.Xc
|
|
Print the vm_object at
|
|
.Ar address .
|
|
If
|
|
.Cm /f
|
|
is specified, the complete object is printed.
|
|
.It Xo
|
|
.Ic show page Ns Op Cm /f
|
|
.Ar address
|
|
.Xc
|
|
Print the vm_page at
|
|
.Ar address .
|
|
If
|
|
.Cm /f
|
|
is specified, the complete page is printed.
|
|
.It Xo
|
|
.Ic show pool Ns Op Cm /clp
|
|
.Ar address
|
|
.Xc
|
|
Print the pool at
|
|
.Ar address .
|
|
Valid modifiers:
|
|
.Bl -tag -width 4n -compact
|
|
.It Cm /c
|
|
Print the cachelist and its statistics for this pool.
|
|
.It Cm /l
|
|
Print the log entries for this pool.
|
|
.It Cm /p
|
|
Print the pagelist for this pool.
|
|
.El
|
|
.It Ic show registers Ns Op Cm /u
|
|
Display the register set.
|
|
If
|
|
.Cm /u
|
|
is specified, display user registers instead of kernel registers
|
|
or the currently save one.
|
|
.Pp
|
|
Warning: support for
|
|
.Cm /u
|
|
is machine dependent.
|
|
If not supported, incorrect information will be displayed.
|
|
.It Ic 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
|
|
.Sq \&! .
|
|
.It Ic show uvmexp
|
|
Print a selection of UVM counters and statistics.
|
|
.It Xo
|
|
.Ic show vnode Ns Op Cm /f
|
|
.Ar address
|
|
.Xc
|
|
Print the vnode at
|
|
.Ar address .
|
|
If
|
|
.Cm /f
|
|
is specified, the complete vnode is printed.
|
|
.It Ic show watches
|
|
Display all watchpoints.
|
|
.It Xo
|
|
.Ic sifting Ns Op Cm /F
|
|
.Ar string
|
|
.Xc
|
|
Search the symbol tables for all symbols of which
|
|
.Ar string
|
|
is a substring, and display them.
|
|
If
|
|
.Cm /F
|
|
is specified, a character is displayed immediately after each symbol
|
|
name indicating the type of symbol.
|
|
.Pp
|
|
For
|
|
.Xr a.out 5 Ns -format
|
|
symbol tables,
|
|
absolute symbols display
|
|
.Sy @ ,
|
|
text segment symbols display
|
|
.Sy * ,
|
|
data segment symbols display
|
|
.Sy + ,
|
|
.Tn BSS
|
|
segment symbols display
|
|
.Sy - ,
|
|
and filename symbols display
|
|
.Sy / .
|
|
For
|
|
.Tn ELF Ns -format
|
|
symbol tables,
|
|
object symbols display
|
|
.Sy + ,
|
|
function symbols display
|
|
.Sy * ,
|
|
section symbols display
|
|
.Sy \*[Am] ,
|
|
and file symbols display
|
|
.Sy / .
|
|
.Pp
|
|
To sift for a string beginning with a number, escape the first
|
|
character with a backslash as:
|
|
.Bd -literal -offset indent
|
|
sifting \\386
|
|
.Ed
|
|
.It Xo
|
|
.Ic step Ns Op Cm /p
|
|
.Op Cm , Ns Ar count
|
|
.Xc
|
|
Single-step
|
|
.Ar count
|
|
times.
|
|
If
|
|
.Cm /p
|
|
is specified, print each instruction at each step.
|
|
Otherwise, only print the last instruction.
|
|
.Pp
|
|
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.
|
|
.It Ic sync
|
|
Force a crash dump, and then reboot.
|
|
.It Xo
|
|
.Ic trace
|
|
.Ns Op Cm /u Ns Op Cm l
|
|
.Sm off
|
|
.Op Ar frame-address
|
|
.Op Cm , Ar count
|
|
.Sm on
|
|
.Xc
|
|
Stack trace from
|
|
.Ar frame-address .
|
|
If
|
|
.Cm /u
|
|
is specified, trace user-space, otherwise trace kernel-space.
|
|
.Ar count
|
|
is the number of frames to be traced.
|
|
If
|
|
.Ar count
|
|
is omitted, all frames are printed.
|
|
If
|
|
.Cm /l
|
|
is specified, the trace is printed and also stored in the kernel
|
|
message buffer.
|
|
.Pp
|
|
Warning: user-space stack trace is valid only if the machine dependent
|
|
code supports it.
|
|
.It Xo
|
|
.Ic trace/t Ns Op Cm l
|
|
.Sm off
|
|
.Op Ar pid
|
|
.Op Cm , Ar count
|
|
.Sm on
|
|
.Xc
|
|
Stack trace by
|
|
.Dq thread
|
|
(process, on
|
|
.Nx )
|
|
rather than by stack frame address.
|
|
Note that
|
|
.Ar pid
|
|
is interpreted using the current radix, whilst
|
|
.Ic ps
|
|
displays pids in decimal; prefix
|
|
.Ar pid
|
|
with
|
|
.Sq 0t
|
|
to force it to be interpreted as decimal (see
|
|
.Sx VARIABLES
|
|
section for radix).
|
|
If
|
|
.Cm /l
|
|
is specified, the trace is printed and also stored in the kernel
|
|
message buffer.
|
|
.Pp
|
|
Warning: trace by pid is valid only if the machine dependent code
|
|
supports it.
|
|
.It Ic until Ns Op Cm /p
|
|
Stop at the next call or return instruction.
|
|
If
|
|
.Cm /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.
|
|
.It Xo
|
|
.Ic watch
|
|
.Sm off
|
|
.Ar address
|
|
.Op Cm , Ar size
|
|
.Sm on
|
|
.Xc
|
|
Set a watchpoint for a region.
|
|
Execution stops when an attempt to modify the region occurs.
|
|
.Ar size
|
|
defaults to 4.
|
|
.Pp
|
|
If you specify a wrong space address, the request is
|
|
rejected with an error message.
|
|
.Pp
|
|
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.
|
|
.It Xo
|
|
.Ic write Ns Op Cm /bhl
|
|
.Ar address
|
|
.Ar expression Op Ar expression ...
|
|
.Xc
|
|
Write the
|
|
.Ar expression Ns s
|
|
at succeeding locations.
|
|
The unit size is specified with a modifier character, as per
|
|
.Ic examine .
|
|
Valid modifiers are:
|
|
.Cm /b ,
|
|
.Cm /h ,
|
|
and
|
|
.Cm /l .
|
|
If no modifier is specified,
|
|
.Cm /l
|
|
is used.
|
|
.Pp
|
|
Warning: since there is no delimiter between
|
|
.Ar expression Ns s ,
|
|
strange things may occur.
|
|
It's best to enclose each
|
|
.Ar expression
|
|
in parentheses.
|
|
.It Xo
|
|
.Ic x Ns Op Cm / Ns Ar modifier
|
|
.Ar address Ns Op Cm , Ns Ar count
|
|
.Xc
|
|
A synonym for
|
|
.Ic examine .
|
|
.\" XXX - these commands aren't implemented; jhawk 19 May 2000
|
|
.\" .It Ic xf
|
|
.\" Examine forward.
|
|
.\" .Ic xf
|
|
.\" re-executes the most recent
|
|
.\" .Ic execute
|
|
.\" command with the same parameters except that
|
|
.\" .Ar address
|
|
.\" is set to
|
|
.\" .Ar next .
|
|
.\" .It Ic xb
|
|
.\" Examine backward.
|
|
.\" .Ic xb
|
|
.\" re-executes the most recent
|
|
.\" .Ic execute
|
|
.\" command with the same parameters, except that
|
|
.\" .Ar address
|
|
.\" is set to the last start address minus its size.
|
|
.El
|
|
.Sh MACHINE-SPECIFIC COMMANDS
|
|
The "glue" code that hooks
|
|
.Nm
|
|
into the
|
|
.Nx
|
|
kernel for any given port can also add machine specific commands
|
|
to the
|
|
.Nm
|
|
command parser.
|
|
All of these commands are preceded by the command word
|
|
.Em machine
|
|
to indicate that they are part of the machine-specific command
|
|
set (e.g.
|
|
.Ic machine reboot ) .
|
|
Some of these commands are:
|
|
.Ss ALPHA
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic halt
|
|
Call the PROM monitor to halt the CPU.
|
|
.It Ic reboot
|
|
Call the PROM monitor to reboot the CPU.
|
|
.El
|
|
.Ss ARM32
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic vmstat
|
|
Equivalent to
|
|
.Xr vmstat 1
|
|
output with "-s" option (statistics).
|
|
.It Ic vnode
|
|
Print out a description of a vnode.
|
|
.It Ic intrchain
|
|
Print the list of IRQ handlers.
|
|
.It Ic panic
|
|
Print the current "panic" string.
|
|
.It Ic frame
|
|
Given a trap frame address, print out the trap frame.
|
|
.El
|
|
.Ss MIPS
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic kvtop
|
|
Print the physical address for a given kernel virtual address.
|
|
.It Ic tlb
|
|
Print out the Translation Lookaside Buffer (TLB).
|
|
Only works in
|
|
.Nx
|
|
kernels compiled with
|
|
.Dv DEBUG
|
|
option.
|
|
.El
|
|
.Ss SH3
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic tlb
|
|
Print TLB entries
|
|
.It Ic cache
|
|
Print cache entries
|
|
.It Ic frame
|
|
Print switch frame and trap frames.
|
|
.It Ic stack
|
|
Print kernel stack usage.
|
|
Only works in
|
|
.Nx
|
|
kernels compiled with the
|
|
.Dv KSTACK_DEBUG
|
|
option.
|
|
.El
|
|
.Ss SPARC
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic prom
|
|
Exit to the Sun PROM monitor.
|
|
.El
|
|
.Ss SPARC64
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic buf
|
|
Print buffer information.
|
|
.It Ic ctx
|
|
Print process context information.
|
|
.It Ic dtlb
|
|
Print data translation look-aside buffer context information.
|
|
.It Ic dtsb
|
|
Display data translation storage buffer information.
|
|
.It Ic kmap
|
|
Display information about the listed mapping in the kernel pmap.
|
|
Use the
|
|
.Dq f
|
|
modifier to get a full listing.
|
|
.It Ic pcb
|
|
Display information about the
|
|
.Dq struct pcb
|
|
listed.
|
|
.It Ic pctx
|
|
Attempt to change process context.
|
|
.It Ic page
|
|
Display the pointer to the
|
|
.Dq struct vm_page
|
|
for this physical address.
|
|
.It Ic phys
|
|
Display physical memory.
|
|
.It Ic pmap
|
|
Display the pmap.
|
|
Use the
|
|
.Dq f
|
|
modifier to get a fuller listing.
|
|
.It Ic proc
|
|
Display some information about the process pointed to, or curproc.
|
|
.It Ic prom
|
|
Enter the OFW PROM.
|
|
.It Ic pv
|
|
Display the
|
|
.Dq struct pv_entry
|
|
pointed to.
|
|
.It Ic stack
|
|
Dump the window stack.
|
|
Use the
|
|
.Dq u
|
|
modifier to get userland information.
|
|
.It Ic tf
|
|
Display full trap frame state.
|
|
This is most useful for inclusion with bug reports.
|
|
.It Ic ts
|
|
Display trap state.
|
|
.It Ic traptrace
|
|
Display or set trap trace information.
|
|
Use the
|
|
.Dq r
|
|
and
|
|
.Dq f
|
|
modifiers to get reversed and full information, respectively.
|
|
.It Ic uvmdump
|
|
Dumps the UVM histories.
|
|
.It Ic watch
|
|
Set or clear a physical or virtual hardware watchpoint.
|
|
Pass the address to be watched, or
|
|
.Dq 0
|
|
to clear the watchpoint.
|
|
Append
|
|
.Dq p
|
|
to the watch point to use the physical watchpoint registers.
|
|
.It Ic window
|
|
Print register window information about given address.
|
|
.El
|
|
.Ss SUN3 and SUN3X
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic abort
|
|
Drop into monitor via abort (allows continue).
|
|
.It Ic halt
|
|
Exit to Sun PROM monitor as in
|
|
.Xr halt 8 .
|
|
.It Ic reboot
|
|
Reboot the machine as in
|
|
.Xr reboot 8 .
|
|
.It Ic pgmap
|
|
Given an address, print the address, segment map, page map, and
|
|
Page Table Entry (PTE).
|
|
.El
|
|
.Sh VARIABLES
|
|
.Nm
|
|
accesses registers and variables as
|
|
.Cm $ Ns Ar name .
|
|
Register names are as per the
|
|
.Ic 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
|
|
.Sq u
|
|
modifier to indicate user register
|
|
(e.g.,
|
|
.Li "$eax:u" ) .
|
|
.Pp
|
|
Built-in variables currently supported are:
|
|
.Bl -tag -offset indent -width "maxwidth" -compact
|
|
.It Va lines
|
|
The number of lines.
|
|
This is used by the
|
|
.Ic more
|
|
feature.
|
|
.It Va maxoff
|
|
Addresses are printed as
|
|
.Li 'symbol'+offset
|
|
unless
|
|
.Li offset
|
|
is greater than
|
|
.Va maxoff .
|
|
.It Va maxwidth
|
|
The width of the displayed line.
|
|
.It Va onpanic
|
|
If non-zero (the default),
|
|
.Nm
|
|
will be invoked when the kernel panics.
|
|
If the kernel configuration option
|
|
.D1 Cd options DDB_ONPANIC=0
|
|
is used,
|
|
.Va onpanic
|
|
will be initialized to off.
|
|
.It Va fromconsole
|
|
If non-zero (the default),
|
|
the kernel allows to enter
|
|
.Nm
|
|
from the console (by break signal or special key sequence).
|
|
If the kernel configuration option
|
|
.D1 Cd options DDB_FROMCONSOLE=0
|
|
is used,
|
|
.Va fromconsole
|
|
will be initialized to off.
|
|
.It Va radix
|
|
Input and output radix.
|
|
.It Va tabstops
|
|
Tab stop width.
|
|
.It Va tee_msgbuf
|
|
If explicitly set to non zero (zero is the default) all
|
|
.Nm
|
|
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
|
|
.D1 Cd options DDB_TEE_MSGBUF=1
|
|
wich will initialise
|
|
.Va tee_msgbuf
|
|
to be 1.
|
|
This option is especially handy for poor souls
|
|
who don't have a serial console but want to recall
|
|
.Nm
|
|
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.
|
|
.\" .It Va work Ns Sy xx
|
|
.\" Temporary work variable.
|
|
.\" .Sq Sy xx
|
|
.\" is between 0 and 31.
|
|
.El
|
|
.Pp
|
|
All built-in variables are accessible via
|
|
.Xr sysctl 3 .
|
|
.Sh EXPRESSIONS
|
|
Almost all expression operators in C are supported, except
|
|
.Sq \&~ ,
|
|
.Sq \&^ ,
|
|
and unary
|
|
.Sq \&\*[Am] .
|
|
Special rules in
|
|
.Nm
|
|
are:
|
|
.Bl -tag -offset indent -width "identifier"
|
|
.It Ar identifier
|
|
name of a symbol.
|
|
It is translated to the address (or value) of it.
|
|
.Sq \&.
|
|
and
|
|
.Sq \&:
|
|
can be used in the identifier.
|
|
If supported by an object format dependent routine,
|
|
.Sm off
|
|
.Xo
|
|
.Oo Ar filename : Oc
|
|
.Ar function
|
|
.Oo : Ar line\ number Oc ,
|
|
.Xc
|
|
.Sm on
|
|
.Sm off
|
|
.Xo
|
|
.Oo Ar filename : Oc
|
|
.Ar variable ,
|
|
.Xc
|
|
.Sm on
|
|
and
|
|
.Sm off
|
|
.Xo
|
|
.Ar filename
|
|
.Oo : Ar "line number" Oc ,
|
|
.Xc
|
|
.Sm on
|
|
can be accepted as a symbol.
|
|
The symbol may be prefixed with
|
|
.Ar symbol_table_name\^ : :
|
|
(e.g.,
|
|
.Li emulator::mach_msg_trap )
|
|
to specify other than kernel symbols.
|
|
.It Ar number
|
|
number.
|
|
Radix is determined by the first two characters:
|
|
.Sq 0x
|
|
- hex,
|
|
.Sq 0o
|
|
- octal,
|
|
.Sq 0t
|
|
- decimal,
|
|
otherwise follow current radix.
|
|
.It Cm .
|
|
.Ar dot
|
|
.It Cm +
|
|
.Ar next
|
|
.It Cm ..
|
|
address of the start of the last line examined.
|
|
Unlike
|
|
.Ar dot
|
|
or
|
|
.Ar next ,
|
|
this is only changed by the
|
|
.Ic examine
|
|
or
|
|
.Ic write
|
|
commands.
|
|
.It Cm \&" \"" XXX: emacs highlighting
|
|
last address explicitly specified.
|
|
.It Cm $ Ns Ar name
|
|
register name or variable.
|
|
It is translated to the value of it.
|
|
It may be followed by a
|
|
.Sq \&:
|
|
and modifiers as described above.
|
|
.It Cm #
|
|
a binary operator which rounds up the left hand side to the next
|
|
multiple of right hand side.
|
|
.It Cm * Ns Ar expr
|
|
expression indirection.
|
|
It may be followed by a
|
|
.Sq \&:
|
|
and modifiers as described above.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr reboot 2 ,
|
|
.Xr options 4 ,
|
|
.Xr reboot 8 ,
|
|
.Xr sysctl 8 ,
|
|
.Xr cnmagic 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
kernel debugger was written as part of the MACH project at
|
|
Carnegie-Mellon University.
|