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