Annotation of src/share/man/man4/ddb.4, Revision 1.84
1.84 ! yamt 1: .\" $NetBSD: ddb.4,v 1.83 2005/11/28 20:05:49 wiz Exp $
1.15 lukem 2: .\"
1.62 wiz 3: .\" Copyright (c) 1997 - 2003 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: .\" 3. All advertising materials mentioning features or use of this software
18: .\" must display the following acknowledgement:
19: .\" This product includes software developed by the NetBSD
20: .\" Foundation, Inc. and its contributors.
21: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22: .\" contributors may be used to endorse or promote products derived
23: .\" from this software without specific prior written permission.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35: .\" POSSIBILITY OF SUCH DAMAGE.
36: .\"
37: .\" ---
38: .\" This manual page was derived from a -man.old document which bore
39: .\" the following copyright message:
40: .\" ---
1.5 jtc 41: .\"
1.1 brezak 42: .\" Mach Operating System
43: .\" Copyright (c) 1991,1990 Carnegie Mellon University
44: .\" All Rights Reserved.
1.52 wiz 45: .\"
1.1 brezak 46: .\" Permission to use, copy, modify and distribute this software and its
47: .\" documentation is hereby granted, provided that both the copyright
48: .\" notice and this permission notice appear in all copies of the
49: .\" software, derivative works or modified versions, and any portions
50: .\" thereof, and that both notices appear in supporting documentation.
1.52 wiz 51: .\"
1.1 brezak 52: .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
53: .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
54: .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
1.52 wiz 55: .\"
1.1 brezak 56: .\" Carnegie Mellon requests users of this software to return to
1.52 wiz 57: .\"
1.1 brezak 58: .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
59: .\" School of Computer Science
60: .\" Carnegie Mellon University
61: .\" Pittsburgh PA 15213-3890
1.52 wiz 62: .\"
1.1 brezak 63: .\" any improvements or extensions that they make and grant Carnegie Mellon
64: .\" the rights to redistribute these changes.
1.15 lukem 65: .\"
1.84 ! yamt 66: .Dd December 1, 2005
1.15 lukem 67: .Dt DDB 4
1.32 garbled 68: .Os
1.15 lukem 69: .Sh NAME
70: .Nm ddb
71: .Nd in-kernel debugger
72: .Sh SYNOPSIS
73: .Cd options DDB
74: .Pp
75: To enable history editing:
76: .Cd options DDB_HISTORY_SIZE=integer
77: .Pp
78: To disable entering
1.64 wiz 79: .\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS
80: .Ic ddb
1.15 lukem 81: upon kernel panic:
82: .Cd options DDB_ONPANIC=0
1.79 reinoud 83: .Pp
84: To enable teeing all
85: .\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS
86: .Ic ddb
87: output to the kernel msgbuf:
88: .Cd options DDB_TEE_MSGBUF=1
1.82 yamt 89: .Pp
90: To specify commands which will be executed on each entry to
91: .Ic ddb :
92: .Cd options DDB_COMMANDONENTER="trace;show registers"
1.83 wiz 93: In this case, "trace" and then "show registers" will be executed automatically.
1.15 lukem 94: .Sh DESCRIPTION
95: .Nm
96: is the in-kernel debugger.
97: It may be entered at any time via a special key sequence, and
98: optionally may be invoked when the kernel panics.
1.21 fair 99: .Sh ENTERING THE DEBUGGER
100: Unless
101: .Dv DDB_ONPANIC
102: is set to 0,
103: .Nm
104: will be activated whenever the kernel would otherwise panic.
105: .Pp
106: .Nm
107: may also be activated from the console.
108: In general, sending a break on a serial console will activate
1.60 wiz 109: .Nm .
1.21 fair 110: There are also key sequences for each port that will activate
111: .Nm
112: from the keyboard:
1.44 jhawk 113: .Bl -tag -offset indent -width "mvme68k" -compact
1.21 fair 114: .It alpha
1.56 ross 115: \*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] on PC style keyboards.
1.21 fair 116: .It amiga
1.56 ross 117: \*[Lt]LAlt\*[Gt]-\*[Lt]LAmiga\*[Gt]-\*[Lt]F10\*[Gt]
1.27 leo 118: .It atari
1.56 ross 119: \*[Lt]Alt\*[Gt]-\*[Lt]LeftShift\*[Gt]-\*[Lt]F9\*[Gt]
1.21 fair 120: .It hp300
1.56 ross 121: \*[Lt]Shift\*[Gt]-\*[Lt]Reset\*[Gt]
1.78 jdc 122: .It hpcarm
123: \*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
1.37 takemura 124: .It hpcmips
1.56 ross 125: \*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
1.58 uch 126: .It hpcsh
127: \*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
1.21 fair 128: .It i386
1.56 ross 129: \*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt]
1.45 jhawk 130: .br
1.56 ross 131: \*[Lt]Break\*[Gt] on serial console.
1.21 fair 132: .It mac68k
1.56 ross 133: \*[Lt]Command\*[Gt]-\*[Lt]Power\*[Gt], or the Interrupt switch.
1.62 wiz 134: .It macppc
135: Some models:
136: \*[Lt]Command\*[Gt]-\*[Lt]Option\*[Gt]-\*[Lt]Power\*[Gt]
1.21 fair 137: .It mvme68k
138: Abort switch on CPU card.
139: .It pmax
1.56 ross 140: \*[Lt]Do\*[Gt] on
1.23 fair 141: .Tn LK-201
142: rcons console.
143: .br
1.56 ross 144: \*[Lt]Break\*[Gt] on serial console.
1.21 fair 145: .It sparc
1.56 ross 146: \*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a
1.23 fair 147: .Tn Sun
148: keyboard.
149: .br
1.56 ross 150: \*[Lt]Break\*[Gt] on serial console.
1.78 jdc 151: .It sparc64
1.56 ross 152: \*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a
1.23 fair 153: .Tn Sun
154: keyboard.
155: .br
1.56 ross 156: \*[Lt]Break\*[Gt] on serial console.
1.78 jdc 157: .It sun3
1.56 ross 158: \*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a
1.23 fair 159: .Tn Sun
160: keyboard.
161: .br
1.56 ross 162: \*[Lt]Break\*[Gt] on serial console.
1.76 wiz 163: .It vax
164: \*[Lt]Esc\*[Gt]-\*[Lt]Shift\*[Gt]-D on serial console.
1.26 msaitoh 165: .It x68k
166: Interrupt switch on the body.
1.21 fair 167: .El
1.23 fair 168: .Pp
1.77 wiz 169: The key sequence to activate
170: .Nm
171: can be changed by modifying
172: .Dq hw.cnmagic
173: with
174: .Xr sysctl 8 .
175: If the console is not dedicated to
176: .Nm
177: the sequence should not be easily typed by accident.
1.21 fair 178: In addition,
179: .Nm
180: may be explicitly activated by the debugging code in the kernel
181: if
182: .Cm DDB
183: is configured.
184: .Sh COMMAND SYNTAX
185: The general command syntax is:
186: .Bd -ragged -offset indent
187: .Ic command Ns Op Cm / Ns Ar modifier
188: .Ar address
189: .Op Cm , Ns Ar count
190: .Ed
1.15 lukem 191: .Pp
192: The current memory location being edited is referred to as
193: .Ar dot ,
194: and the next location is
195: .Ar next .
196: They are displayed as hexadecimal numbers.
197: .Pp
198: Commands that examine and/or modify memory update
199: .Ar dot
200: to the address of the last line examined or the last location
201: modified, and set
202: .Ar next
203: to the next location to be examined or modified.
204: Other commands don't change
205: .Ar dot ,
206: and set
207: .Ar next
208: to be the same as
209: .Ar dot .
210: .Pp
211: A blank line repeats the previous command from the address
212: .Ar next
1.39 jhawk 213: with the previous
1.15 lukem 214: .Cm count
1.39 jhawk 215: and no modifiers.
1.15 lukem 216: Specifying
217: .Cm address
218: sets
219: .Em dot
220: to the address.
1.52 wiz 221: If
1.15 lukem 222: .Cm address
223: is omitted,
224: .Em dot
225: is used.
226: A missing
227: .Cm count
228: is taken to be 1 for printing commands, and infinity for stack traces.
1.39 jhawk 229: .Pp
230: The syntax:
231: .Bd -ragged -offset indent
1.67 wiz 232: .Cm , Ns Ar count
1.39 jhawk 233: .Ed
234: .Pp
235: repeats the previous command, just as a blank line does, but with
236: the specified
237: .Cm count .
1.15 lukem 238: .Pp
239: .Nm
240: has a
1.68 wiz 241: .Xr more 1 Ns -like
1.15 lukem 242: functionality; if a number of lines in a command's output exceeds the number
243: defined in the
244: .Va lines
245: variable, then
246: .Nm
247: displays
248: .Dq "--db more--"
249: and waits for a response, which may be one of:
1.56 ross 250: .Bl -tag -offset indent -width "\*[Lt]return\*[Gt]"
251: .It \*[Lt]return\*[Gt]
1.15 lukem 252: one more line.
1.56 ross 253: .It \*[Lt]space\*[Gt]
1.15 lukem 254: one more page.
1.52 wiz 255: .It Ic q
1.1 brezak 256: abort the current command, and return to the command input mode.
1.15 lukem 257: .El
258: .Pp
1.52 wiz 259: If
1.15 lukem 260: .Nm
261: history editing is enabled (by defining the
262: .D1 Cd options DDB_HISTORY_SIZE=num
263: kernel option), then a history of the last
264: .Cm num
265: commands is kept.
266: The history can be manipulated with the following key sequences:
1.56 ross 267: .Bl -tag -offset indent -width "\*[Lt]Ctrl\*[Gt]-P"
268: .It \*[Lt]Ctrl\*[Gt]-P
1.15 lukem 269: retrieve previous command in history (if any).
1.56 ross 270: .It \*[Lt]Ctrl\*[Gt]-N
1.15 lukem 271: retrieve next command in history (if any).
272: .El
273: .Sh COMMANDS
274: .Nm
275: supports the following commands:
276: .Bl -tag -width 5n
277: .It Xo
1.44 jhawk 278: .Sm off
1.68 wiz 279: .Ic \&!
1.44 jhawk 280: .Ar address
281: .Oo
282: .Cm ( Ar expression
283: .Op Ar ,...
284: .Cm )
285: .Oc
286: .Sm on
287: .Xc
288: A synonym for
289: .Ic call .
290: .It Xo
291: .Ic break Ns Op Cm /u
292: .Ar address Ns Op Cm , Ns Ar count
293: .Xc
294: Set a breakpoint at
295: .Ar address .
296: If
297: .Ar count
298: is supplied, continues
299: .Pq Ar count Ns -1
300: times before stopping at the breakpoint.
301: If the breakpoint is set, a breakpoint number is printed with
302: .Sq \&# .
303: This number can be used to
304: .Ic delete
305: the breakpoint, or to add
306: conditions to it.
307: .Pp
308: If
309: .Cm /u
310: is specified,
311: set a breakpoint at a user-space address.
312: Without
313: .Cm /u ,
314: .Ar address
315: is considered to be in the kernel-space, and an address in the wrong
316: space will be rejected, and an error message will be emitted.
317: This modifier may only be used if it is supported by machine dependent
318: routines.
319: .Pp
320: Warning: if a user text is shadowed by a normal user-space debugger,
321: user-space breakpoints may not work correctly.
322: Setting a breakpoint at the low-level code paths may also cause
323: strange behavior.
1.61 wiz 324: .It Xo
1.59 jmc 325: .Ic bt Ns Op Cm /u
326: .Sm off
327: .Op Ar frame-address
328: .Op Cm , Ar count
329: .Sm on
330: .Xc
331: A synonym for
332: .Ic trace .
333: .It Xo
334: .Ic bt/t
335: .Sm off
336: .Op Ar pid
337: .Op Cm , Ar count
338: .Sm on
1.61 wiz 339: .Xc
1.59 jmc 340: A synonym for
341: .Ic trace .
1.44 jhawk 342: .It Xo
343: .Ic call
344: .Sm off
345: .Ar address
346: .Oo
347: .Cm ( Ar expression
348: .Op Ar ,...
349: .Cm )
350: .Oc
351: .Sm on
352: .Xc
353: Call the function specified by
354: .Ar address
355: with the argument(s) listed in parentheses.
356: Parentheses may be omitted if the function takes no arguments.
357: The number of arguments is currently limited to 10.
358: .It Ic continue Ns Op Cm /c
359: Continue execution until a breakpoint or watchpoint.
360: If
361: .Cm /c
362: is specified, count instructions while executing.
363: Some machines (e.g., pmax) also count loads and stores.
364: .Pp
365: Warning: when counting, the debugger is really silently
366: single-stepping.
367: This means that single-stepping on low-level may cause strange
368: behavior.
369: .It Xo
370: .Ic delete
371: .Ar "address" |
372: .Cm # Ns Ar number
373: .Xc
374: Delete a breakpoint.
375: The target breakpoint may be specified by
376: .Ar address ,
377: as per
378: .Ic break ,
379: or by the breakpoint number returned by
380: .Ic break
381: if it's prefixed with
382: .Sq Cm \&# .
383: .It Xo
1.69 simonb 384: .Ic dmesg Op Ar count
1.65 atatat 385: .Xc
386: Prints the contents of the kernel message buffer.
1.69 simonb 387: The optional
388: .Ar count
389: argument will limit printing to at most the last
390: .Ar count
391: bytes of the message buffer.
1.65 atatat 392: .It Xo
1.44 jhawk 393: .Ic dwatch
394: .Ar address
395: .Xc
396: Delete the watchpoint at
397: .Ar address
398: that was previously set with
399: .Ic watch
400: command.
401: .It Xo
1.15 lukem 402: .Ic examine Ns Op Cm / Ns Ar modifier
403: .Ar address Ns Op Cm , Ns Ar count
404: .Xc
1.52 wiz 405: Display the address locations according to the format in
1.15 lukem 406: .Ar modifier .
1.1 brezak 407: Multiple modifier formats display multiple locations.
1.15 lukem 408: If
409: .Ar modifier
410: isn't specified, the modifier from the last use of
411: .Ic examine
1.1 brezak 412: is used.
1.15 lukem 413: .Pp
414: The valid format characters for
415: .Ar modifier
416: are:
1.44 jhawk 417: .Bl -tag -offset indent -width 2n -compact
1.15 lukem 418: .It Cm b
419: examine bytes (8 bits).
420: .It Cm h
421: examine half-words (16 bits).
422: .It Cm l
1.35 ross 423: examine words (legacy
424: .Dq long ,
425: 32 bits).
426: .It Cm L
427: examine long words (implementation dependent)
1.15 lukem 428: .It Cm a
429: print the location being examined.
430: .It Cm A
431: print the location with a line number if possible.
432: .It Cm x
433: display in unsigned hex.
434: .It Cm z
435: display in signed hex.
436: .It Cm o
437: display in unsigned octal.
438: .It Cm d
439: display in signed decimal.
440: .It Cm u
441: display in unsigned decimal.
442: .It Cm r
443: display in current radix, signed.
444: .It Cm c
1.1 brezak 445: display low 8 bits as a character.
1.15 lukem 446: Non-printing characters as displayed as an octal escape code
447: (e.g.,
448: .Sq \e000 ) .
449: .It Cm s
450: display the NUL terminated string at the location.
1.1 brezak 451: Non-printing characters are displayed as octal escapes.
1.15 lukem 452: .It Cm m
453: display in unsigned hex with a character dump at the end of each line.
454: The location is displayed as hex at the beginning of each line.
455: .It Cm i
456: display as a machine instruction.
457: .It Cm I
458: display as a machine instruction, with possible alternative formats
459: depending upon the machine:
1.44 jhawk 460: .Bl -tag -offset indent -width "sparc" -compact
1.25 drochner 461: .It alpha
462: print register operands
463: .It m68k
464: use Motorola syntax
465: .It pc532
466: print instruction bytes in hex
1.15 lukem 467: .It vax
468: don't assume that each external label is a procedure entry mask
469: .El
470: .El
471: .It Xo
1.44 jhawk 472: .Ic kill
473: .Ar pid Ns Op Cm , Ns Ar signal_number
1.15 lukem 474: .Xc
1.44 jhawk 475: Send a signal to the process specified by the
476: .Ar pid .
477: Note that
478: .Ar pid
479: is interpreted using the current radix (see
480: .Cm trace/t
481: command for details).
482: If
483: .Ar signal_number
484: isn't specified, the SIGTERM signal is sent.
485: .It Ic match Ns Op Cm /p
1.15 lukem 486: A synonym for
1.44 jhawk 487: .Ic next .
488: .It Ic next Ns Op Cm /p
489: Stop at the matching return instruction.
490: If
491: .Cm /p
492: is specified, print the call nesting depth and the
493: cumulative instruction count at each call or return.
494: Otherwise, only print when the matching return is hit.
1.15 lukem 495: .It Xo
496: .Ic print Ns Op Cm /axzodurc
497: .Ar address Op Ar address ...
498: .Xc
499: Print addresses
500: .Ar address
501: according to the modifier character, as per
502: .Ic examine .
503: Valid modifiers are:
504: .Cm /a ,
505: .Cm /x ,
506: .Cm /z ,
507: .Cm /o ,
508: .Cm /d ,
509: .Cm /u ,
510: .Cm /r ,
511: and
512: .Cm /c
513: (as per
514: .Ic examine ) .
515: If no modifier is specified, the most recent one specified is used.
516: .Ar address
517: may be a string, and is printed
518: .Dq as-is .
519: For example:
520: .Bd -literal -offset indent
521: print/x "eax = " $eax "\enecx = " $ecx "\en"
522: .Ed
523: .Pp
524: will produce:
525: .Bd -literal -offset indent
1.1 brezak 526: eax = xxxxxx
527: ecx = yyyyyy
1.15 lukem 528: .Ed
529: .It Xo
1.44 jhawk 530: .Sm off
531: .Ic ps
532: .Op Cm /a
533: .Op Cm /n
534: .Op Cm /w
535: .Sm on
536: .Xc
537: A synonym for
538: .Ic "show all procs" .
539: .It Ic reboot Op Ar flags
540: Reboot, using the optionally supplied boot
1.73 lukem 541: .Ar flags ,
1.81 fredb 542: which is a bitmask supporting the same values as for
543: .Xr reboot 2 .
544: Some of the more useful flags:
1.73 lukem 545: .Bl -column "Value" "RB_AUTOBOOT" "Description"
546: .It Sy "Value" Ta Sy "Name" Ta Sy "Description"
547: .It 0x1 Ta RB_ASKNAME Ta Ask for file name to reboot from
548: .It 0x2 Ta RB_SINGLE Ta Reboot to single user mode
549: .It 0x4 Ta RB_NOSYNC Ta Don't sync before reboot
550: .It 0x8 Ta RB_HALT Ta Halt instead of reboot
551: .It 0x40 Ta RB_KDB Ta Boot into kernel debugger
1.81 fredb 552: .It 0x100 Ta RB_DUMP Ta Dump unconditionally before reboot
1.73 lukem 553: .It 0x808 Ta RB_POWERDOWN Ta Power off (or at least halt)
554: .El
1.44 jhawk 555: .Pp
556: Note: Limitations of the command line interface preclude
557: specification of a boot string.
558: .It Xo
559: .Ic search Ns Op Cm /bhl
1.15 lukem 560: .Ar address
1.44 jhawk 561: .Ar value
562: .Op Ar mask
563: .Op Cm , Ns Ar count
1.15 lukem 564: .Xc
1.44 jhawk 565: Search memory from
566: .Ar address
567: for
568: .Ar value .
1.15 lukem 569: The unit size is specified with a modifier character, as per
570: .Ic examine .
571: Valid modifiers are:
572: .Cm /b ,
573: .Cm /h ,
574: and
575: .Cm /l .
576: If no modifier is specified,
577: .Cm /l
578: is used.
579: .Pp
1.44 jhawk 580: This command might fail in interesting ways if it doesn't find
581: .Ar value .
582: This is because
583: .Nm
584: doesn't always recover from touching bad memory.
585: The optional
586: .Ar count
587: limits the search.
1.15 lukem 588: .It Xo
589: .Ic set
590: .Cm $ Ns Ar variable
591: .Op Cm =
592: .Ar expression
593: .Xc
594: Set the named variable or register to the value of
595: .Ar expression .
596: Valid variable names are described in
597: .Sx VARIABLES .
1.84 ! yamt 598: .It Ic "show\ all\ pools" Ns Op Cm /clp
! 599: Display all pool information.
! 600: Modifiers are the same as
! 601: .Ic "show pool" .
1.15 lukem 602: .It Xo
1.44 jhawk 603: .Sm off
604: .Ic "show\ all\ procs"
605: .Op Cm /a
606: .Op Cm /n
607: .Op Cm /w
608: .Sm on
1.15 lukem 609: .Xc
1.44 jhawk 610: Display all process information.
611: Valid modifiers:
612: .Bl -tag -width 3n
613: .It Cm /n
614: show process information in a
615: .Xr ps 1
616: style format (this is the default).
617: Information printed includes: process ID, parent process ID,
618: process group, UID, process status, process flags, process
619: command name, and process wait channel message.
620: .It Cm /a
621: show the kernel virtual addresses of each process'
1.55 mrg 622: proc structure, u-area, and vmspace structure.
1.44 jhawk 623: The vmspace address is also the address of the process'
624: vm_map structure, and can be used in the
625: .Ic "show map"
626: command.
627: .It Cm /w
628: show each process' PID, command, system call emulation, wait channel
629: address, and wait channel message.
630: .El
1.50 jhawk 631: .It Ic "show breaks"
632: Display all breakpoints.
633: .It Xo
634: .Ic "show buf" Ns Op Cm /f
635: .Ar address
636: .Xc
637: Print the struct buf at
638: .Ar address .
639: The
640: .Cm /f
641: does nothing at this time.
1.57 simonb 642: .It Xo
643: .Ic "show event" Ns Op Cm /f
644: .Xc
645: Print all the non-zero
646: .Xr evcnt 9
647: event counters.
648: If
649: .Cm /f
650: is specified, all event counters with a count of zero are printed as well.
1.44 jhawk 651: .It Xo
652: .Ic "show map" Ns Op Cm /f
653: .Ar address
1.52 wiz 654: .Xc
1.44 jhawk 655: Print the vm_map at
656: .Ar address .
657: If
658: .Cm /f
1.50 jhawk 659: is specified, the complete map is printed.
1.74 dbj 660: .It Xo
661: .Ic "show mount" Ns Op Cm /f
662: .Ar address
663: .Xc
664: Print the mount structure at
665: .Ar address .
666: If
667: .Cm /f
668: is specified, the complete vnode list is printed.
1.50 jhawk 669: .It Ic "show ncache" Ar address
670: Dump the namecache list associated with vnode at
671: .Ar address .
1.44 jhawk 672: .It Xo
673: .Ic "show object" Ns Op Cm /f
674: .Ar address
1.52 wiz 675: .Xc
1.44 jhawk 676: Print the vm_object at
1.15 lukem 677: .Ar address .
678: If
1.44 jhawk 679: .Cm /f
1.50 jhawk 680: is specified, the complete object is printed.
681: .It Xo
682: .Ic "show page" Ns Op Cm /f
683: .Ar address
684: .Xc
685: Print the vm_page at
686: .Ar address .
687: If
688: .Cm /f
689: is specified, the complete page is printed.
690: .It Xo
691: .Ic "show pool" Ns Op Cm /clp
692: .Ar address
693: .Xc
694: Print the pool at
695: .Ar address .
696: Valid modifiers:
697: .Bl -tag -width 4n -compact
698: .It Cm /c
699: Print the cachelist and its statistics for this pool.
700: .It Cm /l
701: Print the log entries for this pool.
702: .It Cm /p
703: Print the pagelist for this pool.
704: .El
1.44 jhawk 705: .It Ic "show registers" Ns Op Cm /u
706: Display the register set.
1.15 lukem 707: If
708: .Cm /u
1.44 jhawk 709: is specified, display user registers instead of kernel registers
710: or the currently save one.
1.15 lukem 711: .Pp
1.44 jhawk 712: Warning: support for
713: .Cm /u
714: is machine dependent.
715: If not supported, incorrect information will be displayed.
1.71 thorpej 716: .It Ic "show sched_qs"
717: Print the state of the scheduler's run queues.
718: For each run queue that has an LWP, the run queue index and the list
719: of LWPs will be shown.
720: If the run queue has LWPs, but the sched_whichqs bit is not set for that
721: queue, the queue index will be prefixed with a
1.72 wiz 722: .Sq \&! .
1.50 jhawk 723: .It Ic "show uvmexp"
724: Print a selection of UVM counters and statistics.
725: .It Xo
726: .Ic "show vnode" Ns Op Cm /f
727: .Ar address
728: .Xc
729: Print the vnode at
730: .Ar address .
731: If
732: .Cm /f
733: is specified, the complete vnode is printed.
1.44 jhawk 734: .It Ic "show watches"
735: Display all watchpoints.
1.46 jhawk 736: .It Xo
737: .Ic sifting Ns Op Cm /F
738: .Ar string
739: .Xc
740: Search the symbol tables for all symbols of which
741: .Ar string
1.66 wiz 742: is a substring, and display them.
743: If
1.46 jhawk 744: .Cm /F
745: is specified, a character is displayed immediately after each symbol
746: name indicating the type of symbol.
747: .Pp
748: For
1.68 wiz 749: .Xr a.out 5 Ns -format
1.52 wiz 750: symbol tables,
1.46 jhawk 751: absolute symbols display
752: .Sy @ ,
753: text segment symbols display
754: .Sy * ,
755: data segment symbols display
756: .Sy + ,
757: .Tn BSS
758: segment symbols display
759: .Sy - ,
760: and filename symbols display
761: .Sy / .
762: For
763: .Tn ELF Ns -format
764: symbol tables,
765: object symbols display
766: .Sy + ,
767: function symbols display
768: .Sy * ,
769: section symbols display
1.56 ross 770: .Sy \*[Am] ,
1.46 jhawk 771: and file symbols display
772: .Sy / .
1.47 jhawk 773: .Pp
774: To sift for a string beginning with a number, escape the first
775: character with a backslash as:
776: .Bd -literal -offset indent
777: sifting \\386
778: .Ed
1.15 lukem 779: .It Xo
780: .Ic step Ns Op Cm /p
781: .Op Cm , Ns Ar count
782: .Xc
783: Single-step
784: .Ar count
785: times.
786: If
787: .Cm /p
788: is specified, print each instruction at each step.
1.1 brezak 789: Otherwise, only print the last instruction.
1.15 lukem 790: .Pp
791: Warning: depending on the machine type, it may not be possible
792: to single-step through some low-level code paths or user-space
793: code.
1.1 brezak 794: On machines with software-emulated single-stepping (e.g., pmax),
795: stepping through code executed by interrupt handlers will probably
796: do the wrong thing.
1.44 jhawk 797: .It Ic sync
798: Force a crash dump, and then reboot.
1.15 lukem 799: .It Xo
1.65 atatat 800: .Ic trace
1.67 wiz 801: .Ns Op Cm /u Ns Op Cm l
1.15 lukem 802: .Sm off
803: .Op Ar frame-address
804: .Op Cm , Ar count
805: .Sm on
806: .Xc
807: Stack trace from
808: .Ar frame-address .
809: If
810: .Cm /u
811: is specified, trace user-space, otherwise trace kernel-space.
812: .Ar count
813: is the number of frames to be traced.
814: If
815: .Ar count
816: is omitted, all frames are printed.
1.65 atatat 817: If
818: .Cm /l
819: is specified, the trace is printed and also stored in the kernel
820: message buffer.
1.15 lukem 821: .Pp
822: Warning: user-space stack trace is valid only if the machine dependent
823: code supports it.
824: .It Xo
1.65 atatat 825: .Ic trace/t Ns Op Cm l
1.15 lukem 826: .Sm off
827: .Op Ar pid
828: .Op Cm , Ar count
829: .Sm on
830: .Xc
831: Stack trace by
832: .Dq thread
1.52 wiz 833: (process, on
1.18 perry 834: .Nx )
835: rather than by stack frame address.
1.15 lukem 836: Note that
837: .Ar pid
838: is interpreted using the current radix, whilst
839: .Ic ps
840: displays pids in decimal; prefix
841: .Ar pid
842: with
843: .Sq 0t
1.30 msaitoh 844: to force it to be interpreted as decimal (see
845: .Sx VARIABLES
1.65 atatat 846: section for radix).
847: If
848: .Cm /l
849: is specified, the trace is printed and also stored in the kernel
850: message buffer.
1.15 lukem 851: .Pp
1.10 sommerfe 852: Warning: trace by pid is valid only if the machine dependent code
853: supports it.
1.44 jhawk 854: .It Ic until Ns Op Cm /p
855: Stop at the next call or return instruction.
1.15 lukem 856: If
1.44 jhawk 857: .Cm /p
858: is specified, print the call nesting depth and the
859: cumulative instruction count at each call or return.
860: Otherwise, only print when the matching return is hit.
1.15 lukem 861: .It Xo
862: .Ic watch
863: .Sm off
864: .Ar address
865: .Op Cm , Ar size
866: .Sm on
867: .Xc
868: Set a watchpoint for a region.
869: Execution stops when an attempt to modify the region occurs.
870: .Ar size
871: defaults to 4.
872: .Pp
873: If you specify a wrong space address, the request is
874: rejected with an error message.
875: .Pp
876: Warning: attempts to watch wired kernel memory may cause
877: an unrecoverable error in some systems such as i386.
878: Watchpoints on user addresses work the best.
1.28 msaitoh 879: .It Xo
1.44 jhawk 880: .Ic write Ns Op Cm /bhl
1.28 msaitoh 881: .Ar address
1.44 jhawk 882: .Ar expression Op Ar expression ...
1.28 msaitoh 883: .Xc
1.44 jhawk 884: Write the
885: .Ar expression Ns s
886: at succeeding locations.
887: The unit size is specified with a modifier character, as per
888: .Ic examine .
889: Valid modifiers are:
890: .Cm /b ,
891: .Cm /h ,
892: and
893: .Cm /l .
894: If no modifier is specified,
895: .Cm /l
896: is used.
897: .Pp
898: Warning: since there is no delimiter between
899: .Ar expression Ns s ,
900: strange things may occur.
901: It's best to enclose each
902: .Ar expression
903: in parentheses.
1.28 msaitoh 904: .It Xo
1.44 jhawk 905: .Ic x Ns Op Cm / Ns Ar modifier
906: .Ar address Ns Op Cm , Ns Ar count
1.41 jhawk 907: .Xc
908: A synonym for
1.44 jhawk 909: .Ic examine .
910: .\" XXX - these commands aren't implemented; jhawk 19 May 2000
911: .\" .It Ic xf
912: .\" Examine forward.
913: .\" .Ic xf
914: .\" re-executes the most recent
915: .\" .Ic execute
916: .\" command with the same parameters except that
917: .\" .Ar address
918: .\" is set to
919: .\" .Ar next .
920: .\" .It Ic xb
921: .\" Examine backward.
922: .\" .Ic xb
923: .\" re-executes the most recent
924: .\" .Ic execute
925: .\" command with the same parameters, except that
926: .\" .Ar address
927: .\" is set to the last start address minus its size.
1.15 lukem 928: .El
1.19 fair 929: .Sh MACHINE-SPECIFIC COMMANDS
930: The "glue" code that hooks
931: .Nm
932: into the
933: .Nx
934: kernel for any given port can also add machine specific commands
935: to the
936: .Nm
937: command parser.
938: All of these commands are preceded by the command word
939: .Em machine
940: to indicate that they are part of the machine-specific command
1.23 fair 941: set (e.g.
1.45 jhawk 942: .Ic "machine reboot" ) .
1.19 fair 943: Some of these commands are:
1.23 fair 944: .Ss ALPHA
1.44 jhawk 945: .Bl -tag -width "intrchain" -compact
1.23 fair 946: .It Ic halt
1.21 fair 947: Call the PROM monitor to halt the CPU.
1.23 fair 948: .It Ic reboot
1.21 fair 949: Call the PROM monitor to reboot the CPU.
1.19 fair 950: .El
1.23 fair 951: .Ss ARM32
1.44 jhawk 952: .Bl -tag -width "intrchain" -compact
1.23 fair 953: .It Ic vmstat
1.19 fair 954: Equivalent to
1.52 wiz 955: .Xr vmstat 1
1.19 fair 956: output with "-s" option (statistics).
1.23 fair 957: .It Ic vnode
1.21 fair 958: Print out a description of a vnode.
1.23 fair 959: .It Ic intrchain
1.21 fair 960: Print the list of IRQ handlers.
1.23 fair 961: .It Ic panic
1.21 fair 962: Print the current "panic" string.
1.23 fair 963: .It Ic frame
1.19 fair 964: Given a trap frame address, print out the trap frame.
965: .El
1.23 fair 966: .Ss MIPS
1.44 jhawk 967: .Bl -tag -width "intrchain" -compact
1.38 soren 968: .It Ic kvtop
969: Print the physical address for a given kernel virtual address.
1.23 fair 970: .It Ic tlb
1.21 fair 971: Print out the Translation Lookaside Buffer (TLB).
1.19 fair 972: Only works in
973: .Nx
1.23 fair 974: kernels compiled with
975: .Dv DEBUG
976: option.
1.58 uch 977: .El
978: .Ss SH3
979: .Bl -tag -width "intrchain" -compact
980: .It Ic tlb
981: Print TLB entries
982: .It Ic cache
983: Print cache entries
984: .It Ic frame
985: Print switch frame and trap frames.
986: .It Ic stack
1.66 wiz 987: Print kernel stack usage.
1.75 wiz 988: Only works in
989: .Nx
990: kernels compiled with the
991: .Dv KSTACK_DEBUG
992: option.
1.19 fair 993: .El
1.23 fair 994: .Ss SPARC
1.44 jhawk 995: .Bl -tag -width "intrchain" -compact
1.23 fair 996: .It Ic prom
1.21 fair 997: Exit to the Sun PROM monitor.
1.49 mrg 998: .El
999: .Ss SPARC64
1000: .Bl -tag -width "intrchain" -compact
1001: .It Ic buf
1002: Print buffer information.
1003: .It Ic ctx
1004: Print process context information.
1005: .It Ic dtlb
1006: Print data translation look-aside buffer context information.
1007: .It Ic dtsb
1008: Display data translation storage buffer information.
1009: .It Ic kmap
1.66 wiz 1010: Display information about the listed mapping in the kernel pmap.
1011: Use the
1.49 mrg 1012: .Dq f
1013: modifier to get a full listing.
1014: .It Ic pcb
1015: Display information about the
1.52 wiz 1016: .Dq struct pcb
1.49 mrg 1017: listed.
1018: .It Ic pctx
1019: Attempt to change process context.
1020: .It Ic page
1021: Display the pointer to the
1022: .Dq struct vm_page
1023: for this physical address.
1024: .It Ic phys
1025: Display physical memory.
1026: .It Ic pmap
1.66 wiz 1027: Display the pmap.
1028: Use the
1.49 mrg 1029: .Dq f
1030: modifier to get a fuller listing.
1031: .It Ic proc
1032: Display some information about the process pointed to, or curproc.
1033: .It Ic prom
1.63 wiz 1034: Enter the OFW PROM.
1.49 mrg 1035: .It Ic pv
1036: Display the
1037: .Dq struct pv_entry
1038: pointed to.
1039: .It Ic stack
1.66 wiz 1040: Dump the window stack.
1041: Use the
1.49 mrg 1042: .Dq u
1043: modifier to get userland information.
1044: .It Ic tf
1.66 wiz 1045: Display full trap frame state.
1046: This is most useful for inclusion with bug reports.
1.49 mrg 1047: .It Ic ts
1048: Display trap state.
1049: .It Ic traptrace
1.66 wiz 1050: Display or set trap trace information.
1051: Use the
1.49 mrg 1052: .Dq r
1053: and
1054: .Dq f
1055: modifiers to get reversed and full information, respectively.
1056: .It Ic uvmdump
1057: Dumps the UVM histories.
1058: .It Ic watch
1.66 wiz 1059: Set or clear a physical or virtual hardware watchpoint.
1060: Pass the address to be watched, or
1.49 mrg 1061: .Dq 0
1.66 wiz 1062: to clear the watchpoint.
1063: Append
1.49 mrg 1064: .Dq p
1.52 wiz 1065: to the watch point to use the physical watchpoint registers.
1.49 mrg 1066: .It Ic window
1067: Print register window information about given address.
1.19 fair 1068: .El
1.23 fair 1069: .Ss SUN3 and SUN3X
1.44 jhawk 1070: .Bl -tag -width "intrchain" -compact
1.23 fair 1071: .It Ic abort
1.19 fair 1072: Drop into monitor via abort (allows continue).
1.23 fair 1073: .It Ic halt
1.19 fair 1074: Exit to Sun PROM monitor as in
1075: .Xr halt 8 .
1.23 fair 1076: .It Ic reboot
1.19 fair 1077: Reboot the machine as in
1078: .Xr reboot 8 .
1.23 fair 1079: .It Ic pgmap
1.19 fair 1080: Given an address, print the address, segment map, page map, and
1081: Page Table Entry (PTE).
1082: .El
1.15 lukem 1083: .Sh VARIABLES
1084: .Nm
1085: accesses registers and variables as
1086: .Cm $ Ns Ar name .
1087: Register names are as per the
1088: .Ic "show registers"
1.1 brezak 1089: command.
1.15 lukem 1090: Some variables are suffixed with numbers, and may have a modifier
1.1 brezak 1091: following a colon immediately after the variable name.
1.15 lukem 1092: For example, register variables may have a
1093: .Sq u
1094: modifier to indicate user register
1095: (e.g.,
1096: .Li "$eax:u" ) .
1097: .Pp
1.1 brezak 1098: Built-in variables currently supported are:
1.44 jhawk 1099: .Bl -tag -offset indent -width "maxwidth" -compact
1.15 lukem 1100: .It Va lines
1101: The number of lines.
1102: This is used by the
1103: .Ic more
1104: feature.
1105: .It Va maxoff
1106: Addresses are printed as
1107: .Li 'symbol'+offset
1108: unless
1109: .Li offset
1110: is greater than
1111: .Va maxoff .
1112: .It Va maxwidth
1.1 brezak 1113: The width of the displayed line.
1.15 lukem 1114: .It Va onpanic
1115: If non-zero (the default),
1116: .Nm
1117: will be invoked when the kernel panics.
1118: If the kernel configuration option
1119: .D1 Cd options DDB_ONPANIC=0
1120: is used,
1121: .Va onpanic
1.52 wiz 1122: will be initialized to off.
1.51 msaitoh 1123: .It Va fromconsole
1124: If non-zero (the default),
1125: the kernel allows to enter
1126: .Nm
1127: from the console (by break signal or special key sequence).
1128: If the kernel configuration option
1129: .D1 Cd options DDB_FROMCONSOLE=0
1130: is used,
1131: .Va fromconsole
1.52 wiz 1132: will be initialized to off.
1.15 lukem 1133: .It Va radix
1134: Input and output radix.
1135: .It Va tabstops
1.1 brezak 1136: Tab stop width.
1.79 reinoud 1137: .It Va tee_msgbuf
1138: If explictly set to non zero (zero is the default) all
1139: .Nm
1140: output will not only be displayed on screen but
1141: also be fed to the msgbuf.
1142: The default of the variable can be set using the kernel configuration option
1143: .D1 Cd options DDB_TEE_MSGBUF=1
1144: wich will initialise
1145: .Va tee_msgbuf
1146: to be 1.
1147: This option is especially handy for poor souls
1148: who don't have a serial console but want to recall
1149: .Nm
1150: output from a crash investigation.
1151: This option is more generic than the /l command modifier possible for
1.80 wiz 1152: selected commands as discussed above to log the output.
1153: Mixing both /l
1.79 reinoud 1154: and this setting can give double loggings.
1.54 jhawk 1155: .\" .It Va work Ns Sy xx
1156: .\" Temporary work variable.
1157: .\" .Sq Sy xx
1158: .\" is between 0 and 31.
1.15 lukem 1159: .El
1160: .Pp
1161: All built-in variables are accessible via
1162: .Xr sysctl 3 .
1163: .Sh EXPRESSIONS
1164: Almost all expression operators in C are supported, except
1.31 mycroft 1165: .Sq \&~ ,
1166: .Sq \&^ ,
1.15 lukem 1167: and unary
1.56 ross 1168: .Sq \&\*[Am] .
1.15 lukem 1169: Special rules in
1170: .Nm
1.1 brezak 1171: are:
1.15 lukem 1172: .Bl -tag -offset indent -width "identifier"
1173: .It Ar identifier
1174: name of a symbol.
1175: It is translated to the address (or value) of it.
1.31 mycroft 1176: .Sq \&.
1.15 lukem 1177: and
1.31 mycroft 1178: .Sq \&:
1.15 lukem 1179: can be used in the identifier.
1180: If supported by an object format dependent routine,
1181: .Sm off
1182: .Xo
1183: .Oo Ar filename : Oc
1184: .Ar function
1185: .Oo : Ar "line number" Oc ,
1186: .Xc
1187: .Xo
1188: .Oo Ar filename : Oc
1189: .Ar variable ,
1190: .Xc
1191: and
1192: .Xo
1193: .Ar filename
1194: .Oo : Ar "line number" Oc ,
1195: .Xc
1196: .Sm on
1.1 brezak 1197: can be accepted as a symbol.
1.15 lukem 1198: The symbol may be prefixed with
1.53 wiz 1199: .Ar symbol_table_name : :
1.15 lukem 1200: (e.g.,
1201: .Li emulator::mach_msg_trap )
1202: to specify other than kernel symbols.
1203: .It Ar number
1204: number.
1205: Radix is determined by the first two characters:
1206: .Sq 0x
1207: - hex,
1208: .Sq 0o
1209: - octal,
1210: .Sq 0t
1211: - decimal,
1212: otherwise follow current radix.
1213: .It Cm .
1214: .Ar dot
1215: .It Cm +
1216: .Ar next
1217: .It Cm ..
1.1 brezak 1218: address of the start of the last line examined.
1.15 lukem 1219: Unlike
1220: .Ar dot
1221: or
1222: .Ar next ,
1223: this is only changed by the
1224: .Ic examine
1225: or
1226: .Ic write
1227: commands.
1.48 jhawk 1228: .It Cm \&"
1.1 brezak 1229: last address explicitly specified.
1.15 lukem 1230: .It Cm $ Ns Ar name
1231: register name or variable.
1232: It is translated to the value of it.
1233: It may be followed by a
1.31 mycroft 1234: .Sq \&:
1.15 lukem 1235: and modifiers as described above.
1236: .It Cm a
1237: multiple of right-hand side.
1238: .It Cm * Ns Ar expr
1239: expression indirection.
1240: It may be followed by a
1.31 mycroft 1241: .Sq \&:
1.15 lukem 1242: and modifiers as described above.
1243: .El
1.53 wiz 1244: .Sh SEE ALSO
1.83 wiz 1245: .Xr reboot 2 ,
1.53 wiz 1246: .Xr options 4 ,
1.81 fredb 1247: .Xr reboot 8 ,
1.77 wiz 1248: .Xr sysctl 8 ,
1249: .Xr cnmagic 9
1.19 fair 1250: .Sh HISTORY
1251: The
1252: .Nm
1253: kernel debugger was written as part of the MACH project at
1254: 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