.\"	$NetBSD: ddb.4,v 1.202.2.2 2024/07/03 19:09:10 martin Exp $
.\"
.\" Copyright (c) 1997 - 2019 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.
.\"
.\" 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 June 29, 2024
.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.
.Pp
To enable extended online help:
.Cd options DDB_VERBOSE_HELP .
.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 "xen domU" -compact
.It alpha
<Ctrl>-<Alt>-<Esc> on PC style keyboards.
.It amd64
<Ctrl>-<Alt>-<Esc>
.It ""
<Break> on serial console.
.It amiga
<LAlt>-<LAmiga>-<F10>
.It atari
<Alt>-<LeftShift>-<F9>
.It evbarm
<Ctrl>-<Alt>-<Esc> on PC style keyboards.
.It ""
<Break> on serial console.
.It ""
Some models:
+++++
(five plus signs) on serial console.
.It hp300
<Shift>-<Reset>
.It hpcarm
<Ctrl>-<Alt>-<Esc>
.It hpcmips
<Ctrl>-<Alt>-<Esc>
.It hpcsh
<Ctrl>-<Alt>-<Esc>
.It hppa
<Ctrl>-<Alt>-<Esc> on PC style keyboards.
.It ""
+++++
(five plus signs) on PDC console
.It ""
<Break> on serial console.
.It i386
<Ctrl>-<Alt>-<Esc>
.It ""
<Break> on serial console.
.It mac68k
<Command>-<Power>, or the Interrupt switch.
.It macppc
Some models:
<Command>-<Option>-<Power>
.It mvme68k
Abort switch on CPU card.
.It pmax
<Do> on LK-201 rcons console.
.It ""
<Break> on serial console.
.It sandpoint
<Break> on serial console.
.It sparc
<L1>-A, or <Stop>-A on a Sun keyboard.
.It ""
<Break> on serial console.
.It sparc64
<L1>-A, or <Stop>-A on a Sun keyboard.
.It ""
<Break> on serial console.
.It sun3
<L1>-A, or <Stop>-A on a Sun keyboard.
.It ""
<Break> on serial console.
.It vax
<Esc> followed by <Shift>-D on serial console.
.It x68k
Interrupt switch on the body.
.It xen dom0
<Ctrl>-<Alt>-<Esc> on PC style keyboards.
.It ""
+++++
(five plus signs) on serial console.
.It xen domU
+++++
(five plus signs) on serial console.
.It zaurus
<Ctrl>-<Alt>-<Esc>
.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.
.Pp
Commands can be automatically run when
.Nm
is entered by using
.Cd options DDB_COMMANDONENTER
or by setting
.Ar ddb.commandonenter
with
.Xr sysctl 8 .
Multiple commands can be separated by a semi-colon.
.Sh COMMAND SYNTAX
The general command syntax is:
.Bd -ragged -offset indent
.Ic command Ns Op / Ns Ar modifier
.Ar address
.Op , 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 "<return>"
.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
You can set
.Va lines
variable to zero to disable this feature.
.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 Ic \&! Ns Ar address Ns Oo ( Ar expression Ns Oo Ar ,... Oc ) Oc
A synonym for
.Ic call .
.It Ic break Ns Oo Cm /u Oc Ar address Ns Op , Ns Ar count
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 Ic bt Ns Oo Cm /ul Oc Oo Ar frame-address Oc Ns Oo , Ns Ar count Oc
A synonym for
.Ic trace .
.It Ic bt/t Ns Oo Cm /ul Oc Oo Ar pid Oc Ns Oo , Ns Ar count Oc
A synonym for
.Ic trace/t .
.It Ic bt/a Ns Oo Cm /ul Oc Oo Ar lwpaddr Oc Ns Oo , Ns Ar count Oc
A synonym for
.Ic trace/a .
.It Ic call Ar address Ns Oo ( Ns Ar expression Ns Oo Ar ,... Oc ) Oc
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 Ic delete Ar "address" | Cm # Ns Ar number
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 Ic dmesg Op Ar count
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 Ic dwatch Ar address
Delete the watchpoint at
.Ar address
that was previously set with
.Ic watch
command.
.It Ic examine Ns Oo Cm / Ns Ar modifier Oc Ar address Ns Op , Ns Ar count
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 q
examine quad-words (64 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 p
display as a pointer and it's symbol if possible.
.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 m68k
use Motorola syntax
.It vax
don't assume that each external label is a procedure entry mask
.El
.El
.It Ic kill Ar pid Ns Op , Ns Ar signal_number
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 Ic print Ns Oo Cm /axzodurc Oc Ar address Op Ar address ...
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 Ic ps Ns Oo Cm /a Oc Ns Oo Cm /n Oc Ns Oo Cm /w Oc Ns Oo Cm /l Oc
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 Ic search Ns Oo Cm /bhl Oc Ar address Ar value \
Oo Ar mask Oc Oo , Ns Ar count Oc
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 Ic set Cm $ Ns Ar variable Oo Cm = Oc Ar expression
Set the named variable or register to the value of
.Ar expression .
Valid variable names are described in
.Sx VARIABLES .
.It Ic show all callout
Display information about callouts in the system.
See
.Xr callout 9
for more information on callouts.
.It Ic show all locks Ns Op Cm /t
Display details information about all active locks.
If
.Cm /t
is specified, stack traces of LWPs holding locks are also printed.
This command is only useful if a kernel is compiled with
.Cd options LOCKDEBUG .
.It Ic show all mount Ns Op Cm /f
Display all mount points.
If
.Cm /f
is specified, the complete vnode list is printed.
.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 /clpsS
Display all pool information.
Modifiers are the same as
.Ic show pool .
.It Ic "show\ all\ procs" Ns Oo Cm /a Oc Ns Oo Cm /n Oc Ns Oo Cm /w Oc Ns \
Oo Cm /l Oc
Display all process information.
Valid modifiers:
.Bl -tag -width 3n
.It Cm /n
show process information in a
.Xr ps 1
style format.
Information printed includes: process ID, parent process ID,
process group, UID, process status, process flags, number of LWPs,
command name, and process wait channel message.
.It Cm /a
show each process ID, command name, 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 LWP ID, process ID, command name, system call emulation,
priority, wait channel message and wait channel address.
LWPs currently running on a CPU are marked with the '\&>' sign.
.It Cm /l
show each LWP ID, process ID, process status, CPU ID the LWP runs on,
process flags, kernel virtual address of LWP structure,
LWP name and wait channel message.
LWPs currently running on a CPU are marked with the '\&>' sign.
This is the default.
.El
.It Ic show all tstiles Ns Oo Cm /t Oc
Display all lwps that are currently waiting in turnstiles to acquire
locks, which locks they are waiting for, and who currently holds them.
Valid modifiers:
.Bl -tag -width 3n
.It Cm /t
show a stack trace of the lwp that currently holds each lock
.El
.It Ic show routes
Dump the entire
.Dv AF_INET
routing table.
This command is available only on systems which support inet.
.It Ic show breaks
Display all breakpoints.
.It Ic show buf Ns Oo Cm /f Oc Ar address
Print the struct buf at
.Ar address .
The
.Cm /f
does nothing at this time.
.It Ic show event Ns Oo Cm /f Oc Ns Oo Cm /i Oc Ns Oo Cm /m Oc Ns \
Oo Cm /t Oc
Print all the non-zero
.Xr evcnt 9
event counters.
Valid modifiers:
.Bl -tag -width 3n
.It Cm /f
event counters with a count of zero are printed as well.
.It Cm /i
interrupted counters will be displayed.
.It Cm /m
misc counters will be displayed.
.It Cm /t
trap counters will be displayed.
.El
.Pp
If none of
.Cm /i ,
.Cm /m ,
or
.Cm /t
are specified, all are shown.
You can combine any of these.
For example, the modifier
.Cm /itf
will select both interrupt and trap events, including those that are non-zero.
.It Ic show files Ar address
Display information about the vnodes of the files that are currently
open by the process associated with the proc structure at
.Ar address .
This address can be found using the
.Ic show all procs /a
command.
If the kernel is compiled with
.Cd options LOCKDEBUG
then details about the locking of the underlying uvm object will also
be displayed.
.It Ic show lock Ar address
Display information about a lock at
.Ar address .
This command is only useful if a kernel is compiled with
.Cd options LOCKDEBUG .
.It Ic show lockstats
Display information about lock statistics.
This command is only useful if a kernel is compiled with
.Cd options LOCKDEBUG .
.It Ic show map Ns Oo Cm /f Oc Ar address
Print the vm_map at
.Ar address .
If
.Cm /f
is specified, the complete map is printed.
.It Ic show mount Ns Oo Cm /f Oc Ar address
Print the mount structure at
.Ar address .
If
.Cm /f
is specified, the complete vnode list is printed.
.It Ic show mbuf Ns Oo Cm /cdv Oc Ar address
Print the mbuf structure at
.Ar address .
Valid modifiers:
.Bl -tag -width 4n -compact
.It Cm /c
The mbufs in the chain are NOT followed.
.It Cm /d
The data is dumped.
.It Cm /v
Decode the mbuf chain as a packet.
It currently supports Ethernet, PPP, PPPoE, ARP, IPv4, ICMP, IPv6, ICMP6, TCP
and UDP.
.El
.It Ic show ncache Ar address
Dump the namecache list associated with vnode at
.Ar address .
.It Ic show object Ns Oo Cm /f Oc Ar address
Print the vm_object at
.Ar address .
If
.Cm /f
is specified, the complete object is printed.
.It Ic show page Ns Oo Cm /f Oc Ar address
Print the vm_page at
.Ar address .
If
.Cm /f
is specified, the complete page is printed.
.It Ic show panic
Print the current "panic" string.
.It Ic show pool Ns Oo Cm /clpsS Oc Ar address
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.
.It Cm /s
Print a short (one line) list per pool, showing the wait channel, pool
address, allocation size, alignment, allocated pages, allocated items,
consumed items, allocation requests, allocation frees, pages allocated,
pages freed, and currently idle pages, respectively.
.It Cm /S
Skip pools with zero allocations.
.El
.It Ic show proc Ns Oo Cm /ap Oc Ar address | pid
Show information about a process and its LWPs.
LWPs currently running on a CPU are marked with the '\&>' sign.
.Bl -tag -width 4n -compact
.It Cm /a
The argument passed is the kernel virtual address
of LWP structure.
.It Cm /p
The argument passed is a PID.
Note that
.Ar pid
is interpreted using the current radix (see
.Cm trace/t
command for details).
This is the default.
.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 socket Ns Oo Cm /ampv Oc
Print usage of system's socket buffers.
By default, empty sockets aren't printed.
.Bl -tag -width 4n -compact
.It Cm /a
Print all processes which use the socket.
.It Cm /m
Print mbuf chain in the socket buffer.
.It Cm /p
By default, a process which uses the socket is printed (only one socket).
If
.Cm /p
is specified, the process isn't printed.
.It Cm /v
Verbose mode.
If
.Cm /v
is specified, all sockets are printed.
.El
.It Ic show uvmexp
Print a selection of UVM counters and statistics.
.It Ic show kernhist Ns Oo Cm /i Oc Oo Ar addr Ns Oo , Ns Ar count Oc Oc
Dumps all the kernel histories if no address is specified, or the history
at the address.
If
.Cm /i
is specified, display information about the named history or all histories,
instead of history entries.
If
.Ar count
is specified, only the last
.Ar count
entries will be displayed.
Currently the
.Ar count
handling is only performed if a single history is requested.
This command is available only if a kernel is compiled with one or more
of the kernel history options
.Cd KERNHIST ,
.Cd SYSCALL_DEBUG ,
.Cd USB_DEBUG ,
.Cd BIOHIST ,
or
.Cd UVMHIST .
.It Ic show vmem Ar address
Print the vmem at
.Ar address .
.It Ic show vmems
Display all vmems.
.It Ic show vnode Ns Oo Cm /f Oc Ar address
Print the vnode at
.Ar address .
If
.Cm /f
is specified, the complete vnode is printed.
.It Ic show vnode_lock Ns Oo Cm /f Oc Ar address
Print the vnode which has its lock at
.Ar address .
If
.Cm /f
is specified, the complete vnode is printed.
.It Ic show watches
Display all watchpoints.
.It Ic sifting Ns Oo Cm /F Oc Ar string
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
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 Ic step Ns Oo Cm /p Oc Op , Ns Ar count
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
Sync the disks, force a crash dump, and then reboot.
.It Ic trace Ns Oo Cm /u Ns Oo Cm l Oc Oc Oo Ar frame-address Oc Ns \
Oo , Ns Ar count Oc
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 Ic trace/t Ns Oo Cm l Oc Oo Ar pid Oc Ns Oo , Ns Ar count Oc
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 trace/a Ns Oo Cm l Oc Oo Ar lwpaddr Oc Ns Oo , Ns Ar count Oc
Stack trace by light weight process (LWP) address
rather than by stack frame address.
If
.Cm /l
is specified, the trace is printed and also stored in the kernel
message buffer.
.Pp
Warning: trace by LWP address 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 Ic watch Ar address Ns Oo , Ns Ar size Oc
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 Ic whatis Ar address
Describe what an address is.
.It Ic write Ns Oo Cm /bhlqBHLQ Oc Ar address Ar expression Oo Ar expression ... Oc
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 ,
.Cm /l ,
and
.Cm /q .
If no modifier is specified,
.Cm /l
is used.
.Pp
Specifying the modifiers in upper case,
.Cm /B ,
.Cm /H ,
.Cm /L ,
.Cm /Q ,
will prevent
.Nm
from reading the memory location first, which is useful for avoiding
side effects when writing to I/O memory regions.
.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 Ic x Ns Oo Cm / Ns Ar modifier Oc Ar address Ns Op , Ns Ar count
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 AARCH64
.Bl -tag -width "traptrace" -compact
.It Ic break
Set or clear a hardware breakpoint.
.It Ic cpu
Switch to another CPU.
.It Ic cpuinfo
Print CPU information about the ``struct cpuinfo''.
.It Ic frame
Given a trap frame address, print out the trap frame.
.It Ic lwp
Print lwp information about the ``struct lwp''.
.It Ic pte
Print PTE information.
.It Ic reset
Reset the system.
.It Ic sysreg
Print system registers.
.It Ic watch
Set or clear a hardware watchpoint.
Pass the address to be watched, or watchpoint number to clear the watchpoint.
Optional modifiers are
.Dq r
for read access,
.Dq w
for write access (default: trap on read or write access),
.Dq b
for 8 bit width,
.Dq h
for 16 bit,
.Dq l
for 32 bit or,
.Dq q
for 64 bit (default: 32 bit).
.El
.Ss ALPHA
.Bl -tag -width "traptrace" -compact
.It Ic cpu
Switch to another CPU.
.\" .It Ic halt
.\" Call the PROM monitor to halt the CPU.
.\" .It Ic reboot
.\" Call the PROM monitor to reboot the CPU.
.El
.Ss AMD64
.Bl -tag -width "traptrace" -compact
.It Ic cpu
Switch to another CPU.
.El
.Ss ARM32
.Bl -tag -width "traptrace" -compact
.It Ic frame
Given a trap frame address, print out the trap frame.
.It Ic reset
Reset the system.
.El
.Ss HPPA
.Bl -tag -width "traptrace" -compact
.It Ic frame
Without an address the default trap frame is printed.
Otherwise, the trap frame address can be given, or, when the
.Dq l
modifier is used, an LWP address.
.El
.Ss I386
.Bl -tag -width "traptrace" -compact
.It Ic cpu
Switch to another CPU.
.El
.Ss IA64
.Bl -tag -width "traptrace" -compact
.It Ic vector
Without a vector, information about all 256 vectors is shown.
Otherwise, the given vector is shown.
.El
.Ss MIPS
.Bl -tag -width "traptrace" -compact
.It Ic cp0
Dump CP0 (coprocessor 0) register values.
.It Ic cpu
Switch to another CPU.
.It Ic kvtop
Print the physical address for a given kernel virtual address.
.\" .It Ic mfcr -- document this!
.\" .It Ic mtcr -- document this!
.It Ic nmi
Send an NMI to a different CPU.
This DDB command is currently only implemented for Cavium
Octeon CPUs.
.It Ic reset
Reset the system.
Not implemented for many CPUs and/or systems.
.It Ic tlb
Print out the Translation Lookaside Buffer (TLB).
Use the
.Cm /v
modifier to show only valid TLB entries.
.It Ic watch
Set a hardware watchpoint on an address or a TLB ASID.
Pass the address to be watched.
If no address is specified, show a list of active watchpoints.
The modifiers are
.Cm /m
i for trap on an instruction fetch,
.Cm /r
for trap on a read,
.Cm /w
for trap on a write,
.Cm /m
for a mask on the address to match,
.Cm /a
for trap on a TLB ASID match.
The
.Cm /m
and
.Cm /a
modifiers require an extra argument for the mask and ASID respectively.
.It Ic unwatch
Clear a hardware watchpoint.
If an address is specified, clear watchpoints that match that address.
If no address is specified, clear all watchpoints.
.El
.Ss POWERPC 4xx
.Bl -tag -width "traptrace" -compact
.It Ic ctx
Print process MMU context information.
.It Ic pv
Print PA->VA mapping information.
.It Ic reset
Reset the system.
.It Ic tf
Display the contents of the trapframe.
.It Ic tlb
Display instruction translation storage buffer information.
.It Ic dcr
Set the DCR register.
Must be between 0x00 and 0x3ff.
.It Ic user
Display user memory.
Use the
.Dq i
modifier to get instruction decoding.
.El
.Ss POWERPC OEA
.Bl -tag -width "traptrace" -compact
.It Ic bat
Print BAT registers and translations.
.It Ic mmu
Print MMU registers.
.El
.Ss SH3
.Bl -tag -width "traptrace" -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 "traptrace" -compact
.It Ic cpu
Switch to another CPU.
.It Ic prom
Enter the Sun PROM monitor.
.It Ic proc
Display some information about the LWP pointed to, or curlwp.
.It Ic pcb
Display information about the
.Dq struct pcb
listed.
.It Ic page
Display the pointer to the
.Dq struct vm_page
for this physical address.
.El
.Ss SPARC64
.Bl -tag -width "traptrace" -compact
.It Ic ctx
Print process context information.
.It Ic cpu
Switch to another CPU.
.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 extract
Extract the physical address for a given virtual address from the kernel pmap.
.It Ic fpstate
Dump the FPU state.
.It Ic itlb
Print instruction translation look-aside buffer context information.
.It Ic itsb
Display instruction translation storage buffer information.
.It Ic lwp
Display a struct lwp
.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 sir
Reset the machine and enter prom (do a Software Initiated Reset).
.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 watch
Set or clear a physical or virtual hardware watchpoint.
Pass the address to be watched, or
.Dq 0
(or omit the address) to clear the watchpoint.
Optional modifiers are
.Dq p
for physical address,
.Dq r
for trap on read access (default: trap on write access only),
.Dq b
for 8 bit width,
.Dq h
for 16 bit,
.Dq l
for 32 bit or
.Dq L
for 64 bit.
.It Ic window
Print register window information.
Argument is a stack frame number (0 is
top of stack, which is used when no index is given).
.El
.Ss SUN2, SUN3 and SUN3X
.Bl -tag -width "traptrace" -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
.Ss VAX
.Bl -tag -width "traptrace" -compact
.It Ic cpu
Switch to another CPU.
.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 dumpstack
If non-zero (the default),
causes a stack trace to be printed when
.Nm
is entered on panic.
.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 lines
The number of lines.
This is used by the
.Ic more
feature.
When this variable is set to zero the
.Ic more
feature is disabled.
.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.
.Nm
wraps the current line by printing new line when
.Va maxwidth
column is reached.
When this variable is set to zero
.Nm
doesn't perform any wrapping.
.It Va onpanic
If greater than zero (the default is 1),
.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, causing a stack trace to be printed and
the system to be rebooted instead of
.Nm
being entered.
Setting
.Va onpanic
to \-1 suppresses the stack trace before reboot.
.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
which will initialize
.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 panicstackframes
Number of stack frames to display on panic.
Useful to avoid scrolling away the interesting frames on a glass tty.
Default value is
.Dv 65535
(all frames), useful value around
.Dv 10 .
.\" .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
.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 crash 8 ,
.Xr reboot 8 ,
.Xr sysctl 8 ,
.Xr cnmagic 9 ,
.Xr ddb 9
.Sh HISTORY
The
.Nm
kernel debugger was written as part of the MACH project at
Carnegie-Mellon University.