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