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