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