Annotation of src/share/man/man4/ddb.4, Revision 1.189
1.189 ! maya 1: .\" $NetBSD: ddb.4,v 1.188 2019/12/15 20:29:08 joerg Exp $
1.15 lukem 2: .\"
1.188 joerg 3: .\" Copyright (c) 1997 - 2019 The NetBSD Foundation, Inc.
1.15 lukem 4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by Luke Mewburn
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28: .\" POSSIBILITY OF SUCH DAMAGE.
29: .\"
30: .\" ---
31: .\" This manual page was derived from a -man.old document which bore
32: .\" the following copyright message:
33: .\" ---
1.5 jtc 34: .\"
1.1 brezak 35: .\" Mach Operating System
36: .\" Copyright (c) 1991,1990 Carnegie Mellon University
37: .\" All Rights Reserved.
1.52 wiz 38: .\"
1.1 brezak 39: .\" Permission to use, copy, modify and distribute this software and its
40: .\" documentation is hereby granted, provided that both the copyright
41: .\" notice and this permission notice appear in all copies of the
42: .\" software, derivative works or modified versions, and any portions
43: .\" thereof, and that both notices appear in supporting documentation.
1.52 wiz 44: .\"
1.1 brezak 45: .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
46: .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
47: .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
1.52 wiz 48: .\"
1.1 brezak 49: .\" Carnegie Mellon requests users of this software to return to
1.52 wiz 50: .\"
1.1 brezak 51: .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
52: .\" School of Computer Science
53: .\" Carnegie Mellon University
54: .\" Pittsburgh PA 15213-3890
1.52 wiz 55: .\"
1.1 brezak 56: .\" any improvements or extensions that they make and grant Carnegie Mellon
57: .\" the rights to redistribute these changes.
1.15 lukem 58: .\"
1.189 ! maya 59: .Dd March 30, 2020
1.15 lukem 60: .Dt DDB 4
1.32 garbled 61: .Os
1.15 lukem 62: .Sh NAME
63: .Nm ddb
64: .Nd in-kernel debugger
65: .Sh SYNOPSIS
66: .Cd options DDB
67: .Pp
68: To enable history editing:
69: .Cd options DDB_HISTORY_SIZE=integer
70: .Pp
71: To disable entering
1.64 wiz 72: .\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS
73: .Ic ddb
1.15 lukem 74: upon kernel panic:
75: .Cd options DDB_ONPANIC=0
1.79 reinoud 76: .Pp
77: To enable teeing all
78: .\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS
79: .Ic ddb
80: output to the kernel msgbuf:
81: .Cd options DDB_TEE_MSGBUF=1
1.82 yamt 82: .Pp
83: To specify commands which will be executed on each entry to
84: .Ic ddb :
85: .Cd options DDB_COMMANDONENTER="trace;show registers"
1.83 wiz 86: In this case, "trace" and then "show registers" will be executed automatically.
1.104 martin 87: .Pp
88: To enable extended online help:
89: .Cd options DDB_VERBOSE_HELP .
1.15 lukem 90: .Sh DESCRIPTION
91: .Nm
92: is the in-kernel debugger.
93: It may be entered at any time via a special key sequence, and
94: optionally may be invoked when the kernel panics.
1.21 fair 95: .Sh ENTERING THE DEBUGGER
96: Unless
97: .Dv DDB_ONPANIC
98: is set to 0,
99: .Nm
100: will be activated whenever the kernel would otherwise panic.
101: .Pp
102: .Nm
103: may also be activated from the console.
104: In general, sending a break on a serial console will activate
1.60 wiz 105: .Nm .
1.21 fair 106: There are also key sequences for each port that will activate
107: .Nm
108: from the keyboard:
1.144 jym 109: .Bl -tag -offset indent -width "xen domU" -compact
1.21 fair 110: .It alpha
1.167 wiz 111: <Ctrl>-<Alt>-<Esc> on PC style keyboards.
1.110 tron 112: .It amd64
1.167 wiz 113: <Ctrl>-<Alt>-<Esc>
1.125 joerg 114: .It ""
1.167 wiz 115: <Break> on serial console.
1.21 fair 116: .It amiga
1.167 wiz 117: <LAlt>-<LAmiga>-<F10>
1.27 leo 118: .It atari
1.167 wiz 119: <Alt>-<LeftShift>-<F9>
1.185 rin 120: .It evbarm
121: <Ctrl>-<Alt>-<Esc> on PC style keyboards.
122: .It ""
123: <Break> on serial console.
124: .It ""
125: Some models:
126: +++++
127: (five plus signs) on serial console.
1.21 fair 128: .It hp300
1.167 wiz 129: <Shift>-<Reset>
1.155 skrll 130: .It hpcarm
1.167 wiz 131: <Ctrl>-<Alt>-<Esc>
1.155 skrll 132: .It hpcmips
1.167 wiz 133: <Ctrl>-<Alt>-<Esc>
1.155 skrll 134: .It hpcsh
1.167 wiz 135: <Ctrl>-<Alt>-<Esc>
1.155 skrll 136: .It hppa
1.167 wiz 137: <Ctrl>-<Alt>-<Esc> on PC style keyboards.
1.148 skrll 138: .It ""
1.100 skrll 139: +++++
1.148 skrll 140: (five plus signs) on PDC console
1.125 joerg 141: .It ""
1.167 wiz 142: <Break> on serial console.
1.21 fair 143: .It i386
1.167 wiz 144: <Ctrl>-<Alt>-<Esc>
1.125 joerg 145: .It ""
1.167 wiz 146: <Break> on serial console.
1.21 fair 147: .It mac68k
1.167 wiz 148: <Command>-<Power>, or the Interrupt switch.
1.62 wiz 149: .It macppc
150: Some models:
1.167 wiz 151: <Command>-<Option>-<Power>
1.21 fair 152: .It mvme68k
153: Abort switch on CPU card.
154: .It pmax
1.169 wiz 155: <Do> on LK-201 rcons console.
1.125 joerg 156: .It ""
1.167 wiz 157: <Break> on serial console.
1.157 phx 158: .It sandpoint
1.167 wiz 159: <Break> on serial console.
1.21 fair 160: .It sparc
1.169 wiz 161: <L1>-A, or <Stop>-A on a Sun keyboard.
1.125 joerg 162: .It ""
1.167 wiz 163: <Break> on serial console.
1.78 jdc 164: .It sparc64
1.169 wiz 165: <L1>-A, or <Stop>-A on a Sun keyboard.
1.125 joerg 166: .It ""
1.167 wiz 167: <Break> on serial console.
1.78 jdc 168: .It sun3
1.169 wiz 169: <L1>-A, or <Stop>-A on a Sun keyboard.
1.125 joerg 170: .It ""
1.167 wiz 171: <Break> on serial console.
1.76 wiz 172: .It vax
1.167 wiz 173: <Esc>-<Shift>-D on serial console.
1.26 msaitoh 174: .It x68k
175: Interrupt switch on the body.
1.145 jym 176: .It xen dom0
1.167 wiz 177: <Ctrl>-<Alt>-<Esc> on PC style keyboards.
1.145 jym 178: .It ""
179: +++++
180: (five plus signs) on serial console.
1.144 jym 181: .It xen domU
1.94 hubertf 182: +++++
1.145 jym 183: (five plus signs) on serial console.
1.119 ober 184: .It zaurus
1.167 wiz 185: <Ctrl>-<Alt>-<Esc>
1.21 fair 186: .El
1.23 fair 187: .Pp
1.77 wiz 188: The key sequence to activate
189: .Nm
190: can be changed by modifying
191: .Dq hw.cnmagic
192: with
193: .Xr sysctl 8 .
194: If the console is not dedicated to
195: .Nm
196: the sequence should not be easily typed by accident.
1.21 fair 197: In addition,
198: .Nm
199: may be explicitly activated by the debugging code in the kernel
200: if
201: .Cm DDB
202: is configured.
1.149 sborrill 203: .Pp
204: Commands can be automatically run when
205: .Nm
206: is entered by using
207: .Cd options DDB_COMMANDONENTER
208: or by setting
209: .Ar ddb.commandonenter
210: with
211: .Xr sysctl 8 .
212: Multiple commands can be separated by a semi-colon.
1.21 fair 213: .Sh COMMAND SYNTAX
214: The general command syntax is:
215: .Bd -ragged -offset indent
1.172 wiz 216: .Ic command Ns Op / Ns Ar modifier
1.21 fair 217: .Ar address
1.172 wiz 218: .Op , Ns Ar count
1.21 fair 219: .Ed
1.15 lukem 220: .Pp
221: The current memory location being edited is referred to as
222: .Ar dot ,
223: and the next location is
224: .Ar next .
225: They are displayed as hexadecimal numbers.
226: .Pp
227: Commands that examine and/or modify memory update
228: .Ar dot
229: to the address of the last line examined or the last location
230: modified, and set
231: .Ar next
232: to the next location to be examined or modified.
233: Other commands don't change
234: .Ar dot ,
235: and set
236: .Ar next
237: to be the same as
238: .Ar dot .
239: .Pp
240: A blank line repeats the previous command from the address
241: .Ar next
1.39 jhawk 242: with the previous
1.15 lukem 243: .Cm count
1.39 jhawk 244: and no modifiers.
1.15 lukem 245: Specifying
246: .Cm address
247: sets
248: .Em dot
249: to the address.
1.52 wiz 250: If
1.15 lukem 251: .Cm address
252: is omitted,
253: .Em dot
254: is used.
255: A missing
256: .Cm count
257: is taken to be 1 for printing commands, and infinity for stack traces.
1.39 jhawk 258: .Pp
259: The syntax:
260: .Bd -ragged -offset indent
1.177 wiz 261: .Cm \&, Ns Ar count
1.39 jhawk 262: .Ed
263: .Pp
264: repeats the previous command, just as a blank line does, but with
265: the specified
266: .Cm count .
1.15 lukem 267: .Pp
268: .Nm
269: has a
1.68 wiz 270: .Xr more 1 Ns -like
1.15 lukem 271: functionality; if a number of lines in a command's output exceeds the number
272: defined in the
273: .Va lines
274: variable, then
275: .Nm
276: displays
277: .Dq "--db more--"
278: and waits for a response, which may be one of:
1.167 wiz 279: .Bl -tag -offset indent -width "<return>"
1.85 wiz 280: .It Aq return
1.15 lukem 281: one more line.
1.85 wiz 282: .It Aq space
1.15 lukem 283: one more page.
1.52 wiz 284: .It Ic q
1.1 brezak 285: abort the current command, and return to the command input mode.
1.15 lukem 286: .El
287: .Pp
1.103 uwe 288: You can set
289: .Va lines
290: variable to zero to disable this feature.
291: .Pp
1.52 wiz 292: If
1.15 lukem 293: .Nm
294: history editing is enabled (by defining the
295: .D1 Cd options DDB_HISTORY_SIZE=num
296: kernel option), then a history of the last
297: .Cm num
298: commands is kept.
299: The history can be manipulated with the following key sequences:
1.167 wiz 300: .Bl -tag -offset indent -width "<Ctrl>-P"
301: .It <Ctrl>-P
1.15 lukem 302: retrieve previous command in history (if any).
1.167 wiz 303: .It <Ctrl>-N
1.15 lukem 304: retrieve next command in history (if any).
305: .El
306: .Sh COMMANDS
307: .Nm
308: supports the following commands:
309: .Bl -tag -width 5n
1.172 wiz 310: .It Ic \&! Ns Ar address Ns Oo ( Ar expression Ns Oo Ar ,... Oc ) Oc
1.44 jhawk 311: A synonym for
312: .Ic call .
1.172 wiz 313: .It Ic break Ns Oo Cm /u Oc Ar address Ns Op , Ns Ar count
1.44 jhawk 314: Set a breakpoint at
315: .Ar address .
316: If
317: .Ar count
318: is supplied, continues
1.143 wiz 319: .Pq Ar count Ns \-1
1.44 jhawk 320: times before stopping at the breakpoint.
321: If the breakpoint is set, a breakpoint number is printed with
322: .Sq \&# .
323: This number can be used to
324: .Ic delete
325: the breakpoint, or to add
326: conditions to it.
327: .Pp
328: If
329: .Cm /u
330: is specified,
331: set a breakpoint at a user-space address.
332: Without
333: .Cm /u ,
334: .Ar address
335: is considered to be in the kernel-space, and an address in the wrong
336: space will be rejected, and an error message will be emitted.
337: This modifier may only be used if it is supported by machine dependent
338: routines.
339: .Pp
340: Warning: if a user text is shadowed by a normal user-space debugger,
341: user-space breakpoints may not work correctly.
342: Setting a breakpoint at the low-level code paths may also cause
343: strange behavior.
1.172 wiz 344: .It Ic bt Ns Oo Cm /ul Oc Oo Ar frame-address Oc Ns Oo , Ns Ar count Oc
1.59 jmc 345: A synonym for
346: .Ic trace .
1.172 wiz 347: .It Ic bt/t Ns Oo Cm /ul Oc Oo Ar pid Oc Ns Oo , Ns Ar count Oc
1.59 jmc 348: A synonym for
1.98 mrg 349: .Ic trace/t .
1.172 wiz 350: .It Ic bt/a Ns Oo Cm /ul Oc Oo Ar lwpaddr Oc Ns Oo , Ns Ar count Oc
1.99 ad 351: A synonym for
352: .Ic trace/a .
1.172 wiz 353: .It Ic call Ar address Ns Oo ( Ns Ar expression Ns Oo Ar ,... Oc ) Oc
1.44 jhawk 354: Call the function specified by
355: .Ar address
356: with the argument(s) listed in parentheses.
357: Parentheses may be omitted if the function takes no arguments.
358: The number of arguments is currently limited to 10.
359: .It Ic continue Ns Op Cm /c
360: Continue execution until a breakpoint or watchpoint.
361: If
362: .Cm /c
363: is specified, count instructions while executing.
364: Some machines (e.g., pmax) also count loads and stores.
365: .Pp
366: Warning: when counting, the debugger is really silently
367: single-stepping.
368: This means that single-stepping on low-level may cause strange
369: behavior.
1.125 joerg 370: .It Ic delete Ar "address" | Cm # Ns Ar number
1.44 jhawk 371: Delete a breakpoint.
372: The target breakpoint may be specified by
373: .Ar address ,
374: as per
375: .Ic break ,
376: or by the breakpoint number returned by
377: .Ic break
378: if it's prefixed with
379: .Sq Cm \&# .
1.125 joerg 380: .It Ic dmesg Op Ar count
1.65 atatat 381: Prints the contents of the kernel message buffer.
1.69 simonb 382: The optional
383: .Ar count
384: argument will limit printing to at most the last
385: .Ar count
386: bytes of the message buffer.
1.125 joerg 387: .It Ic dwatch Ar address
1.44 jhawk 388: Delete the watchpoint at
389: .Ar address
390: that was previously set with
391: .Ic watch
392: command.
1.172 wiz 393: .It Ic examine Ns Oo Cm / Ns Ar modifier Oc Ar address Ns Op , Ns Ar count
1.52 wiz 394: Display the address locations according to the format in
1.15 lukem 395: .Ar modifier .
1.1 brezak 396: Multiple modifier formats display multiple locations.
1.15 lukem 397: If
398: .Ar modifier
399: isn't specified, the modifier from the last use of
400: .Ic examine
1.1 brezak 401: is used.
1.15 lukem 402: .Pp
403: The valid format characters for
404: .Ar modifier
405: are:
1.44 jhawk 406: .Bl -tag -offset indent -width 2n -compact
1.15 lukem 407: .It Cm b
408: examine bytes (8 bits).
409: .It Cm h
410: examine half-words (16 bits).
411: .It Cm l
1.35 ross 412: examine words (legacy
413: .Dq long ,
414: 32 bits).
1.187 ryo 415: .It Cm q
416: examine quad-words (64 bits).
1.35 ross 417: .It Cm L
418: examine long words (implementation dependent)
1.15 lukem 419: .It Cm a
420: print the location being examined.
421: .It Cm A
422: print the location with a line number if possible.
423: .It Cm x
424: display in unsigned hex.
425: .It Cm z
426: display in signed hex.
427: .It Cm o
428: display in unsigned octal.
429: .It Cm d
430: display in signed decimal.
431: .It Cm u
432: display in unsigned decimal.
433: .It Cm r
434: display in current radix, signed.
435: .It Cm c
1.1 brezak 436: display low 8 bits as a character.
1.15 lukem 437: Non-printing characters as displayed as an octal escape code
438: (e.g.,
439: .Sq \e000 ) .
440: .It Cm s
441: display the NUL terminated string at the location.
1.1 brezak 442: Non-printing characters are displayed as octal escapes.
1.15 lukem 443: .It Cm m
444: display in unsigned hex with a character dump at the end of each line.
445: The location is displayed as hex at the beginning of each line.
1.186 ryo 446: .It Cm p
447: display as a pointer and it's symbol if possible.
1.15 lukem 448: .It Cm i
449: display as a machine instruction.
450: .It Cm I
451: display as a machine instruction, with possible alternative formats
452: depending upon the machine:
1.44 jhawk 453: .Bl -tag -offset indent -width "sparc" -compact
1.25 drochner 454: .It alpha
455: print register operands
456: .It m68k
457: use Motorola syntax
1.15 lukem 458: .It vax
459: don't assume that each external label is a procedure entry mask
460: .El
461: .El
1.172 wiz 462: .It Ic kill Ar pid Ns Op , Ns Ar signal_number
1.44 jhawk 463: Send a signal to the process specified by the
464: .Ar pid .
465: Note that
466: .Ar pid
467: is interpreted using the current radix (see
468: .Cm trace/t
469: command for details).
470: If
471: .Ar signal_number
472: isn't specified, the SIGTERM signal is sent.
473: .It Ic match Ns Op Cm /p
1.15 lukem 474: A synonym for
1.44 jhawk 475: .Ic next .
476: .It Ic next Ns Op Cm /p
477: Stop at the matching return instruction.
478: If
479: .Cm /p
480: is specified, print the call nesting depth and the
481: cumulative instruction count at each call or return.
482: Otherwise, only print when the matching return is hit.
1.125 joerg 483: .It Ic print Ns Oo Cm /axzodurc Oc Ar address Op Ar address ...
1.15 lukem 484: Print addresses
485: .Ar address
486: according to the modifier character, as per
487: .Ic examine .
488: Valid modifiers are:
489: .Cm /a ,
490: .Cm /x ,
491: .Cm /z ,
492: .Cm /o ,
493: .Cm /d ,
494: .Cm /u ,
495: .Cm /r ,
496: and
497: .Cm /c
498: (as per
499: .Ic examine ) .
500: If no modifier is specified, the most recent one specified is used.
501: .Ar address
502: may be a string, and is printed
503: .Dq as-is .
504: For example:
505: .Bd -literal -offset indent
506: print/x "eax = " $eax "\enecx = " $ecx "\en"
507: .Ed
508: .Pp
509: will produce:
510: .Bd -literal -offset indent
1.1 brezak 511: eax = xxxxxx
512: ecx = yyyyyy
1.15 lukem 513: .Ed
1.125 joerg 514: .It Ic ps Ns Oo Cm /a Oc Ns Oo Cm /n Oc Ns Oo Cm /w Oc Ns Oo Cm /l Oc
1.44 jhawk 515: A synonym for
1.85 wiz 516: .Ic show all procs .
1.44 jhawk 517: .It Ic reboot Op Ar flags
518: Reboot, using the optionally supplied boot
1.73 lukem 519: .Ar flags ,
1.81 fredb 520: which is a bitmask supporting the same values as for
521: .Xr reboot 2 .
522: Some of the more useful flags:
1.87 uwe 523: .Bl -column "Value" "RB_POWERDOWN" "Description"
1.73 lukem 524: .It Sy "Value" Ta Sy "Name" Ta Sy "Description"
525: .It 0x1 Ta RB_ASKNAME Ta Ask for file name to reboot from
526: .It 0x2 Ta RB_SINGLE Ta Reboot to single user mode
527: .It 0x4 Ta RB_NOSYNC Ta Don't sync before reboot
528: .It 0x8 Ta RB_HALT Ta Halt instead of reboot
529: .It 0x40 Ta RB_KDB Ta Boot into kernel debugger
1.81 fredb 530: .It 0x100 Ta RB_DUMP Ta Dump unconditionally before reboot
1.73 lukem 531: .It 0x808 Ta RB_POWERDOWN Ta Power off (or at least halt)
532: .El
1.44 jhawk 533: .Pp
534: Note: Limitations of the command line interface preclude
535: specification of a boot string.
1.125 joerg 536: .It Ic search Ns Oo Cm /bhl Oc Ar address Ar value \
1.172 wiz 537: Oo Ar mask Oc Oo , Ns Ar count Oc
1.44 jhawk 538: Search memory from
539: .Ar address
540: for
541: .Ar value .
1.15 lukem 542: The unit size is specified with a modifier character, as per
543: .Ic examine .
544: Valid modifiers are:
545: .Cm /b ,
546: .Cm /h ,
547: and
548: .Cm /l .
549: If no modifier is specified,
550: .Cm /l
551: is used.
552: .Pp
1.44 jhawk 553: This command might fail in interesting ways if it doesn't find
554: .Ar value .
555: This is because
556: .Nm
557: doesn't always recover from touching bad memory.
558: The optional
559: .Ar count
560: limits the search.
1.125 joerg 561: .It Ic set Cm $ Ns Ar variable Oo Cm = Oc Ar expression
1.15 lukem 562: Set the named variable or register to the value of
563: .Ar expression .
564: Valid variable names are described in
565: .Sx VARIABLES .
1.102 pooka 566: .It Ic show all callout
567: Display information about callouts in the system.
568: See
569: .Xr callout 9
570: for more information on callouts.
1.176 ozaki-r 571: .It Ic show all locks Ns Op Cm /t
572: Display details information about all active locks.
573: If
574: .Cm /t
1.177 wiz 575: is specified, stack traces of LWPs holding locks are also printed.
576: This command is only useful if a kernel is compiled with
1.176 ozaki-r 577: .Cd options LOCKDEBUG .
1.188 joerg 578: .It Ic show all mount Ns Op Cm /f
579: Display all mount points.
580: If
581: .Cm /f
582: is specified, the complete vnode list is printed.
1.91 bjh21 583: .It Ic show all pages
584: Display basic information about all physical pages managed by the VM system.
585: For more detailed information about a single page, use
586: .Ic show page .
1.85 wiz 587: .It Ic show all pools Ns Op Cm /clp
1.84 yamt 588: Display all pool information.
1.89 wiz 589: Modifiers are the same as
1.85 wiz 590: .Ic show pool .
1.125 joerg 591: .It Ic "show\ all\ procs" Ns Oo Cm /a Oc Ns Oo Cm /n Oc Ns Oo Cm /w Oc Ns \
592: Oo Cm /l Oc
1.44 jhawk 593: Display all process information.
594: Valid modifiers:
595: .Bl -tag -width 3n
596: .It Cm /n
597: show process information in a
598: .Xr ps 1
1.122 ad 599: style format.
1.44 jhawk 600: Information printed includes: process ID, parent process ID,
1.146 jym 601: process group, UID, process status, process flags, number of LWPs,
1.44 jhawk 602: command name, and process wait channel message.
603: .It Cm /a
1.146 jym 604: show each process ID, command name, kernel virtual addresses of
605: each process' proc structure, u-area, and vmspace structure.
1.44 jhawk 606: The vmspace address is also the address of the process'
607: vm_map structure, and can be used in the
1.85 wiz 608: .Ic show map
1.44 jhawk 609: command.
610: .It Cm /w
1.146 jym 611: show each LWP ID, process ID, command name, system call emulation,
612: priority, wait channel message and wait channel address.
613: LWPs currently running on a CPU are marked with the '\&>' sign.
1.96 oster 614: .It Cm /l
1.146 jym 615: show each LWP ID, process ID, process status, CPU ID the LWP runs on,
616: process flags, kernel virtual address of LWP structure,
1.147 jym 617: LWP name and wait channel message.
1.146 jym 618: LWPs currently running on a CPU are marked with the '\&>' sign.
1.122 ad 619: This is the default.
1.44 jhawk 620: .El
1.161 ozaki-r 621: .It Ic show routes
1.102 pooka 622: Dump the entire
623: .Dv AF_INET
624: routing table.
1.161 ozaki-r 625: This command is available only on systems which support inet.
1.85 wiz 626: .It Ic show breaks
1.50 jhawk 627: Display all breakpoints.
1.125 joerg 628: .It Ic show buf Ns Oo Cm /f Oc Ar address
1.50 jhawk 629: Print the struct buf at
630: .Ar address .
631: The
632: .Cm /f
633: does nothing at this time.
1.126 mrg 634: .It Ic show event Ns Oo Cm /f Oc Ns Oo Cm /i Oc Ns Oo Cm /m Oc Ns \
635: Oo Cm /t Oc
1.57 simonb 636: Print all the non-zero
637: .Xr evcnt 9
638: event counters.
1.126 mrg 639: Valid modifiers:
640: .Bl -tag -width 3n
641: .It Cm /f
642: event counters with a count of zero are printed as well.
643: .It Cm /i
644: interrupted counters will be displayed.
645: .It Cm /m
1.127 wiz 646: misc counters will be displayed.
1.126 mrg 647: .It Cm /t
1.127 wiz 648: trap counters will be displayed.
1.126 mrg 649: .El
650: .Pp
651: If none of
652: .Cm /i ,
1.172 wiz 653: .Cm /m ,
1.126 mrg 654: or
655: .Cm /t
656: are specified, all are shown.
657: You can combine any of these.
658: For example, the modifier
659: .Cm /itf
660: will select both interrupt and trap events, including those that are non-zero.
1.125 joerg 661: .It Ic show files Ar address
1.115 blymn 662: Display information about the vnodes of the files that are currently
663: open by the process associated with the proc structure at
664: .Ar address .
665: This address can be found using the
666: .Ic show all procs /a
667: command.
668: If the kernel is compiled with
669: .Cd options LOCKDEBUG
670: then details about the locking of the underlying uvm object will also
671: be displayed.
1.125 joerg 672: .It Ic show lock Ar address
1.102 pooka 673: Display information about a lock at
674: .Ar address .
1.177 wiz 675: This command is only useful if a kernel is compiled with
1.102 pooka 676: .Cd options LOCKDEBUG .
1.178 ozaki-r 677: .It Ic show lockstats
1.177 wiz 678: Display information about lock statistics.
679: This command is only useful if a kernel is compiled with
1.175 ozaki-r 680: .Cd options LOCKDEBUG .
1.125 joerg 681: .It Ic show map Ns Oo Cm /f Oc Ar address
1.44 jhawk 682: Print the vm_map at
683: .Ar address .
684: If
685: .Cm /f
1.50 jhawk 686: is specified, the complete map is printed.
1.125 joerg 687: .It Ic show mount Ns Oo Cm /f Oc Ar address
1.74 dbj 688: Print the mount structure at
689: .Ar address .
690: If
691: .Cm /f
692: is specified, the complete vnode list is printed.
1.179 msaitoh 693: .It Ic show mbuf Ns Oo Cm /cdv Oc Ar address
1.90 yamt 694: Print the mbuf structure at
695: .Ar address .
1.179 msaitoh 696: Valid modifiers:
697: .Bl -tag -width 4n -compact
698: .It Cm /c
1.184 msaitoh 699: The mbufs in the chain are NOT followed.
1.179 msaitoh 700: .It Cm /d
701: The data is dumped.
702: .It Cm /v
703: Decode the mbuf chain as a packet.
704: It currently supports Ethernet, PPP, PPPoE, ARP, IPv4, ICMP, IPv6, ICMP6, TCP
705: and UDP.
706: .El
1.85 wiz 707: .It Ic show ncache Ar address
1.50 jhawk 708: Dump the namecache list associated with vnode at
709: .Ar address .
1.125 joerg 710: .It Ic show object Ns Oo Cm /f Oc Ar address
1.44 jhawk 711: Print the vm_object at
1.15 lukem 712: .Ar address .
713: If
1.44 jhawk 714: .Cm /f
1.50 jhawk 715: is specified, the complete object is printed.
1.125 joerg 716: .It Ic show page Ns Oo Cm /f Oc Ar address
1.50 jhawk 717: Print the vm_page at
718: .Ar address .
719: If
720: .Cm /f
721: is specified, the complete page is printed.
1.151 christos 722: .It Ic show panic
723: Print the current "panic" string.
1.125 joerg 724: .It Ic show pool Ns Oo Cm /clp Oc Ar address
1.50 jhawk 725: Print the pool at
726: .Ar address .
727: Valid modifiers:
728: .Bl -tag -width 4n -compact
729: .It Cm /c
730: Print the cachelist and its statistics for this pool.
731: .It Cm /l
732: Print the log entries for this pool.
733: .It Cm /p
734: Print the pagelist for this pool.
735: .El
1.146 jym 736: .It Ic show proc Ns Oo Cm /ap Oc Ar address | pid
737: Show information about a process and its LWPs.
738: LWPs currently running on a CPU are marked with the '\&>' sign.
739: .Bl -tag -width 4n -compact
740: .It Cm /a
741: The argument passed is the kernel virtual address
742: of LWP structure.
743: .It Cm /p
744: The argument passed is a PID.
745: Note that
746: .Ar pid
747: is interpreted using the current radix (see
748: .Cm trace/t
749: command for details).
750: This is the default.
751: .El
1.85 wiz 752: .It Ic show registers Ns Op Cm /u
1.44 jhawk 753: Display the register set.
1.15 lukem 754: If
755: .Cm /u
1.44 jhawk 756: is specified, display user registers instead of kernel registers
757: or the currently save one.
1.15 lukem 758: .Pp
1.44 jhawk 759: Warning: support for
760: .Cm /u
761: is machine dependent.
762: If not supported, incorrect information will be displayed.
1.85 wiz 763: .It Ic show sched_qs
1.71 thorpej 764: Print the state of the scheduler's run queues.
765: For each run queue that has an LWP, the run queue index and the list
766: of LWPs will be shown.
767: If the run queue has LWPs, but the sched_whichqs bit is not set for that
768: queue, the queue index will be prefixed with a
1.72 wiz 769: .Sq \&! .
1.180 msaitoh 770: .It Ic show socket Ns Oo Cm /ampv Oc
771: Print usage of system's socket buffers.
1.181 wiz 772: By default, empty sockets aren't printed.
1.180 msaitoh 773: .Bl -tag -width 4n -compact
774: .It Cm /a
775: Print all processes which use the socket.
776: .It Cm /m
777: Print mbuf chain in the socket buffer.
778: .It Cm /p
1.181 wiz 779: By default, a process which uses the socket is printed (only one socket).
1.180 msaitoh 780: If
781: .Cm /p
782: is specified, the process isn't printed.
783: .It Cm /v
784: Verbose mode.
785: If
786: .Cm /v
787: is specified, all sockets are printed.
788: .El
1.85 wiz 789: .It Ic show uvmexp
1.50 jhawk 790: Print a selection of UVM counters and statistics.
1.183 mrg 791: .It Ic show kernhist Ns Oo Cm /i Oc Oo Ar addr Ns Oo , Ns Ar count Oc Oc
1.159 skrll 792: Dumps all the kernel histories if no address is specified, or the history
793: at the address.
1.183 mrg 794: If
795: .Cm /i
796: is specified, display information about the named history or all histories,
797: instead of history entries.
798: If
799: .Ar count
800: is specified, only the last
801: .Ar count
802: entries will be displayed.
803: Currently the
804: .Ar count
805: handling is only performed if a single history is requested.
1.163 pgoyette 806: This command is available only if a kernel is compiled with one or more
807: of the kernel history options
808: .Cd KERNHIST ,
809: .Cd SYSCALL_DEBUG ,
810: .Cd USB_DEBUG ,
811: .Cd BIOHIST ,
1.154 msaitoh 812: or
1.163 pgoyette 813: .Cd UVMHIST .
1.125 joerg 814: .It Ic show vnode Ns Oo Cm /f Oc Ar address
1.50 jhawk 815: Print the vnode at
816: .Ar address .
817: If
818: .Cm /f
819: is specified, the complete vnode is printed.
1.165 martin 820: .It Ic show vnode_lock Ns Oo Cm /f Oc Ar address
1.166 wiz 821: Print the vnode which has its lock at
1.165 martin 822: .Ar address .
823: If
824: .Cm /f
825: is specified, the complete vnode is printed.
1.85 wiz 826: .It Ic show watches
1.44 jhawk 827: Display all watchpoints.
1.125 joerg 828: .It Ic sifting Ns Oo Cm /F Oc Ar string
1.46 jhawk 829: Search the symbol tables for all symbols of which
830: .Ar string
1.66 wiz 831: is a substring, and display them.
832: If
1.46 jhawk 833: .Cm /F
834: is specified, a character is displayed immediately after each symbol
835: name indicating the type of symbol.
836: .Pp
1.189 ! maya 837: Object symbols display
1.46 jhawk 838: .Sy + ,
839: function symbols display
840: .Sy * ,
841: section symbols display
1.167 wiz 842: .Sy & ,
1.46 jhawk 843: and file symbols display
844: .Sy / .
1.47 jhawk 845: .Pp
846: To sift for a string beginning with a number, escape the first
847: character with a backslash as:
848: .Bd -literal -offset indent
849: sifting \\386
850: .Ed
1.172 wiz 851: .It Ic step Ns Oo Cm /p Oc Op , Ns Ar count
1.15 lukem 852: Single-step
853: .Ar count
854: times.
855: If
856: .Cm /p
857: is specified, print each instruction at each step.
1.1 brezak 858: Otherwise, only print the last instruction.
1.15 lukem 859: .Pp
860: Warning: depending on the machine type, it may not be possible
861: to single-step through some low-level code paths or user-space
862: code.
1.1 brezak 863: On machines with software-emulated single-stepping (e.g., pmax),
864: stepping through code executed by interrupt handlers will probably
865: do the wrong thing.
1.44 jhawk 866: .It Ic sync
1.150 christos 867: Sync the disks, force a crash dump, and then reboot.
1.125 joerg 868: .It Ic trace Ns Oo Cm /u Ns Oo Cm l Oc Oc Oo Ar frame-address Oc Ns \
1.172 wiz 869: Oo , Ns Ar count Oc
1.15 lukem 870: Stack trace from
871: .Ar frame-address .
872: If
873: .Cm /u
874: is specified, trace user-space, otherwise trace kernel-space.
875: .Ar count
876: is the number of frames to be traced.
877: If
878: .Ar count
879: is omitted, all frames are printed.
1.65 atatat 880: If
881: .Cm /l
882: is specified, the trace is printed and also stored in the kernel
883: message buffer.
1.15 lukem 884: .Pp
885: Warning: user-space stack trace is valid only if the machine dependent
886: code supports it.
1.172 wiz 887: .It Ic trace/t Ns Oo Cm l Oc Oo Ar pid Oc Ns Oo , Ns Ar count Oc
1.15 lukem 888: Stack trace by
889: .Dq thread
1.52 wiz 890: (process, on
1.18 perry 891: .Nx )
892: rather than by stack frame address.
1.15 lukem 893: Note that
894: .Ar pid
895: is interpreted using the current radix, whilst
896: .Ic ps
897: displays pids in decimal; prefix
898: .Ar pid
899: with
900: .Sq 0t
1.30 msaitoh 901: to force it to be interpreted as decimal (see
902: .Sx VARIABLES
1.65 atatat 903: section for radix).
904: If
905: .Cm /l
906: is specified, the trace is printed and also stored in the kernel
907: message buffer.
1.15 lukem 908: .Pp
1.10 sommerfe 909: Warning: trace by pid is valid only if the machine dependent code
910: supports it.
1.172 wiz 911: .It Ic trace/a Ns Oo Cm l Oc Oo Ar lwpaddr Oc Ns Oo , Ns Ar count Oc
1.99 ad 912: Stack trace by light weight process (LWP) address
913: rather than by stack frame address.
914: If
915: .Cm /l
916: is specified, the trace is printed and also stored in the kernel
917: message buffer.
918: .Pp
919: Warning: trace by LWP address is valid only if the machine dependent
920: code supports it.
1.44 jhawk 921: .It Ic until Ns Op Cm /p
922: Stop at the next call or return instruction.
1.15 lukem 923: If
1.44 jhawk 924: .Cm /p
925: is specified, print the call nesting depth and the
926: cumulative instruction count at each call or return.
927: Otherwise, only print when the matching return is hit.
1.172 wiz 928: .It Ic watch Ar address Ns Oo , Ns Ar size Oc
1.15 lukem 929: Set a watchpoint for a region.
930: Execution stops when an attempt to modify the region occurs.
931: .Ar size
932: defaults to 4.
933: .Pp
934: If you specify a wrong space address, the request is
935: rejected with an error message.
936: .Pp
937: Warning: attempts to watch wired kernel memory may cause
938: an unrecoverable error in some systems such as i386.
939: Watchpoints on user addresses work the best.
1.125 joerg 940: .It Ic whatis Ar address
1.108 yamt 941: Describe what an address is.
1.134 phx 942: .It Ic write Ns Oo Cm /bhlBHL Oc Ar address Ar expression Oo Ar expression ... Oc
1.44 jhawk 943: Write the
944: .Ar expression Ns s
945: at succeeding locations.
946: The unit size is specified with a modifier character, as per
947: .Ic examine .
948: Valid modifiers are:
949: .Cm /b ,
950: .Cm /h ,
951: and
952: .Cm /l .
953: If no modifier is specified,
954: .Cm /l
955: is used.
956: .Pp
1.134 phx 957: Specifying the modifiers in upper case,
958: .Cm /B ,
959: .Cm /H ,
960: .Cm /L ,
961: will prevent
962: .Nm
963: from reading the memory location first, which is useful for avoiding
964: side effects when writing to I/O memory regions.
965: .Pp
1.44 jhawk 966: Warning: since there is no delimiter between
967: .Ar expression Ns s ,
968: strange things may occur.
969: It's best to enclose each
970: .Ar expression
971: in parentheses.
1.172 wiz 972: .It Ic x Ns Oo Cm / Ns Ar modifier Oc Ar address Ns Op , Ns Ar count
1.41 jhawk 973: A synonym for
1.44 jhawk 974: .Ic examine .
975: .\" XXX - these commands aren't implemented; jhawk 19 May 2000
976: .\" .It Ic xf
977: .\" Examine forward.
978: .\" .Ic xf
979: .\" re-executes the most recent
980: .\" .Ic execute
981: .\" command with the same parameters except that
982: .\" .Ar address
983: .\" is set to
984: .\" .Ar next .
985: .\" .It Ic xb
986: .\" Examine backward.
987: .\" .Ic xb
988: .\" re-executes the most recent
989: .\" .Ic execute
990: .\" command with the same parameters, except that
991: .\" .Ar address
992: .\" is set to the last start address minus its size.
1.15 lukem 993: .El
1.19 fair 994: .Sh MACHINE-SPECIFIC COMMANDS
995: The "glue" code that hooks
996: .Nm
997: into the
998: .Nx
999: kernel for any given port can also add machine specific commands
1000: to the
1001: .Nm
1002: command parser.
1003: All of these commands are preceded by the command word
1004: .Em machine
1005: to indicate that they are part of the machine-specific command
1.23 fair 1006: set (e.g.
1.85 wiz 1007: .Ic machine reboot ) .
1.19 fair 1008: Some of these commands are:
1.182 ryo 1009: .Ss AARCH64
1010: .Bl -tag -width "traptrace" -compact
1011: .It Ic cpu
1012: Switch to another cpu.
1013: .It Ic cpuinfo
1014: Print cpu information about the ``struct cpuinfo''.
1015: .It Ic frame
1016: Given a trap frame address, print out the trap frame.
1017: .It Ic lwp
1018: Print lwp information about the ``struct lwp''.
1019: .It Ic pte
1020: Print PTE information.
1021: .It Ic sysreg
1022: Print system registers.
1023: .It Ic watch
1024: Set or clear a hardware watchpoint.
1025: Pass the address to be watched, or watchpoint number to clear the watchpoint.
1026: Optional modifiers are
1027: .Dq l
1028: for load access,
1029: .Dq s
1030: for store access,
1031: .Dq 1
1032: for 8 bit width,
1033: .Dq 2
1034: for 16 bit,
1035: .Dq 3
1036: for 24 bit,
1037: .Dq 4
1038: for 32 bit,
1039: .Dq 5
1040: for 40 bit,
1041: .Dq 6
1042: for 48 bit,
1043: .Dq 7
1044: for 56 bit,
1045: .Dq 8
1046: for 64 bit.
1047: .El
1.23 fair 1048: .Ss ALPHA
1.112 chris 1049: .Bl -tag -width "traptrace" -compact
1.139 mrg 1050: .It Ic cpu
1051: Switch to another cpu.
1052: .\" .It Ic halt
1053: .\" Call the PROM monitor to halt the CPU.
1054: .\" .It Ic reboot
1055: .\" Call the PROM monitor to reboot the CPU.
1.19 fair 1056: .El
1.140 mrg 1057: .Ss AMD64
1058: .Bl -tag -width "traptrace" -compact
1059: .It Ic cpu
1060: Switch to another cpu.
1061: .El
1.23 fair 1062: .Ss ARM32
1.112 chris 1063: .Bl -tag -width "traptrace" -compact
1.140 mrg 1064: .It Ic frame
1065: Given a trap frame address, print out the trap frame.
1.19 fair 1066: .El
1.155 skrll 1067: .Ss HPPA
1.137 skrll 1068: .Bl -tag -width "traptrace" -compact
1069: .It Ic frame
1070: Without an address the default trap frame is printed.
1071: Otherwise, the trap frame address can be given, or, when the
1072: .Dq l
1073: modifier is used, an LWP address.
1074: .El
1.140 mrg 1075: .Ss I386
1076: .Bl -tag -width "traptrace" -compact
1077: .It Ic cpu
1078: Switch to another cpu.
1079: .El
1080: .Ss IA64
1081: .Bl -tag -width "traptrace" -compact
1082: .It Ic vector
1083: Without a vector, information about all 256 vectors is shown.
1084: Otherwise, the given vector is shown.
1085: .El
1.23 fair 1086: .Ss MIPS
1.112 chris 1087: .Bl -tag -width "traptrace" -compact
1.114 tsutsui 1088: .It Ic cp0
1089: Dump CP0 (coprocessor 0) register values.
1.38 soren 1090: .It Ic kvtop
1091: Print the physical address for a given kernel virtual address.
1.23 fair 1092: .It Ic tlb
1.21 fair 1093: Print out the Translation Lookaside Buffer (TLB).
1.19 fair 1094: Only works in
1095: .Nx
1.23 fair 1096: kernels compiled with
1097: .Dv DEBUG
1098: option.
1.58 uch 1099: .El
1.132 phx 1100: .Ss POWERPC 4xx
1.130 mrg 1101: .Bl -tag -width "traptrace" -compact
1102: .It Ic ctx
1103: Print process MMU context information.
1104: .It Ic pv
1.167 wiz 1105: Print PA->VA mapping information.
1.130 mrg 1106: .It Ic reset
1107: Reset the system.
1108: .It Ic tf
1109: Display the contents of the trapframe.
1110: .It Ic tlb
1111: Display instruction translation storage buffer information.
1112: .It Ic dcr
1113: Set the DCR register.
1114: Must be between 0x00 and 0x3ff.
1115: .It Ic user
1116: Display user memory.
1117: Use the
1118: .Dq i
1119: modifier to get instruction decoding.
1120: .El
1.132 phx 1121: .Ss POWERPC OEA
1122: .Bl -tag -width "traptrace" -compact
1123: .It Ic bat
1124: Print BAT registers and translations.
1125: .It Ic mmu
1126: Print MMU registers.
1127: .El
1.58 uch 1128: .Ss SH3
1.112 chris 1129: .Bl -tag -width "traptrace" -compact
1.58 uch 1130: .It Ic tlb
1.130 mrg 1131: Print TLB entries.
1.58 uch 1132: .It Ic cache
1.130 mrg 1133: Print cache entries.
1.58 uch 1134: .It Ic frame
1135: Print switch frame and trap frames.
1136: .It Ic stack
1.66 wiz 1137: Print kernel stack usage.
1.75 wiz 1138: Only works in
1139: .Nx
1140: kernels compiled with the
1141: .Dv KSTACK_DEBUG
1142: option.
1.19 fair 1143: .El
1.23 fair 1144: .Ss SPARC
1.112 chris 1145: .Bl -tag -width "traptrace" -compact
1.128 mrg 1146: .It Ic cpu
1147: Switch to another cpu.
1.23 fair 1148: .It Ic prom
1.128 mrg 1149: Enter the Sun PROM monitor.
1150: .It Ic proc
1151: Display some information about the LWP pointed to, or curlwp.
1152: .It Ic pcb
1153: Display information about the
1154: .Dq struct pcb
1155: listed.
1156: .It Ic page
1157: Display the pointer to the
1158: .Dq struct vm_page
1159: for this physical address.
1.49 mrg 1160: .El
1161: .Ss SPARC64
1.112 chris 1162: .Bl -tag -width "traptrace" -compact
1.49 mrg 1163: .It Ic ctx
1164: Print process context information.
1.105 martin 1165: .It Ic cpu
1166: Switch to another cpu.
1.49 mrg 1167: .It Ic dtlb
1168: Print data translation look-aside buffer context information.
1169: .It Ic dtsb
1170: Display data translation storage buffer information.
1171: .It Ic kmap
1.66 wiz 1172: Display information about the listed mapping in the kernel pmap.
1173: Use the
1.49 mrg 1174: .Dq f
1175: modifier to get a full listing.
1.105 martin 1176: .It Ic extract
1177: Extract the physical address for a given virtual address from the kernel pmap.
1178: .It Ic fpstate
1179: Dump the FPU state.
1180: .It Ic itlb
1181: Print instruction translation look-aside buffer context information.
1182: .It Ic itsb
1183: Display instruction translation storage buffer information.
1184: .It Ic lwp
1185: Display a struct lwp
1.49 mrg 1186: .It Ic pcb
1187: Display information about the
1.52 wiz 1188: .Dq struct pcb
1.49 mrg 1189: listed.
1190: .It Ic pctx
1191: Attempt to change process context.
1192: .It Ic page
1193: Display the pointer to the
1194: .Dq struct vm_page
1195: for this physical address.
1196: .It Ic phys
1197: Display physical memory.
1198: .It Ic pmap
1.66 wiz 1199: Display the pmap.
1200: Use the
1.49 mrg 1201: .Dq f
1202: modifier to get a fuller listing.
1203: .It Ic proc
1204: Display some information about the process pointed to, or curproc.
1205: .It Ic prom
1.63 wiz 1206: Enter the OFW PROM.
1.49 mrg 1207: .It Ic pv
1208: Display the
1209: .Dq struct pv_entry
1210: pointed to.
1.106 martin 1211: .It Ic sir
1212: Reset the machine and enter prom (do a Software Initiated Reset).
1.49 mrg 1213: .It Ic stack
1.66 wiz 1214: Dump the window stack.
1215: Use the
1.49 mrg 1216: .Dq u
1217: modifier to get userland information.
1218: .It Ic tf
1.66 wiz 1219: Display full trap frame state.
1220: This is most useful for inclusion with bug reports.
1.49 mrg 1221: .It Ic ts
1222: Display trap state.
1223: .It Ic traptrace
1.66 wiz 1224: Display or set trap trace information.
1225: Use the
1.49 mrg 1226: .Dq r
1227: and
1228: .Dq f
1229: modifiers to get reversed and full information, respectively.
1230: .It Ic watch
1.66 wiz 1231: Set or clear a physical or virtual hardware watchpoint.
1232: Pass the address to be watched, or
1.49 mrg 1233: .Dq 0
1.107 wiz 1234: (or omit the address) to clear the watchpoint.
1.106 martin 1235: Optional modifiers are
1.49 mrg 1236: .Dq p
1.106 martin 1237: for physical address,
1238: .Dq r
1239: for trap on read access (default: trap on write access only),
1240: .Dq b
1241: for 8 bit width,
1242: .Dq h
1243: for 16 bit,
1244: .Dq l
1.107 wiz 1245: for 32 bit or
1.106 martin 1246: .Dq L
1247: for 64 bit.
1.49 mrg 1248: .It Ic window
1.123 wiz 1249: Print register window information.
1250: Argument is a stack frame number (0 is
1.106 martin 1251: top of stack, which is used when no index is given).
1.19 fair 1252: .El
1.138 mrg 1253: .Ss SUN2, SUN3 and SUN3X
1.112 chris 1254: .Bl -tag -width "traptrace" -compact
1.23 fair 1255: .It Ic abort
1.19 fair 1256: Drop into monitor via abort (allows continue).
1.23 fair 1257: .It Ic halt
1.19 fair 1258: Exit to Sun PROM monitor as in
1259: .Xr halt 8 .
1.23 fair 1260: .It Ic reboot
1.19 fair 1261: Reboot the machine as in
1262: .Xr reboot 8 .
1.23 fair 1263: .It Ic pgmap
1.19 fair 1264: Given an address, print the address, segment map, page map, and
1265: Page Table Entry (PTE).
1266: .El
1.140 mrg 1267: .Ss VAX
1268: .Bl -tag -width "traptrace" -compact
1269: .It Ic cpu
1270: Switch to another cpu.
1271: .El
1.15 lukem 1272: .Sh VARIABLES
1273: .Nm
1274: accesses registers and variables as
1275: .Cm $ Ns Ar name .
1276: Register names are as per the
1.85 wiz 1277: .Ic show registers
1.1 brezak 1278: command.
1.15 lukem 1279: Some variables are suffixed with numbers, and may have a modifier
1.1 brezak 1280: following a colon immediately after the variable name.
1.15 lukem 1281: For example, register variables may have a
1282: .Sq u
1283: modifier to indicate user register
1284: (e.g.,
1285: .Li "$eax:u" ) .
1286: .Pp
1.1 brezak 1287: Built-in variables currently supported are:
1.44 jhawk 1288: .Bl -tag -offset indent -width "maxwidth" -compact
1.173 sevan 1289: .It Va dumpstack
1290: If non-zero (the default),
1291: causes a stack trace to be printed when
1292: .Nm
1293: is entered on panic.
1294: .It Va fromconsole
1295: If non-zero (the default),
1296: the kernel allows to enter
1297: .Nm
1298: from the console (by break signal or special key sequence).
1299: If the kernel configuration option
1300: .D1 Cd options DDB_FROMCONSOLE=0
1301: is used,
1302: .Va fromconsole
1303: will be initialized to off.
1.15 lukem 1304: .It Va lines
1305: The number of lines.
1306: This is used by the
1307: .Ic more
1308: feature.
1.107 wiz 1309: When this variable is set to zero the
1.103 uwe 1310: .Ic more
1311: feature is disabled.
1.15 lukem 1312: .It Va maxoff
1313: Addresses are printed as
1314: .Li 'symbol'+offset
1315: unless
1316: .Li offset
1317: is greater than
1318: .Va maxoff .
1319: .It Va maxwidth
1.1 brezak 1320: The width of the displayed line.
1.103 uwe 1321: .Nm
1322: wraps the current line by printing new line when
1323: .Va maxwidth
1324: column is reached.
1.107 wiz 1325: When this variable is set to zero
1.103 uwe 1326: .Nm
1327: doesn't perform any wrapping.
1.15 lukem 1328: .It Va onpanic
1.142 riz 1329: If greater than zero (the default is 1),
1.15 lukem 1330: .Nm
1331: will be invoked when the kernel panics.
1332: If the kernel configuration option
1333: .D1 Cd options DDB_ONPANIC=0
1334: is used,
1335: .Va onpanic
1.142 riz 1336: will be initialized to off, causing a stack trace to be printed and
1337: the system to be rebooted instead of
1338: .Nm
1339: being entered.
1.173 sevan 1340: Setting
1341: .Va onpanic
1.174 wiz 1342: to \-1 suppresses the stack trace before reboot.
1.15 lukem 1343: .It Va radix
1344: Input and output radix.
1345: .It Va tabstops
1.1 brezak 1346: Tab stop width.
1.79 reinoud 1347: .It Va tee_msgbuf
1.93 wiz 1348: If explicitly set to non zero (zero is the default) all
1.79 reinoud 1349: .Nm
1350: output will not only be displayed on screen but
1351: also be fed to the msgbuf.
1352: The default of the variable can be set using the kernel configuration option
1353: .D1 Cd options DDB_TEE_MSGBUF=1
1.107 wiz 1354: which will initialize
1.79 reinoud 1355: .Va tee_msgbuf
1356: to be 1.
1357: This option is especially handy for poor souls
1358: who don't have a serial console but want to recall
1359: .Nm
1360: output from a crash investigation.
1361: This option is more generic than the /l command modifier possible for
1.80 wiz 1362: selected commands as discussed above to log the output.
1363: Mixing both /l
1.79 reinoud 1364: and this setting can give double loggings.
1.168 christos 1365: .It Va panicstackframes
1366: Number of stack frames to display on panic.
1.170 wiz 1367: Useful to avoid scrolling away the interesting frames on a glass tty.
1.168 christos 1368: Default value is
1369: .Dv 65535
1370: (all frames), useful value around
1371: .Dv 10 .
1.54 jhawk 1372: .\" .It Va work Ns Sy xx
1373: .\" Temporary work variable.
1374: .\" .Sq Sy xx
1375: .\" is between 0 and 31.
1.15 lukem 1376: .El
1377: .Pp
1378: All built-in variables are accessible via
1379: .Xr sysctl 3 .
1380: .Sh EXPRESSIONS
1381: Almost all expression operators in C are supported, except
1.31 mycroft 1382: .Sq \&~ ,
1383: .Sq \&^ ,
1.15 lukem 1384: and unary
1.167 wiz 1385: .Sq \&& .
1.15 lukem 1386: Special rules in
1387: .Nm
1.1 brezak 1388: are:
1.15 lukem 1389: .Bl -tag -offset indent -width "identifier"
1390: .It Ar identifier
1391: name of a symbol.
1392: It is translated to the address (or value) of it.
1.31 mycroft 1393: .Sq \&.
1.15 lukem 1394: and
1.31 mycroft 1395: .Sq \&:
1.15 lukem 1396: can be used in the identifier.
1397: If supported by an object format dependent routine,
1398: .Sm off
1399: .Xo
1400: .Oo Ar filename : Oc
1401: .Ar function
1.86 uwe 1402: .Oo : Ar line\ number Oc ,
1.15 lukem 1403: .Xc
1.86 uwe 1404: .Sm on
1405: .Sm off
1.15 lukem 1406: .Xo
1407: .Oo Ar filename : Oc
1408: .Ar variable ,
1409: .Xc
1.86 uwe 1410: .Sm on
1.15 lukem 1411: and
1.86 uwe 1412: .Sm off
1.15 lukem 1413: .Xo
1414: .Ar filename
1415: .Oo : Ar "line number" Oc ,
1416: .Xc
1417: .Sm on
1.1 brezak 1418: can be accepted as a symbol.
1.15 lukem 1419: The symbol may be prefixed with
1.86 uwe 1420: .Ar symbol_table_name\^ : :
1.15 lukem 1421: (e.g.,
1422: .Li emulator::mach_msg_trap )
1423: to specify other than kernel symbols.
1424: .It Ar number
1425: number.
1426: Radix is determined by the first two characters:
1427: .Sq 0x
1428: - hex,
1429: .Sq 0o
1430: - octal,
1431: .Sq 0t
1432: - decimal,
1433: otherwise follow current radix.
1.172 wiz 1434: .It Cm \&.
1.15 lukem 1435: .Ar dot
1436: .It Cm +
1437: .Ar next
1438: .It Cm ..
1.1 brezak 1439: address of the start of the last line examined.
1.15 lukem 1440: Unlike
1441: .Ar dot
1442: or
1443: .Ar next ,
1444: this is only changed by the
1445: .Ic examine
1446: or
1447: .Ic write
1448: commands.
1.86 uwe 1449: .It Cm \&" \"" XXX: emacs highlighting
1.1 brezak 1450: last address explicitly specified.
1.15 lukem 1451: .It Cm $ Ns Ar name
1452: register name or variable.
1453: It is translated to the value of it.
1454: It may be followed by a
1.31 mycroft 1455: .Sq \&:
1.15 lukem 1456: and modifiers as described above.
1.86 uwe 1457: .It Cm #
1458: a binary operator which rounds up the left hand side to the next
1459: multiple of right hand side.
1.15 lukem 1460: .It Cm * Ns Ar expr
1461: expression indirection.
1462: It may be followed by a
1.31 mycroft 1463: .Sq \&:
1.15 lukem 1464: and modifiers as described above.
1465: .El
1.53 wiz 1466: .Sh SEE ALSO
1.83 wiz 1467: .Xr reboot 2 ,
1.53 wiz 1468: .Xr options 4 ,
1.136 wiz 1469: .Xr crash 8 ,
1.81 fredb 1470: .Xr reboot 8 ,
1.77 wiz 1471: .Xr sysctl 8 ,
1472: .Xr cnmagic 9
1.19 fair 1473: .Sh HISTORY
1474: The
1475: .Nm
1476: kernel debugger was written as part of the MACH project at
1477: Carnegie-Mellon University.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to ddb.4 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / share / man / man4