2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
16 .\" Carnegie Mellon requests users of this software to return to
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
26 .\" changed a \# to #, since groff choked on it.
30 .\" Revision 1.1 1993/07/15 18:41:02 brezak
33 .\" Revision 2.6 92/04/08 08:52:57 rpd
35 .\" [92/01/17 14:19:22 jsb]
36 .\" Changes for OSF debugger modifications.
39 .\" Revision 2.5 91/06/25 13:50:22 rpd
40 .\" Added some watchpoint explanation.
43 .\" Revision 2.4 91/06/17 15:47:31 jsb
44 .\" Added documentation for continue/c, match, search, and watchpoints.
45 .\" I've not actually explained what a watchpoint is; maybe Rich can
46 .\" do that (hint, hint).
47 .\" [91/06/17 10:58:08 jsb]
49 .\" Revision 2.3 91/05/14 17:04:23 mrt
50 .\" Correcting copyright
52 .\" Revision 2.2 91/02/14 14:10:06 mrt
53 .\" Changed to new Mach copyright
54 .\" [91/02/12 18:10:12 mrt]
56 .\" Revision 2.2 90/08/30 14:23:15 dbg
67 .Nd interactive kernel debugger
72 To prevent activation of the debugger on kernel
74 .Cd options KDB_UNATTENDED
78 kernel debugger has most of the features of the old
80 but with a more rational syntax
83 If linked into the running kernel,
84 it can be invoked locally with the
88 The debugger is also invoked on kernel
91 .Va debug.debugger_on_panic
93 MIB variable is set non-zero,
99 The current location is called
104 a hexadecimal format at a prompt.
111 to the address of the last line
112 examined or the last location modified, and set
115 the next location to be examined or changed.
116 Other commands do not change
123 The general command syntax is:
124 .Ar command Ns Op Li / Ns Ar modifier
125 .Ar address Ns Op Li , Ns Ar count
127 A blank line repeats the previous command from the address
130 count 1 and no modifiers.
143 to be 1 for printing commands or infinity for stack traces.
147 debugger has a pager feature (like the
151 If an output line exceeds the number set in the
153 variable, it displays
155 and waits for a response.
156 The valid responses for it are:
158 .Bl -tag -compact -width ".Li SPC"
164 abort the current command, and return to the command input mode
169 provides a small (currently 10 items) command history, and offers
172 command line editing capabilities.
176 control keys, the usual
178 arrow keys might be used to
179 browse through the history buffer, and move the cursor within the
182 .Bl -tag -width indent -compact
185 Display the addressed locations according to the formats in the modifier.
186 Multiple modifier formats display multiple locations.
187 If no format is specified, the last format specified for this command
190 The format characters are:
191 .Bl -tag -compact -width indent
193 look at by bytes (8 bits)
195 look at by half words (16 bits)
197 look at by long words (32 bits)
199 print the location being displayed
201 print the location with a line number if possible
203 display in unsigned hex
205 display in signed hex
207 display in unsigned octal
209 display in signed decimal
211 display in unsigned decimal
213 display in current radix, signed
215 display low 8 bits as a character.
216 Non-printing characters are displayed as an octal escape code (e.g.,
219 display the null-terminated string at the location.
220 Non-printing characters are displayed as octal escapes.
222 display in unsigned hex with character dump at the end of each line.
223 The location is also displayed in hex at the beginning of each line.
225 display as an instruction
227 display as an instruction with possible alternate formats depending on the
229 .Bl -tag -width ".Tn powerpc" -compact
231 Show the registers of the instruction.
249 command with the last specified parameters to it
250 except that the next address displayed by it is used as the start address.
256 command with the last specified parameters to it
257 except that the last start address subtracted by the size displayed by it
258 is used as the start address.
260 .It Ic print Ns Op Li / Ns Cm acdoruxz
261 .It Ic p Ns Op Li / Ns Cm acdoruxz
264 according to the modifier character (as described above for
267 .Cm a , x , z , o , d , u , r ,
270 If no modifier is specified, the last one specified to it is used.
273 can be a string, in which case it is printed as it is.
275 .Bd -literal -offset indent
276 print/x "eax = " $eax "\enecx = " $ecx "\en"
280 .Bd -literal -offset indent
286 .Ic write Ns Op Li / Ns Cm bhl
287 .Ar addr expr1 Op Ar expr2 ...
290 .Ic w Ns Op Li / Ns Cm bhl
291 .Ar addr expr1 Op Ar expr2 ...
293 Write the expressions specified after
295 on the command line at succeeding locations starting with
297 The write unit size can be specified in the modifier with a letter
303 (long word) respectively.
305 long word is assumed.
308 since there is no delimiter between expressions, strange
310 It is best to enclose each expression in parentheses.
312 .It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr
313 Set the named variable or register with the value of
315 Valid variable names are described below.
317 .It Ic break Ns Op Li / Ns Cm u
318 .It Ic b Ns Op Li / Ns Cm u
323 is supplied, continues
325 \- 1 times before stopping at the
327 If the break point is set, a break point number is
330 This number can be used in deleting the break point
331 or adding conditions to it.
335 modifier is specified, this command sets a break point in user space
339 option, the address is considered in the kernel
340 space, and wrong space address is rejected with an error message.
341 This modifier can be used only if it is supported by machine dependent
345 If a user text is shadowed by a normal user space debugger,
346 user space break points may not work correctly.
348 point at the low-level code paths may also cause strange behavior.
350 .It Ic delete Ar addr
352 .It Ic delete Li # Ns Ar number
353 .It Ic d Li # Ns Ar number
354 Delete the break point.
355 The target break point can be specified by a
356 break point number with
360 specified in the original
364 .It Ic watch Ar addr Ns Li , Ns Ar size
365 Set a watchpoint for a region.
366 Execution stops when an attempt to modify the region occurs.
369 argument defaults to 4.
370 If you specify a wrong space address, the request is rejected
371 with an error message.
374 Attempts to watch wired kernel memory
375 may cause unrecoverable error in some systems such as i386.
376 Watchpoints on user addresses work best.
378 .It Ic hwatch Ar addr Ns Li , Ns Ar size
379 Set a hardware watchpoint for a region if supported by the
381 Execution stops when an attempt to modify the region occurs.
384 argument defaults to 4.
387 The hardware debug facilities do not have a concept of separate
388 address spaces like the watch command does.
391 for setting watchpoints on kernel address locations only, and avoid
392 its use on user mode address spaces.
394 .It Ic dhwatch Ar addr Ns Li , Ns Ar size
395 Delete specified hardware watchpoint.
397 .It Ic step Ns Op Li / Ns Cm p
398 .It Ic s Ns Op Li / Ns Cm p
401 times (the comma is a mandatory part of the syntax).
404 modifier is specified, print each instruction at each step.
405 Otherwise, only print the last instruction.
408 depending on machine type, it may not be possible to
409 single-step through some low-level code paths or user space code.
410 On machines with software-emulated single-stepping (e.g., pmax),
411 stepping through code executed by interrupt handlers will probably
414 .It Ic continue Ns Op Li / Ns Cm c
415 .It Ic c Ns Op Li / Ns Cm c
416 Continue execution until a breakpoint or watchpoint.
419 modifier is specified, count instructions while executing.
420 Some machines (e.g., pmax) also count loads and stores.
423 when counting, the debugger is really silently single-stepping.
424 This means that single-stepping on low-level code may cause strange
427 .It Ic until Ns Op Li / Ns Cm p
428 Stop at the next call or return instruction.
431 modifier is specified, print the call nesting depth and the
432 cumulative instruction count at each call or return.
434 only print when the matching return is hit.
436 .It Ic next Ns Op Li / Ns Cm p
437 .It Ic match Ns Op Li / Ns Cm p
438 Stop at the matching return instruction.
441 modifier is specified, print the call nesting depth and the
442 cumulative instruction count at each call or return.
443 Otherwise, only print when the matching return is hit.
446 .Ic trace Ns Op Li / Ns Cm u
451 .Ic t Ns Op Li / Ns Cm u
456 .Ic where Ns Op Li / Ns Cm u
461 .Ic bt Ns Op Li / Ns Cm u
468 option traces user space; if omitted,
472 The optional argument
474 is the number of frames to be traced.
477 is omitted, all frames are printed.
480 User space stack trace is valid
481 only if the machine dependent code supports it.
484 .Ic search Ns Op Li / Ns Cm bhl
492 This command might fail in interesting
493 ways if it does not find the searched-for value.
496 does not always recover from touching bad memory.
499 argument limits the search.
501 .It Ic show Cm all procs Ns Op Li / Ns Cm m
502 .It Ic ps Ns Op Li / Ns Cm m
503 Display all process information.
504 The process information may not be shown if it is not
505 supported in the machine, or the bottom of the stack of the
506 target process is not in the main memory at that time.
509 modifier will alter the display to show VM map
510 addresses for the process and not show other info.
512 .It Ic show Cm registers Ns Op Li / Ns Cm u
513 Display the register set.
516 modifier is specified, it displays user registers instead of
517 kernel or currently saved one.
522 modifier depends on the machine.
523 If not supported, incorrect information will be displayed.
525 .It Ic show Cm geom Op Ar addr
528 argument is not given, displays the entire GEOM topology.
531 is given, displays details about the given GEOM object (class, geom, provider
534 .It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr
539 modifier is specified the
540 complete map is printed.
542 .It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr
543 Prints the VM object at
547 option is specified the
548 complete object is printed.
550 .It Ic show Cm vnode Ar addr
551 Displays details about the given vnode.
553 .It Ic show Cm watches
554 Displays all watchpoints.
557 Toggles between remote GDB and DDB mode.
558 In remote GDB mode, another machine is required that runs
560 using the remote debug feature, with a connection to the serial
561 console port on the target machine.
562 Currently only available on the
569 .It Ic kill Ar sig pid
574 The signal is acted on upon returning from the debugger.
575 This command can be used to kill a process causing resource contention
576 in the case of a hung system.
579 for a list of signals.
580 Note that the arguments are reversed relative to
585 Hard reset the system.
588 Print a short summary of the available commands and command
592 The debugger accesses registers and variables as
594 Register names are as in the
595 .Dq Ic show Cm registers
597 Some variables are suffixed with numbers, and may have some modifier
598 following a colon immediately after the variable name.
599 For example, register variables can have a
601 modifier to indicate user register (e.g.,
604 Built-in variables currently supported are:
606 .Bl -tag -width ".Va tabstops" -compact
608 Input and output radix.
610 Addresses are printed as
611 .Dq Ar symbol Ns Li + Ns Ar offset
617 The width of the displayed line.
620 It is used by the built-in pager.
626 can take values from 0 to 31.
629 Most expression operators in C are supported except
637 .Bl -tag -width ".No Identifiers"
639 The name of a symbol is translated to the value of the symbol, which
640 is the address of the corresponding object.
644 can be used in the identifier.
645 If supported by an object format dependent routine,
647 .Oo Ar filename : Oc Ar func : lineno ,
649 .Oo Ar filename : Oc Ns Ar variable ,
651 .Oo Ar filename : Oc Ns Ar lineno
652 can be accepted as a symbol.
654 Radix is determined by the first two letters:
660 decimal; otherwise, follow current radix.
666 address of the start of the last line examined.
671 this is only changed by
677 last address explicitly specified.
678 .It Li $ Ns Ar variable
679 Translated to the value of the specified variable.
680 It may be followed by a
682 and modifiers as described above.
683 .It Ar a Ns Li # Ns Ar b
684 A binary operator which rounds up the left hand side to the next
685 multiple of right hand side.
688 It may be followed by a
690 and modifiers as described above.
693 On machines with an ISA expansion bus, a simple NMI generation card can be
694 constructed by connecting a push button between the A01 and B01 (CHCHK# and
696 Momentarily shorting these two fingers together may cause the bridge chipset to
697 generate an NMI, which causes the kernel to pass control to
699 Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary.
700 The NMI allows one to break into the debugger on a wedged machine to
702 Other bus' bridge chipsets may be able to generate NMI using bus specific
709 debugger was developed for Mach, and ported to
711 This manual page translated from
714 .An Garrett Wollman .