diff options
Diffstat (limited to 'static/netbsd/man4/ddb.4')
| -rw-r--r-- | static/netbsd/man4/ddb.4 | 1739 |
1 files changed, 1739 insertions, 0 deletions
diff --git a/static/netbsd/man4/ddb.4 b/static/netbsd/man4/ddb.4 new file mode 100644 index 00000000..d88f2aeb --- /dev/null +++ b/static/netbsd/man4/ddb.4 @@ -0,0 +1,1739 @@ +.\" $NetBSD: ddb.4,v 1.206 2026/03/21 16:44:03 uwe 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 March 15, 2026 +.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 +.Ar command Ns Op Cm / Ns Ar modifiers +.Ar address Ns 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 "<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 Xo +.Ar address Ns Oo +.Cm ( Ns +.Ar expression Ns +.Oo Cm \&, Ns Ar ... Oc Ns +.Cm ) +.Oc +.Xc +. +A synonym for +.Ic call . +. +.It Ic break Ns Xo +.Oo Cm /u Oc +.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 Ic bt Ns Xo +.Oo Cm /ul Oc +.Oo Ar frame-address Oc Ns +.Oo Cm \&, Ns Ar count Oc +.Xc +. +A synonym for +.Ic trace . +. +.It Ic bt/t Ns Xo +.Oo Cm /ul Oc +.Oo Ar pid Oc Ns +.Oo Cm \& , Ns Ar count Oc +.Xc +. +A synonym for +.Ic trace/t . +. +.It Ic bt/a Ns Xo +.Oo Cm /ul Oc +.Oo Ar lwpaddr Oc Ns +.Oo Cm \&, Ns Ar count Oc +.Xc +. +A synonym for +.Ic trace/a . +. +.It Ic call Xo +.Ar address Ns Oo +.Cm ( Ns +.Ar expression Ns +.Oo Cm \&, Ns Ar ... Oc Ns +.Cm ) +.Oc +.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 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 +.Ql \&# . +. +.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 Xo +.Oo Cm / Ns Ar modifier Oc +.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 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 Cm \&, 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 Xo +.Oo Cm /a Oc Ns +.Oo Cm /n Oc Ns +.Oo Cm /w Oc Ns +.Oo Cm /l Oc Ns +.Oo Cm /L Oc Ns +.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 Ic search Ns Xo +.Oo Cm /bhl Oc +.Ar address +.Ar value +.Oo Ar mask Oc \" XXX: uwe: space allowed/required? +.Oo Cm \& , Ns Ar count Oc +.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 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 Xo +.Oo Cm /a Oc Ns +.Oo Cm /n Oc Ns +.Oo Cm /w Oc Ns +.Oo Cm /l Oc Ns +.Oo Cm /L Oc Ns +.Xc +. +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. +.It Cm /L +In addition to what +.Cm /l +shows, print the stack trace of each LWPs. +.El +. +.It Ic show all tstiles Ns Op Cm /t +. +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 Xo +.Oo Cm /f Oc Ns +.Oo Cm /i Oc Ns +.Oo Cm /m Oc Ns +.Oo Cm /t Oc Ns +.Xc +. +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 Op Cm /ampv +. +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 Xo +.Oo Cm /i Oc +.Oo Ar address Ns Oo Cm \&, Ns Ar count Oc Oc +.Xc +. +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 Xo +.Oo Cm /p Oc +.\" NB: no address +.Oo Cm \&, Ns Ar count Oc +.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 +. +Sync the disks, force a crash dump, and then reboot. +. +.It Ic trace Ns Xo +.Oo Cm /u Ns Oo Cm l Oc Oc +.Oo Ar frame-address Oc Ns +.Oo Cm \&, Ns Ar count Oc +.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 Ic trace/t Ns Xo +.Oo Cm l Oc +.Oo Ar pid Oc Ns +.Oo Cm \&, Ns Ar count Oc +.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 trace/a Ns Xo +.Oo Cm l Oc +.Oo Ar lwpaddr Oc Ns +.Oo Cm \&, Ns Ar count Oc +.Xc +. +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 Op Cm \&, Ns Ar size +. +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 Xo +.Oo Cm /bhlqBHLQ Oc +.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 , +.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 Xo +.Oo Cm / Ns Ar modifier Oc +.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 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. |