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