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