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