84ceb5dfe7
The "ditto" character is " (double-quote); not , (comma) as indicated in the manpage; and not ' (single-quote) as indicated in the man.old -style manpage from which the mdoc manpage was derived. Some other versions of ddb use single-quote for this feature, and this part of the code may change again in the near future, but the documentation now affects reality now. they
981 lines
21 KiB
Groff
981 lines
21 KiB
Groff
.\" $NetBSD: ddb.4,v 1.48 2000/06/07 13:24:11 jhawk Exp $
|
|
.\"
|
|
.\" Copyright (c) 1997, 1998 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 October 28, 1999
|
|
.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
|
|
.Nm
|
|
upon kernel panic:
|
|
.Cd options DDB_ONPANIC=0
|
|
.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
|
|
<Ctrl>-<Alt>-<Esc> on PC style keyboards.
|
|
.It amiga
|
|
<LAlt>-<LAmiga>-<F10>
|
|
.It atari
|
|
<Alt>-<LeftShift>-<F9>
|
|
.It hp300
|
|
<Shift>-<Reset>
|
|
.It hpcmips
|
|
<Ctrl>-<Alt>-<Esc>
|
|
.It i386
|
|
<Ctrl>-<Alt>-<Esc>
|
|
.br
|
|
<Break> on serial console.
|
|
.It mac68k
|
|
<Command>-<Power>, or the Interrupt switch.
|
|
.It mvme68k
|
|
Abort switch on CPU card.
|
|
.It pmax
|
|
<Do> on
|
|
.Tn LK-201
|
|
rcons console.
|
|
.br
|
|
<Break> on serial console.
|
|
.It sparc
|
|
<L1>-A, or <Stop>-A on a
|
|
.Tn Sun
|
|
keyboard.
|
|
.br
|
|
<Break> on serial console.
|
|
.It sun3
|
|
<L1>-A, or <Stop>-A on a
|
|
.Tn Sun
|
|
keyboard.
|
|
.br
|
|
<Break> on serial console.
|
|
.It sun3x
|
|
<L1>-A, or <Stop>-A on a
|
|
.Tn Sun
|
|
keyboard.
|
|
.br
|
|
<Break> on serial console.
|
|
.It x68k
|
|
Interrupt switch on the body.
|
|
.El
|
|
.Pp
|
|
In addition,
|
|
.Nm
|
|
may be explicitly activated by the debugging code in the kernel
|
|
if
|
|
.Cm DDB
|
|
is configured.
|
|
.Sh COMMAND SYNTAX
|
|
.Pp
|
|
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
|
|
.Ic 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 -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 "<return>"
|
|
.It <return>
|
|
one more line.
|
|
.It <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 "<Ctrl>-P"
|
|
.It <Ctrl>-P
|
|
retrieve previous command in history (if any).
|
|
.It <Ctrl>-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 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 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 .
|
|
.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 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-are, 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 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 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 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 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
|
|
.Ns Xr a.out 5 -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 & ,
|
|
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
|
|
.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.
|
|
.Pp
|
|
Warning: user-space stack trace is valid only if the machine dependent
|
|
code supports it.
|
|
.It Xo
|
|
.Ic trace/t
|
|
.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)
|
|
.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 8
|
|
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 SPARC
|
|
.Bl -tag -width "intrchain" -compact
|
|
.It Ic prom
|
|
Exit to the Sun PROM monitor.
|
|
.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 initialised to off.
|
|
.It Va radix
|
|
Input and output radix.
|
|
.It Va tabstops
|
|
Tab stop width.
|
|
.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 \&& .
|
|
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
|
|
.Xo
|
|
.Oo Ar filename : Oc
|
|
.Ar variable ,
|
|
.Xc
|
|
and
|
|
.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" Ns ::
|
|
(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 \&"
|
|
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
|
|
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 HISTORY
|
|
The
|
|
.Nm
|
|
kernel debugger was written as part of the MACH project at
|
|
Carnegie-Mellon University.
|
|
.Sh SEE ALSO
|
|
.Xr options 4 ,
|
|
.Xr sysctl 8
|