share/man/man4/ddb.4

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