xref: /freebsd/share/man/man4/ddb.4 (revision 6990ffd8a95caaba6858ad44ff1b3157d1efba8f)
1.\"
2.\" Mach Operating System
3.\" Copyright (c) 1991,1990 Carnegie Mellon University
4.\" All Rights Reserved.
5.\"
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.
11.\"
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.
15.\"
16.\" Carnegie Mellon requests users of this software to return to
17.\"
18.\"  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
19.\"  School of Computer Science
20.\"  Carnegie Mellon University
21.\"  Pittsburgh PA 15213-3890
22.\"
23.\" any improvements or extensions that they make and grant Carnegie Mellon
24.\" the rights to redistribute these changes.
25.\"
26.\" changed a \# to #, since groff choked on it.
27.\"
28.\" HISTORY
29.\" ddb.4,v
30.\" Revision 1.1  1993/07/15  18:41:02  brezak
31.\" Man page for DDB
32.\"
33.\" Revision 2.6  92/04/08  08:52:57  rpd
34.\" 	Changes from OSF.
35.\" 	[92/01/17  14:19:22  jsb]
36.\" 	Changes for OSF debugger modifications.
37.\" 	[91/12/12            tak]
38.\"
39.\" Revision 2.5  91/06/25  13:50:22  rpd
40.\" 	Added some watchpoint explanation.
41.\" 	[91/06/25            rpd]
42.\"
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]
48.\"
49.\" Revision 2.3  91/05/14  17:04:23  mrt
50.\" 	Correcting copyright
51.\"
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]
55.\"
56.\" Revision 2.2  90/08/30  14:23:15  dbg
57.\" 	Created.
58.\" 	[90/08/30            dbg]
59.\"
60.\" $FreeBSD$
61.Dd January 16, 1996
62.Dt DDB 4
63.Os
64.Sh NAME
65.Nm ddb
66.Nd interactive kernel debugger
67.Sh SYNOPSIS
68.Cd options DDB
69.Pp
70To prevent activation of the debugger on kernel
71.Xr panic 9 :
72.Cd options DDB_UNATTENDED
73.Sh DESCRIPTION
74The
75.Nm
76kernel debugger has most of the features of the old kdb,
77but with a more rational syntax
78inspired by
79.Xr gdb 1 .
80If linked into the running kernel,
81it can be invoked locally with the
82.Ql debug
83.Xr keymap 5
84action.
85The debugger is also invoked on kernel
86.Xr panic 9
87if the
88.Va debug.debugger_on_panic
89.Xr sysctl 8
90MIB variable is set non-zero,
91which is the default
92unless the
93.Dv DDB_UNATTENDED
94option is specified.
95.Pp
96The current location is called `dot'.  The `dot' is displayed with
97a hexadecimal format at a prompt.
98Examine and write commands update `dot' to the address of the last line
99examined or the last location modified, and set `next' to the address of
100the next location to be examined or changed.
101Other commands don't change `dot', and set `next' to be the same as `dot'.
102.Pp
103The general command syntax is:
104.Cm command Ns Op Li \&/ Ns Ar modifier
105.Ar address Ns Op Li , Ns Ar count
106.Pp
107A blank line repeats the previous command from the address `next' with
108count 1 and no modifiers.  Specifying
109.Ar address
110sets `dot' to the
111address.  Omitting
112.Ar address
113uses `dot'.  A missing
114.Ar count
115is taken
116to be 1 for printing commands or infinity for stack traces.
117.Pp
118The
119.Nm
120debugger has a feature like the
121.Xr more 1
122command
123for the output.  If an output line exceeds the number set in the
124.Li \&$lines
125variable, it displays
126.Dq Em --db_more--
127and waits for a response.
128The valid responses for it are:
129.Pp
130.Bl -tag -compact -width SPC
131.It Li SPC
132one more page
133.It Li RET
134one more line
135.It Li q
136abort the current command, and return to the command input mode
137.El
138.Pp
139Finally,
140.Nm
141provides a small (currently 10 items) command history, and offers
142simple emacs-style command line editing capabilities.  In addition to
143the emacs control keys, the usual ANSI arrow keys might be used to
144browse through the history buffer, and move the cursor within the
145current line.
146.Sh COMMANDS
147.Bl -ohang
148.It Cm examine
149.It Cm x
150Display the addressed locations according to the formats in the modifier.
151Multiple modifier formats display multiple locations.
152If no format is specified, the last formats specified for this command
153is used.
154.Pp
155The format characters are:
156.Bl -tag -compact -width indent
157.It Li b
158look at by bytes (8 bits)
159.It Li h
160look at by half words (16 bits)
161.It Li l
162look at by long words (32 bits)
163.It Li a
164print the location being displayed
165.It Li A
166print the location with a line number if possible
167.It Li x
168display in unsigned hex
169.It Li z
170display in signed hex
171.It Li o
172display in unsigned octal
173.It Li d
174display in signed decimal
175.It Li u
176display in unsigned decimal
177.It Li r
178display in current radix, signed
179.It Li c
180display low 8 bits as a character.
181Non-printing characters are displayed as an octal escape code (e.g., `\e000').
182.It Li s
183display the null-terminated string at the location.
184Non-printing characters are displayed as octal escapes.
185.It Li m
186display in unsigned hex with character dump at the end of each line.
187The location is also displayed in hex at the beginning of each line.
188.It Li i
189display as an instruction
190.It Li I
191display as an instruction with possible alternate formats depending on the
192machine:
193.Bl -tag -width MIPS -compact
194.It Tn VAX
195don't assume that each external label is a procedure entry mask
196.It Tn i386
197don't round to the next long word boundary
198.It Tn MIPS
199print register contents
200.El
201.El
202.It Cm xf
203Examine forward:
204Execute an examine command with the last specified parameters to it
205except that the next address displayed by it is used as the start address.
206.It Cm xb
207Examine backward:
208Execute an examine command with the last specified parameters to it
209except that the last start address subtracted by the size displayed by it
210is used as the start address.
211.It Cm print Ns Op Cm /acdoruxz
212Print
213.Ar addr Ns s
214according to the modifier character (as described above for
215.Li examine ) .
216Valid formats are:
217.Li a ,
218.Li x ,
219.Li z ,
220.Li o ,
221.Li d ,
222.Li u ,
223.Li r ,
224and
225.Li c .
226If no modifier is specified, the last one specified to it is used.
227.Ar addr
228can be a string, in which case it is printed as it is.  For example:
229.Bd -literal -offset indent
230print/x \&"eax = \&" $eax \&"\enecx = \&" $ecx \&"\en\&"
231.Ed
232.Pp
233will print like:
234.Bd -literal -offset indent
235eax = xxxxxx
236ecx = yyyyyy
237.Ed
238.It Xo
239.Cm write Ns Op Cm /bhl
240.Ar addr Ar expr1 Op Ar "expr2 ..."
241.Xc
242Write the expressions specified after
243.Ar addr
244on the command line at succeeding locations starting with
245.Ar addr
246The write unit size can be specified in the modifier with a letter
247.Li b
248(byte),
249.Li h
250(half word) or
251.Li l
252(long word) respectively.  If omitted,
253long word is assumed.
254.Pp
255.Sy Warning :
256since there is no delimiter between expressions, strange
257things may happen.
258It's best to enclose each expression in parentheses.
259.It Xo
260.Cm set
261.Li \&$ Ns Ar variable
262.Op Li =
263.Ar expr
264.Xc
265Set the named variable or register with the value of
266.Ar expr .
267Valid variable names are described below.
268.It Cm break Ns Op Cm /u
269Set a break point at
270.Ar addr .
271If
272.Ar count
273is supplied, continues
274.Ar count
275- 1 times before stopping at the
276break point.  If the break point is set, a break point number is
277printed with
278.Sq Li \&# .
279This number can be used in deleting the break point
280or adding conditions to it.
281.Pp
282If the
283.Li u
284modifier is specified, this command sets a break point in user space
285address.  Without the
286.Li u
287option, the address is considered in the kernel
288space, and wrong space address is rejected with an error message.
289This modifier can be used only if it is supported by machine dependent
290routines.
291.Pp
292.Sy Warning :
293If a user text is shadowed by a normal user space debugger,
294user space break points may not work correctly.  Setting a break
295point at the low-level code paths may also cause strange behavior.
296.It Cm delete Ar addr
297.It Cm delete Li \&# Ns Ar number
298Delete the break point.  The target break point can be specified by a
299break point number with
300.Li # ,
301or by using the same
302.Ar addr
303specified in the original
304.Cm break
305command.
306.It Cm step Ns Op Cm /p
307Single step
308.Ar count
309times (the comma is a mandatory part of the syntax).
310If the
311.Li p
312modifier is specified, print each instruction at each step.
313Otherwise, only print the last instruction.
314.Pp
315.Sy Warning :
316depending on machine type, it may not be possible to
317single-step through some low-level code paths or user space code.
318On machines with software-emulated single-stepping (e.g., pmax),
319stepping through code executed by interrupt handlers will probably
320do the wrong thing.
321.It Cm continue Ns Op Cm /c
322Continue execution until a breakpoint or watchpoint.
323If the
324.Li c
325modifier is specified, count instructions while executing.
326Some machines (e.g., pmax) also count loads and stores.
327.Pp
328.Sy Warning :
329when counting, the debugger is really silently single-stepping.
330This means that single-stepping on low-level code may cause strange
331behavior.
332.It Cm until Ns Op Cm /p
333Stop at the next call or return instruction.
334If the
335.Li p
336modifier is specified, print the call nesting depth and the
337cumulative instruction count at each call or return.  Otherwise,
338only print when the matching return is hit.
339.It Cm next Ns Op Cm /p
340.It Cm match Ns Op Cm /p
341Stop at the matching return instruction.
342If the
343.Li p
344modifier is specified, print the call nesting depth and the
345cumulative instruction count at each call or return.  Otherwise,
346only print when the matching return is hit.
347.It Xo
348.Cm trace Ns Op Cm /u
349.Op Ar frame
350.Op , Ns Ar count
351.Xc
352Stack trace.  The
353.Li u
354option traces user space; if omitted,
355.Cm trace
356only traces
357kernel space.
358.Ar count
359is the number of frames to be traced.
360If
361.Ar count
362is omitted, all frames are printed.
363.Pp
364.Sy Warning :
365User space stack trace is valid
366only if the machine dependent code supports it.
367.It Xo
368.Cm search Ns Op Cm /bhl
369.Ar addr
370.Ar value
371.Op Ar mask
372.Op , Ns Ar count
373.Xc
374Search memory for
375.Ar value .
376This command might fail in interesting
377ways if it doesn't find the searched-for value.  This is because
378ddb doesn't always recover from touching bad memory.  The optional
379.Ar count
380argument limits the search.
381.It Cm show all procs Ns Op Cm /m
382.It Cm ps Ns Op Cm /m
383Display all process information.
384The process information may not be shown if it is not
385supported in the machine, or the bottom of the stack of the
386target process is not in the main memory at that time.
387The
388.Li m
389modifier will alter the display to show VM map
390addresses for the process and not show other info.
391.It Cm show registers Ns Op Cm /u
392Display the register set.
393If the
394.Li u
395option is specified, it displays user registers instead of
396kernel or currently saved one.
397.Pp
398.Sy Warning :
399The support of the
400.Li u
401modifier depends on the machine.  If
402not supported, incorrect information will be displayed.
403.It Xo
404.Cm show map Ns Op Cm /f
405.Ar addr
406.Xc
407Prints the VM map at
408.Ar addr .
409If the
410.Li f
411modifier is specified the
412complete map is printed.
413.It Xo
414.Cm show object Ns Op Cm /f
415.Ar addr
416.Xc
417Prints the VM object at
418.Ar addr .
419If the
420.Li f
421option is specified the
422complete object is printed.
423.It Cm "show watches"
424Displays all watchpoints.
425.It Xo
426.Cm watch
427.Ar addr Ns Li \&, Ns Ar size
428.Xc
429Set a watchpoint for a region.  Execution stops
430when an attempt to modify the region occurs.
431The
432.Ar size
433argument defaults to 4.
434If you specify a wrong space address, the request is rejected
435with an error message.
436.Pp
437.Sy Warning :
438Attempts to watch wired kernel memory
439may cause unrecoverable error in some systems such as i386.
440Watchpoints on user addresses work best.
441.It Xo
442.Cm hwatch
443.Ar addr Ns Li \&, Ns Ar size
444.Xc
445Set a hardware watchpoint for a region if supported by the
446architecture.  Execution stops when an attempt to modify the region
447occurs.  The
448.Ar size
449argument defaults to 4.
450.Pp
451.Sy Warning :
452The hardware debug facilities do not have a concept of seperate
453address spaces like the watch command does.  Use
454.Cm hwatch
455for setting watchpoints on kernel address locations only, and avoid
456its use on user mode address spaces.
457.It Xo
458.Cm dhwatch
459.Ar addr Ns Li \&, Ns Ar size
460.Xc
461Delete specified hardware watchpoint.
462.It Cm gdb
463Toggles between remote GDB and DDB mode.  In remote GDB mode, another
464machine is required that runs
465.Xr gdb 1
466using the remote debug feature, with a connection to the serial
467console port on the target machine.  Currently only available on the
468.Em i386
469and
470.Em Alpha
471architectures.
472.It Cm help
473Print a short summary of the available commands and command
474abbreviations.
475.El
476.Sh VARIABLES
477The debugger accesses registers and variables as
478.Li \&$ Ns Em name .
479Register names are as in the
480.Dq Cm show registers
481command.
482Some variables are suffixed with numbers, and may have some modifier
483following a colon immediately after the variable name.
484For example, register variables can have a
485.Li u
486modifier to indicate user register (e.g.,
487.Li $eax:u ) .
488.Pp
489Built-in variables currently supported are:
490.Bl -tag -width tabstops -compact
491.It Li radix
492Input and output radix
493.It Li maxoff
494Addresses are printed as 'symbol'+offset unless offset is greater than maxoff.
495.It Li maxwidth
496The width of the displayed line.
497.It Li lines
498The number of lines.  It is used by "more" feature.
499.It Li tabstops
500Tab stop width.
501.It Li work Ns Ar xx
502Work variable.
503.Ar xx
504can be 0 to 31.
505.El
506.Sh EXPRESSIONS
507Almost all expression operators in C are supported except
508.Sq Li \&~ ,
509.Sq Li \&^ ,
510and unary
511.Sq Li \&& .
512Special rules in
513.Nm
514are:
515.Bl -tag -width Identifiers
516.It Em Identifiers
517The name of a symbol is translated to the value of the symbol, which
518is the address of the corresponding object.
519.Sq Li \&.
520and
521.Sq Li \&:
522can be used in the identifier.
523If supported by an object format dependent routine,
524.Sm off
525.Oo Em filename : Oc Em func : lineno ,
526.Sm on
527.Oo Em filename : Oc Ns Em variable ,
528and
529.Oo Em filename : Oc Ns Em lineno
530can be accepted as a symbol.
531.It Em Numbers
532Radix is determined by the first two letters:
533.Li 0x :
534hex,
535.Li 0o :
536octal,
537.Li 0t :
538decimal; otherwise, follow current radix.
539.It Li \&.
540`dot'
541.It Li \&+
542`next'
543.It Li \&..
544address of the start of the last line examined.
545Unlike `dot' or `next', this is only changed by
546.Dq Li examine
547or
548.Dq Li write
549command.
550.It Li \&'
551last address explicitly specified.
552.It Li \&$ Ns Em variable
553Translated to the value of the specified variable.
554It may be followed by a
555.Li :
556and modifiers as described above.
557.It Em a Ns Li \&# Ns Em b
558a binary operator which rounds up the left hand side to the next
559multiple of right hand side.
560.It Li \&* Ns Em expr
561indirection.  It may be followed by a
562.Sq Li :
563and modifiers as described above.
564.El
565.Sh HINTS
566On machines with an ISA expansion bus, a simple NMI generation card can be
567constructed by connecting a push button between the A01 and B01 (CHCHK# and
568GND) card fingers.
569Momentarily shorting these two fingers together may cause the bridge chipset to
570generate an NMI, which causes the kernel to pass control to
571.Nm .
572Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary.
573The NMI allows one to break into the debugger on a wedged machine to
574diagnose problems.
575Other bus' bridge chipsets may be able to generate NMI using bus specific
576methods.
577.Sh SEE ALSO
578.Xr gdb 1
579.Sh HISTORY
580The
581.Nm
582debugger was developed for Mach, and ported to
583.Bx 386 0.1 .
584This manual page translated from
585.Fl man
586macros by Garrett Wollman.
587