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