FreeBSD/Linux Kernel Cross Reference
sys/man/ddb.man
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 .\"
27 .\" HISTORY
28 .\" $Log: ddb.man,v $
29 .\" Revision 2.7 93/03/09 18:01:38 danner
30 .\" Added , modifier to examine
31 .\" [93/03/09 jfriedl]
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 .TH ddb 8
61 .SH NAME
62 ddb \- new kernel debugger
63 .de XX
64 .sp
65 .ti -4n
66 \\$1
67 .br
68 .sp
69 ..
70 .de XS
71 .nr )R +\\$1
72 ..
73 .de XE
74 .nr )R -\\$1
75 ..
76 .SH DESCRIPTION
77 .br
78 .sp
79 The new kernel debugger has most of the features of the old kdb,
80 but with a more rational (gdb-like) syntax.
81 .sp
82 The current location is called 'dot'. The 'dot' is displayed with
83 a hexadecimal format at a prompt.
84 Examine and write commands update 'dot' to the address of the last line
85 examined or the last location modified, and set 'next' to the address of
86 the next location to be examined or changed.
87 Other commands don't change 'dot', and set 'next' to be the same as 'dot'.
88 .sp
89 The general command syntax is:
90 .sp
91 .ti +4n
92 \fIcommand[/modifier] address [,count]\fR
93 .sp
94 "!!" repeats the previous command, and
95 a blank line repeats from the address 'next' with count 1 and no modifiers.
96 Specifying 'address' sets 'dot' to the address.
97 Omitting 'address' uses 'dot'.
98 A missing 'count' is taken to be 1 for printing commands or infinity
99 for stack traces.
100 .sp
101 Current
102 .B ddb
103 is enhanced to support multi-thread debugging. A break point can be
104 set only for a specific thread, and the address space or registers of
105 non current thread can be examined or modified if supported by machine
106 dependent routines.
107 For example,
108 .sp
109 .ti +4n
110 break/t mach_msg_trap $task11.0
111 .sp
112 sets a break point at "mach_msg_trap" for the first thread
113 of task 11 listed by a "show all threads" command.
114 .br
115 In the above example, "$task11.0" is translated to the corresponding
116 thread structure's address by variable translation mechanism described later.
117 If a default target thread is set in a variable "$thread", the "$task11.0"
118 can be omitted.
119 In general, if 't' is specified in a modifier of a command line,
120 a specified thread or a default target thread is used as a target thread
121 instead of the current one.
122 The 't' modifier in a command line is not valid in evaluating
123 expressions in a command line. If you want to get a value indirectly
124 from a specific thread's address space or access to its registers within
125 an expression, you have to specify a default target thread in advance,
126 and to use ":t" modifier immediately after the indirect access or the register
127 reference like as follows:
128 .sp
129 .ti +4n
130 set $thread $task11.0
131 .br
132 .ti +4n
133 print $eax:t *(0x100):tuh
134 .sp
135 No sign extension and indirection size(long, half word, byte)
136 can be specified with 'u', 'l', 'h' and 'b' respectively
137 for the indirect access.
138 .br
139 Note: Support of non current space/register access and user space
140 break point depend on the machines. If not supported, attempts of
141 such operation may provide incorrect information or may cause strange
142 behavior. Even if supported, the user space access is limited
143 to the pages resident in the main memory at that time. If a target
144 page is not in the main memory, an error will be reported.
145 .sp
146 "\fBddb\fR" has a feature like a command "\fBmore\fR"
147 for the output. If an output line exceeds the number set in the $lines
148 variable, it displays "\fI--db_more--\fR"
149 and waits for a response.
150 The valid responses for it are:
151 .XS 4n
152 .IP \fI\<space>\fR 10n
153 one more page
154 .IP \fI\<return>\fR 10n
155 one more line
156 .IP \fB\q\fR 10n
157 abort the current command, and return to the command input mode.
158 .LP
159 .sp
160 .XE 4n
161 .LP
162 .B COMMANDS
163 .sp
164 .XS 4n
165 .LP
166 .XX "\fBexamine(x) \fI[/<modifier>] <addr>[,<count>] [ <thread> ]\fR"
167 Display the addressed locations according to the formats in the modifier.
168 Multiple modifier formats display multiple locations.
169 If no format is specified, the last formats specified for this command
170 is used.
171 Address space other than that of the current thread can be specified
172 with 't' option in the modifier and 'thread' parameter.
173 .br
174 The format characters are
175 .sp
176 .LP
177 .XS 2n
178 .IP b 5n
179 look at by bytes(8 bits)
180 .IP h 5n
181 look at by half words(16 bits)
182 .IP l 5n
183 look at by long words(32 bits)
184 .IP a 5n
185 print the location being displayed
186 .IP , 5n
187 skip one unit producing no output
188 .IP A 5n
189 print the location with a line number if possible
190 .IP x 5n
191 display in unsigned hex
192 .IP z 5n
193 display in signed hex
194 .IP o 5n
195 display in unsigned octal
196 .IP d 5n
197 display in signed decimal
198 .IP u 5n
199 display in unsigned decimal
200 .IP r 5n
201 display in current radix, signed
202 .IP c 5n
203 display low 8 bits as a character.
204 Non-printing characters are displayed as an octal escape code (e.g. '\\000').
205 .IP s 5n
206 display the null-terminated string at the location.
207 Non-printing characters are displayed as octal escapes.
208 .IP m 5n
209 display in unsigned hex with character dump at the end of each line.
210 The location is also displayed in hex at the beginning of each line.
211 .IP i 5n
212 display as an instruction
213 .IP I 5n
214 display as an instruction with possible alternate formats depending on the
215 machine:
216 .XE 2n
217 .LP
218 .XS 5n
219 .LP
220 .IP vax 6n
221 don't assume that each external label is a procedure entry mask
222 .IP i386 6n
223 don't round to the next long word boundary
224 .IP mips 6n
225 print register contents
226 .LP
227 .XE 5n
228 .LP
229 .XX xf
230 Examine forward.
231 It executes an examine command with the last specified parameters to it
232 except that the next address displayed by it is used as the start address.
233 .XX xb
234 Examine backward.
235 It executes an examine command with the last specified parameters to it
236 except that the last start address subtracted by the size displayed by it
237 is used as the start address.
238 .XX "\fBprint[/axzodurc] \fI<addr1> [ <addr2> ... ]\fR"
239 Print 'addr's according to the modifier character.
240 Valid formats are: a x z o d u r c.
241 If no modifier is specified, the last one specified to it is used. 'addr'
242 can be a string, and it is printed as it is. For example,
243 .br
244 .sp
245 .ti +4n
246 print/x "eax = " $eax "\\necx = " $ecx "\\n"
247 .br
248 .sp
249 will print like
250 .sp
251 .in +4n
252 eax = xxxxxx
253 .br
254 ecx = yyyyyy
255 .in -4n
256 .sp
257 .br
258 .XX "\fBwrite[/bhlt] \fI<addr> [ <thread> ] <expr1> [ <expr2> ... ]\fR"
259 Write the expressions at succeeding locations.
260 The write unit size can be specified in the modifier with a letter
261 b (byte), h (half word) or l(long word) respectively. If omitted,
262 long word is assumed. Target address space can also be specified
263 with 't' option in the modifier and 'thread' parameter.
264 .br
265 Warning: since there is no delimiter between expressions, strange
266 things may happen.
267 It's best to enclose each expression in parentheses.
268 .XX "\fBset \fI$<variable> [=] <expr>\fR"
269 Set the named variable or register with the value of 'expr'.
270 Valid variable names are described below.
271 .XX "\fBbreak[/tuTU] \fI<addr>[,<count>] [ <thread1> ...]\fR"
272 Set a break point at 'addr'.
273 If count is supplied, continues (count-1) times before stopping at the
274 break point. If the break point is set, a break point number is
275 printed with '#'. This number can be used in deleting the break point
276 or adding conditions to it.
277 .LP
278 .XS 2n
279 .IP t 5n
280 Set a break point only for a specific thread. The thread is specified
281 by 'thread' parameter, or default one is used if the parameter is omitted.
282 .IP u 5n
283 Set a break point in user space address. It may be combined with 't' or 'T'
284 option to specify the non-current target user space. Without 'u' option,
285 the address is considered in the kernel space, and wrong space address
286 is rejected with an error message.
287 This option can be used only if it is supported by machine dependent
288 routines.
289 .IP T 5n
290 Set a break point only for threads in a specific task. It is like 't'
291 option except that the break point is valid for all threads which belong
292 to the same task as the specified target thread.
293 .IP U 5n
294 Set a break point in shared user space address. It is like 'u' option,
295 except that the break point is valid for all threads which share the
296 same address space even if 't' option is specified. 't' option is used
297 only to specify the target shared space. Without 't' option, 'u' and 'U'
298 have the same meanings. 'U' is useful for setting a user space
299 break point in non-current address space with 't' option such as in an
300 emulation library space.
301 This option can be used only if it is supported by machine dependent
302 routines.
303 .LP
304 .XE 2n
305 Warning: if a user text is shadowed by a normal user space debugger,
306 user space break points may not work correctly. Setting a break
307 point at the low-level code paths may also cause strange behavior.
308 .XX "\fBdelete[/tuTU] \fI<addr>|#<number> [ <thread1> ...]\fR"
309 Delete the break point. The target break point can be specified by a
310 break point number with '#', or by 'addr' like specified in 'break'
311 command.
312 .XX "\fBcond \fI#<number> [ <condition> <commands> ]\fR"
313 Set or delete a condition for the break point specified by the 'number'.
314 If the 'condition' and 'commands' are null, the condition is deleted.
315 Otherwise the condition is set for it.
316 When the break point is hit, the 'condition' is evaluated.
317 The 'commands' will be executed if the condition is true and the break
318 point count set by a break point command becomes zero. 'commands' is
319 a list of commands separated by semicolons.
320 Each command in the list is executed in that order, but if a "continue"
321 command is executed, the command execution stops there, and the stopped
322 thread resumes execution. If the command execution reaches the
323 end of the list, and it enters into a command input mode.
324 .br
325 For example,
326 .sp
327 .nf
328 set $work0 0
329 break/Tu xxx_start $task7.0
330 cond #1 (1) set $work0 1; set $work1 0; cont
331 break/T vm_fault $task7.0
332 cond #2 ($work0) set $work1 ($work1+1); cont
333 break/Tu xxx_end $task7.0
334 cond #3 ($work0) print $work1 " faults\\n"; set $work0 0
335 cont
336 .br
337 .fi
338 .sp
339 will print page fault counts from 'xxx_start' to 'xxx_end' in task7.
340 .br
341 .XX "\fBstep[/p] \fI[,<count>]\fR"
342 Single step 'count' times.
343 If 'p' option is specified, print each instruction at each step.
344 Otherwise, only print the last instruction.
345 .br
346 .sp
347 Warning: depending on machine type, it may not be possible to
348 single-step through some low-level code paths or user space code.
349 On machines with software-emulated single-stepping (e.g., pmax),
350 stepping through code executed by interrupt handlers will probably
351 do the wrong thing.
352 .XX "\fBcontinue[/c]\fR"
353 Continue execution until a breakpoint or watchpoint.
354 If /c, count instructions while executing.
355 Some machines (e.g., pmax) also count loads and stores.
356 .br
357 .sp
358 Warning: when counting, the debugger is really silently single-stepping.
359 This means that single-stepping on low-level code may cause strange
360 behavior.
361 .XX "\fBuntil\fR"
362 Stop at the next call or return instruction.
363 .XX "\fBnext[/p]\fR"
364 Stop at the matching return instruction.
365 If 'p' option is specified, print the call nesting depth and the
366 cumulative instruction count at each call or return. Otherwise,
367 only print when the matching return is hit.
368 .XX "\fBmatch[/p]\fR"
369 A synonym for 'next'.
370 .XX "\fBtrace[/tu] \fI[ <frame_addr>|<thread> ][,<count>]\fR"
371 Stack trace. 'u' option traces user space; if omitted, only traces
372 kernel space. If 't' option is specified, it shows the stack trace
373 of the specified thread or a default target thread.
374 Otherwise, it shows the stack trace of the current thread from the
375 frame address specified by a parameter or from the current frame. 'count'
376 is the number of frames to be traced. If the 'count' is omitted,
377 all frames are printed.
378 .br
379 .sp
380 Warning: If the target thread's stack is not in the main memory at that
381 time, the stack trace will fail. User space stack trace is valid
382 only if the machine dependent code supports it.
383 .XX "\fBsearch[/bhl] \fI<addr> <value> [<mask>] [,<count>]\fR"
384 Search memory for a value. This command might fail in interesting
385 ways if it doesn't find the searched-for value. This is because
386 ddb doesn't always recover from touching bad memory. The optional
387 count argument limits the search.
388 .XX "\fBmacro \fI<name> <commands>\fR"
389 Define a debugger macro as 'name'. 'commands' is a list of commands
390 to be associated with the macro.
391 In the expressions of the command list, a variable
392 .B $arg\fIxx\fR
393 can be used to get a parameter passed to the macro.
394 When a macro is called, each argument is evaluated as an expression,
395 and the value is assigned to each parameter,
396 .B $arg1, $arg2, ...
397 respectively. 10
398 .B $arg
399 variables are reserved to each level of macros, and they can be used
400 as local variables.
401 The nesting of macro can be allowed up to 5 levels.
402 .br
403 For example,
404 .sp
405 .nf
406 macro xinit set $work0 $arg1
407 macro xlist examine/m $work0,4; set $work0 *($work0)
408 xinit *(xxx_list)
409 xlist
410 ....
411 .sp
412 will print the contents of a list starting from 'xxx_list'
413 by each "xlist" command.
414 .fi
415 .XX "\fBdmacro \fI<name>\fR"
416 Delete the macro named 'name'.
417 .XX "\fBshow all threads[/ul]\fR"
418 Display all tasks and threads information.
419 This version of "\fBddb\fR"
420 prints more information than previous one.
421 It shows UNIX process information like "ps" for each task.
422 The UNIX process information may not be shown if it is not
423 supported in the machine, or the bottom of the stack of the
424 target task is not in the main memory at that time.
425 .br
426 It also shows task and thread identification numbers.
427 These numbers can be used to specify a task or a thread
428 symbolically in various commands.
429 The numbers are valid only in the same debugger session.
430 If the execution is resumed again, the numbers may change.
431 The current thread can be distinguished from others by a '#' after
432 the thread id instead of ':'.
433 .br
434 Without 'l' option, it only shows thread id, thread structure address
435 and the status for each thread. The status consists of 5 letters,
436 R(run), W(wait), S(suspended), O(swapped out) and N(interruptible),
437 and if corresponding status bit is off, '.' is printed instead.
438 If 'l' option is specified, more detail information is printed for each
439 thread.
440 .XX "\fBshow task \fI[ <addr> ]\fR"
441 Display the information of a task specified by 'addr'. If 'addr' is
442 omitted, current task information is displayed.
443 .XX "\fBshow thread \fI[ <addr> ]\fR"
444 Display the information of a thread specified by 'addr'. If 'addr' is
445 omitted, current thread information is displayed.
446 .XX "\fBshow registers[/tu \fI[ <thread> ]]\fR"
447 Display the register set.
448 Target thread can be specified with 't' option and 'thread' parameter.
449 If 'u' option is specified, it displays user registers instead of
450 kernel or currently saved one.
451 .br
452 .sp
453 Warning: The support of 't' and 'u' option depends on the machine. If
454 not supported, incorrect information will be displayed.
455 .XX "\fBshow map \fI<addr>\fR"
456 Prints the vm_map at 'addr'.
457 .XX "\fBshow object \fI<addr>\fR"
458 Prints the vm_object at 'addr'.
459 .XX "\fBshow page \fI<addr>\fR"
460 Prints the vm_page structure at 'addr'.
461 .XX "\fBshow port\fR"
462 Prints the ipc_port structure at 'addr'.
463 .XX "\fBshow ipc_port[/t \fI[ <thread> ]]\fR"
464 Prints all ipc_port structure's addresses the target thread has.
465 The target thread is a current thread or that specified by a parameter.
466 .XX "\fBshow macro \fI[ <name> ]\fR"
467 Show the definitions of macros.
468 If 'name' is specified, only the definition of it is displayed.
469 Otherwise, definitions of all macros are displayed.
470 .XX "\fBshow watches\fR"
471 Displays all watchpoints.
472 .XX "\fBwatch[/T] \fI<addr>,<size> [ <task> ]\fR"
473 Set a watchpoint for a region. Execution stops
474 when an attempt to modify the region occurs.
475 The 'size' argument defaults to 4.
476 .br
477 Without 'T' option, 'addr' is assumed to be a kernel address.
478 If you want to set a watch point in user space, specify 'T'
479 and 'task' parameter where the address belongs to. If the 'task'
480 parameter is omitted, a task of the default target thread or
481 a current task is assumed.
482 If you specify a wrong space address, the request is rejected
483 with an error message.
484 .br
485 .sp
486 Warning: Attempts to watch wired kernel memory
487 may cause unrecoverable error in some systems such as i386.
488 Watchpoints on user addresses work best.
489 .br
490 .LP
491 .XE 4n
492 .LP
493 .sp
494 .B VARIABLES
495 .sp
496 The debugger accesses registers and variables as
497 .I $<name>.
498 Register names are as in the "\fBshow registers\fR"
499 command.
500 Some variables are suffixed with numbers, and may have some modifier
501 following a colon immediately after the variable name.
502 For example, register variables can have 'u' and 't' modifier to indicate
503 user register and that of a default target thread instead of that of the
504 current thread (e.g. $eax:tu).
505 .br
506 .sp
507 Built-in variables currently supported are:
508 .sp
509 .IP task\fIxx[.yy]\fR 12n
510 Task or thread structure address. 'xx' and 'yy' are task and thread
511 identification numbers printed by a "\fBshow all threads\fR"
512 command respectively. This variable is read only.
513 .IP thread 12n
514 The default target thread. The value is used when 't' option is
515 specified without explicit thread structure address parameter
516 in command lines or expression evaluation.
517 .IP radix 12n
518 Input and output radix
519 .IP maxoff 12n
520 Addresses are printed as 'symbol'+offset unless offset is greater than maxoff.
521 .IP maxwidth 12n
522 The width of the displayed line.
523 .IP lines 12n
524 The number of lines. It is used by "more" feature.
525 .IP tabstops 12n
526 Tab stop width.
527 .IP arg\fIxx\fR
528 Parameters passed to a macro.
529 .I 'xx'
530 can be 1 to 10.
531 .IP work\fIxx\fR
532 Work variable.
533 .I 'xx'
534 can be 0 to 31.
535 .LP
536 .LP
537 .sp
538 .B EXPRESSIONS
539 .sp
540 Almost all expression operators in C are supported except '~', '^',
541 and unary '&'.
542 Special rules in "\fBddb\fR"
543 are:
544 .br
545 .IP "<identifier>" 15n
546 name of a symbol. It is translated to the address(or value) of it. '.'
547 and ':' can be used in the identifier. If supported by an object format
548 dependent routine,
549 [\fI<file_name>\fR:]\fI<func>\fR[:\fI<line_number>\fR]
550 [\fI<file_name>\fR:]\fI<variable>\fR, and
551 \fI<file_name>\fR[:\fI<line_number>\fR]
552 can be accepted as a symbol.
553 The symbol may be prefixed with '\fI<symbol_table_name>\fR::'
554 like 'emulator::mach_msg_trap' to specify other than kernel symbols.
555 .IP "<number>" 15n
556 radix is determined by the first two letters:
557 0x: hex, 0o: octal, 0t: decimal, otherwise, follow current radix.
558 .IP \. 15n
559 \'dot'
560 .IP \+ 15n
561 \'next'
562 .IP \.. 15n
563 address of the start of the last line examined.
564 Unlike 'dot' or 'next', this is only changed by "examine" or
565 "write" command.
566 .IP \' 15n
567 last address explicitly specified.
568 .IP "$<variable>" 15n
569 register name or variable. It is translated to the value of it.
570 It may be followed by a ':' and modifiers as described above.
571 .IP \# 15n
572 a binary operator which rounds up the left hand side to the next
573 multiple of right hand side.
574 .IP "*<expr>" 15n
575 indirection. It may be followed by a ':' and modifiers as described above.
Cache object: 7119c58fe392b45ad7c0f0fe631c7cc7
|