1.\" $OpenBSD: ddb.4,v 1.27 2001/08/03 15:21:16 mpech Exp $ 2.\" $NetBSD: ddb.4,v 1.5 1994/11/30 16:22:09 jtc Exp $ 3.\" 4.\" Mach Operating System 5.\" Copyright (c) 1991,1990 Carnegie Mellon University 6.\" All Rights Reserved. 7.\" 8.\" Permission to use, copy, modify and distribute this software and its 9.\" documentation is hereby granted, provided that both the copyright 10.\" notice and this permission notice appear in all copies of the 11.\" software, derivative works or modified versions, and any portions 12.\" thereof, and that both notices appear in supporting documentation. 13.\" 14.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 15.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR 16.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 17.\" 18.\" Carnegie Mellon requests users of this software to return to 19.\" 20.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 21.\" School of Computer Science 22.\" Carnegie Mellon University 23.\" Pittsburgh PA 15213-3890 24.\" 25.\" any improvements or extensions that they make and grant Carnegie Mellon 26.\" the rights to redistribute these changes. 27.\" 28.Dd November 30, 1993 29.Dt DDB 4 30.Os 31.Sh NAME 32.Nm ddb 33.Nd kernel debugger 34.Sh DESCRIPTION 35The kernel debugger has most of the features of the old kdb, 36but with a more rational 37.Pf ( Xr gdb 1 No Ns \&-like ) 38syntax. 39.Pp 40.Nm 41prompts for commands on the console with: 42.Pp 43.Bd -literal -offset indent 44ddb> 45.Ed 46.Pp 47The general syntax of a 48.Nm 49command is: 50.Pp 51.Bd -ragged -offset indent 52.Ar command 53.Oo Ic / Ns Ar modifiers Oc " " 54.Oo Ar address Oc Ns 55.Oo Ic \&, Ns Ar count Oc 56.Ed 57.Pp 58To save typing, 59.Nm 60makes use of a context inferred from previous commands. 61In this context, 62the current location is called 63.Va dot . 64.\" The 65.\" .Va dot 66.\" is displayed with 67.\" a hexadecimal format at a prompt. 68The 69.Ic examine , 70.Ic search , 71and 72.Ic write 73commands update 74.Va dot 75to be that of the last address 76examined or the last location modified, and 77have intuitive effects on 78.Va next 79and 80.Va prev . 81All the other commands do not change 82.Va dot , 83and set 84.Va next 85to be the same. 86(See 87.Sx VARIABLES . ) 88.Pp 89.\" Specifying 90.\" .Ar address 91.\" in a command sets 92.\" .Va dot . 93An expression can be used in place of 94.Ar address 95(see 96.Sx EXPRESSIONS ) . 97Omitting 98.Ar address 99in a command uses the last value of 100.Va dot . 101A missing 102.Ar count 103is taken to be 1 for printing commands or \*(If 104for stack traces. 105Entering a blank line causes the last command to be repeated using 106.Va next 107in place of 108.Ar address , 109a 110.Ar count 111of 1, and no modifiers. 112.Pp 113.Nm 114has a feature like 115.Xr more 1 116for the output. 117If the number of lines output in response to one command exceeds the number 118set in the 119.Va \&$lines 120variable, it displays the message 121.Ql "--db_more--" 122and waits for a response. 123.Pp 124The valid responses are: 125.Pp 126.Bl -tag -width 10n -offset indent -compact 127.It <space> 128One more page. 129.It <return> 130One more line. 131.It Ic q 132Abort the current command, and return to the command input mode. 133.El 134.Pp 135The following command line editing keys are provided: 136.Pp 137.Bl -tag -width 10n -offset indent -compact 138.It Ic \&^b 139back up one character 140.It Ic \&^f 141forward up one character 142.It Ic \&^a 143beginning of line 144.It Ic \&^e 145end of line 146.It Ic \&^w 147erase word back 148.It Ic \&^h No | <del> 149erase previous character 150.It Ic \&^d 151erase next character 152.It Ic \&^k 153delete to end of line 154.It Ic \&^u 155delete line 156.It Ic \&^p 157previous in command history 158.It Ic \&^n 159next in command history 160.It Ic \&^r 161redraw line 162.El 163.\" .Pp 164.\" During command execution, 165.\" .Nm ddb 166.\" is sensitive only to the following keystrokes: 167.\" .Bl -tag -width 10n -compact -offset indent 168.\" .It Ic \&^s 169.\" pause 170.\" .It Ic \&^q 171.\" unpause 172.\" .It Ic \&^c 173.\" abort command (even if paused) 174.\" .El 175.Pp 176.Nm 177is only available if the kernel was configured with the DDB option. 178.Nm 179will be invoked upon a kernel panic when the 180.Xr sysctl 8 181name 182.Va ddb.panic 183is set to 1. 184.Nm 185may be invoked from the console by the key sequence 186.Li Ctl-Alt-Esc 187when the 188.Xr sysctl 8 189name 190.Va ddb.console 191is set to 1. 192.Sh COMMANDS 193The following commands may be typed at the 194.Ql ddb> 195prompt. 196Some commands consist of more than one word, and if only the first word 197or words are entered, the possible alternatives to complete the command 198are displayed and no other action is performed. 199.Bl -tag -width 10n 200.\" -------------------- 201.It Ic help 202List the available commands. 203.\" -------------------- 204.It Xo 205.Oo Ic e Oc Ns 206.Ic x Ns Oo Ic amine Oc 207.Op Cm /bhlaAxzodurcsmiI 208.Op Ar addr Ns 209.Op Ic \&, Ns Ar count 210.Xc 211Display the contents at address 212.Ar addr 213according to the formats in the modifier. 214Multiple modifier formats display multiple locations. 215If no format is specified, the last formats specified for this command 216is used. 217.Pp 218The format characters are: 219.Pp 220.Bl -tag -width 4n -compact 221.It Cm /b 222look at by bytes (8 bits) 223.It Cm /h 224look at by half words (16 bits) 225.It Cm /l 226look at by long words (32 bits) (default) 227.It Cm /a 228print the location being displayed 229.It Cm /A 230print the location with a line number if possible 231.It Cm /x 232display in unsigned hex 233.It Cm /z 234display in signed hex 235.It Cm /o 236display in unsigned octal 237.It Cm /d 238display in signed decimal 239.It Cm /u 240display in unsigned decimal 241.It Cm /r 242display in current radix, signed 243.It Cm /c 244display low 8 bits as a character. 245Non-printing characters are displayed as an octal escape code (e.g., '\\000'). 246.It Cm /s 247display the null-terminated string at the location. 248Non-printing characters are displayed as octal escapes. 249.It Cm /m 250display in unsigned hex with character dump at the end of each line. 251The location is also displayed in hex at the beginning of each line. 252.It Cm /i 253display as an instruction 254.It Cm /I 255display as an alternate format instruction depending on the 256machine: 257.Pp 258.Bl -tag -width powerpc_ -compact 259.It vax 260Don't assume that each external label is a procedure entry mask. 261.It i386 262Don't round to the next long word boundary. 263.It mips 264Print register contents. 265.El 266.El 267.Pp 268The value of 269.Va next 270is set to the 271.Ar addr 272plus the size of the data examined. 273.\" -------------------- 274.It Ic xf 275Examine forward. 276Execute an 277.Ic examine 278command with the last specified parameters to it 279except that the next address displayed by it is used as the start address. 280.\" -------------------- 281.It Ic xb 282Examine backward. 283Executes an 284.Ic examine 285command with the last specified parameters to it 286except that the last start address subtracted by the size displayed by it 287is used as the start address. 288.\" -------------------- 289.It Xo 290.Ic print 291.Op Cm /axzodurc 292.Op Ar addr Op addr ... 293.Xc 294Print each 295.Ar addr 296according to the modifier character. 297The valid modifiers are a subset of those from the 298.Ic examine 299command, and act as described there. 300If no modifier is specified, the last one specified in a 301previous use of 302.Ic print 303is used. 304The 305.Ar addr 306argument 307can be a string, and it is printed as a literal. 308.Pp 309For example, 310.Bd -literal -offset indent 311print/x "eax = " $eax "\enecx = " $ecx "\en" 312.Ed 313.Pp 314will print something like this: 315.Bd -literal -offset indent 316eax = xxxxxx 317ecx = yyyyyy 318.Ed 319.\" -------------------- 320.\" .It Xo Ic w Ns Op Cm /bhl 321.\" .Op Ar addr 322.\" .Ar expr Op expr ... 323.\" .Xc 324.It Xo 325.Ic w Ns Oo Ic rite Oc 326.Op Cm /bhl 327.Op Ar addr 328.Ar expr Op expr ... 329.Xc 330Write the value of each 331.Ar expr 332expression at succeeding locations start at 333.Ar addr . 334The write unit size can be specified using one of the modifiers: 335.Pp 336.Bl -tag -width 4n -offset indent -compact 337.It Cm /b 338byte (8 bits) 339.It Cm /h 340half word (16 bits) 341.It Cm /l 342long word (32 bits) (default) 343.El 344.Pp 345The value of 346.Va next 347is set to 348.Ar addr 349plus the size of values written. 350.Pp 351.Sy Warning: 352since there is no delimiter between expressions, the 353command may not parse as you expect. 354It is best to enclose each expression in parentheses. 355.\" -------------------- 356.It Xo Ic set 357.Ic \&$ Ns Ar name 358.Op Ic \&= 359.Ar expr 360.Xc 361Set the named variable or register with the value of 362.Ar expr . 363Valid variable names are described below. 364.It Ic boot Ar how 365Reboot the machine depending on 366.Ar how : 367.Bl -tag -width "boot crashx" -compact -indent offset 368.It Ic boot sync 369Sync disks and reboot. 370.It Ic boot crash 371Dump core and reboot. 372.It Ic boot dump 373Sync disks, dump core and reboot. 374.It Ic boot halt 375Just halt. 376.El 377.\" -------------------- 378.It Xo 379.Ic break 380.Op Cm /u 381.Op Ar addr Ns 382.Op Ic \&, Ns Ar count 383.Xc 384Set a break point at 385.Ar addr . 386If 387.Ar count 388is supplied, 389.Nm 390allows the breakpoint to be silently hit 391.Ar ( count No \&- 1 ) 392times before stopping at the 393break point. 394.Pp 395If the break point is successfully set, a break point number is 396displayed, in the form 397.Ic # Ns Ar number . 398This can later be used in deleting the break point 399or for adding conditions to it. 400.Pp 401When the 402.Cm /u 403modifier is specified, 404.Ar addr 405is taken as a user space address. 406Without it, the address is considered in the kernel space. 407Wrong space addresses are rejected with an error message. 408The 409.Cm /u 410modifier can be used only if it is supported by machine dependent 411routines. 412.Pp 413.Sy Warning: 414if a user text is shadowed by a normal user space debugger, 415user space break points may not work correctly. 416Setting a breakpoint at the low-level code paths may also cause strange 417behavior. 418.\" -------------------- 419.\" .It Xo Ic d 420.\" .Op Ar addr | Ic # Ns Ar number 421.\" .Xc 422.It Xo 423.Ic d Ns Oo Ic elete Oc 424.Op Ar addr | Ic # Ns Ar number 425.Xc 426Delete the break point set with the 427.Ic break 428command. 429.\" -------------------- 430.\" .It Xo Ic s Ns Op Cm /p 431.\" .Op Ic \&, Ns Ar count 432.\" .Xc 433.It Xo 434.Ic s Ns Oo Ic tep Oc 435.Op Cm /p 436.Op Ic \&, Ns Ar count 437.Xc 438Single step 439.Ar count 440times. 441If the 442.Cm /p 443modifier is specified, print each instruction at each step. 444Otherwise, only print the last instruction. 445.Pp 446.Sy Warning: 447depending on machine type, it may not be possible to 448single-step through some low-level code paths or user space code. 449On machines with software-emulated single-stepping (e.g., pmax), 450stepping through code executed by interrupt handlers will probably 451do the wrong thing. 452.\" -------------------- 453.It Ic call Ar name Ns Xo 454.Ic \&( Ns Ar expr 455.Op Ic \&, Ar expr ... 456.Ic \&) 457.Xc 458Call the function named by 459.Ar name 460with the argument(s) listed in parentheses. 461Parentheses may be omitted if the function takes no arguments. 462The number of arguments is currently limited to 10. 463.\" -------------------- 464.\" .It Ic c Ns Op Cm /c 465.It Xo 466.Ic c Ns Oo Ic ontinue Oc 467.Op Cm /c 468.Xc 469Continue execution until a breakpoint or watchpoint. 470If the 471.Cm /c 472modifier is given, instructions are counted while executing. 473Some machines (e.g., pmax) also count loads and stores. 474.Pp 475.Sy Warning: 476when counting with 477.Cm /c , 478.Nm 479is really silently single-stepping. 480This means that single-stepping on low-level code may cause strange 481behavior. 482.\" -------------------- 483.It Xo 484.Ic watch 485.Ar addr 486.Op Ic \&, Ns Ar size 487.Xc 488Set a watchpoint for the region starting at 489.Ar addr . 490Execution stops and control returns to 491.Nm 492when an attempt is made to modify a watched region. 493The 494.Ar size 495argument defaults to 4. 496.Pp 497If you specify a wrong space address, the request is rejected 498with an error message. 499.Pp 500.Sy Warning: 501attempts to watch wired kernel memory 502may cause unrecoverable error on some systems (e.g., i386). 503Watchpoints on user addresses work best. 504.\" -------------------- 505.It Ic dwatch Ar addr 506Delete the watchpoint at address 507.Ar addr 508that was previously set with 509.Ic watch 510command. 511.\" -------------------- 512.It Xo 513.Ic hangman 514.Op Cm /s Ns Op Ic 0-9 515.Xc 516This is tiny and handy tool for random kernel hangs analysis, of which its 517depth is controlled by the optional argument of the default value of five. 518It uses some sophisticated heuristics to spot the global symbol that 519caused the hang. 520Since the discovering algorithm is a probabilistic one 521you may spend substantial time to figure the exact symbol name. 522This smart thing requires a little of your attention, the input it accepts 523is mostly of the same format as that of the famous 524.Xr hangman 6 525game, to which it, apparently, is obliged by the name. 526Hint: the 527.Xr nm 1 528utility might help. 529.\" -------------------- 530.It Xo 531.Ic until 532.Op Cm /p 533.Xc 534Stop at the next 535.Qq call 536or 537.Qq return 538instruction. 539If 540.Cm /p 541modifier is specified, 542.Nm 543prints the call nesting depth and the 544cumulative instruction count at each call or return. 545Otherwise, it stays silent until the matching return is hit. 546.\" -------------------- 547.It Ic match Op Cm /p 548Stop at the next matching return instruction. 549If the 550.Cm /p 551modifier is specified, 552.Nm 553prints the call nesting depth and the 554cumulative instruction count at each call or return. 555Otherwise, it remains mostly quiet. 556.\" -------------------- 557.It Ic next Op Cm /p 558The 559.Ic next 560command is a synonym for 561.Ic match . 562.\" -------------------- 563.It Xo 564.Ic trace 565.Op Cm /u 566.Op Ar frameaddr Ns 567.Op Ic \&, Ns Ar count 568.Xc 569Show the stack trace. 570The 571.Cm /u 572modifier shows the stack trace of user space; 573If omitted, the kernel stack is traced instead. 574The 575.Ar count 576argument is the limit on the number of frames to be followed. 577If 578.Ar count 579is omitted, all frames are printed. 580.Pp 581.Sy Warning: 582user space stack trace is valid 583only if the machine dependent code supports it. 584.\" -------------------- 585.It Xo 586.Ic search 587.Op Cm /bhl 588.Op Ar addr 589.Ar value 590.Op Ar mask 591.Op Ic \&, Ns Ar count 592.Xc 593Search memory for a value beginning at 594.Ar addr . 595This command might fail in interesting 596ways if it doesn't find the searched-for value. 597This is because 598.Nm 599doesn't always recover from touching bad memory. 600The optional 601.Ar count 602argument limits the search. 603The modifiers are the same as those of the 604.Ic write 605command. 606.Pp 607The 608.Va next 609address is set to the address where 610.Ar value 611is found, or just after where the search area finishes. 612.\" -------------------- 613.It Ic show Ar what 614Displays various things, depending on 615.Ar what : 616.Bl -tag -width 4n 617.\" -------------------- 618.It Ic show breaks 619Prints a list of all breakpoints that have been set with the 620.Ic break 621command. 622.\" -------------------- 623.It Ic show extents 624Prints a detailed list of all extents. 625.\" -------------------- 626.It Xo 627.Ic show map 628.Op Cm /f 629.Ar addr 630.Xc 631Prints the 632.Li vm_map 633at 634.Ar addr . 635If the 636.Cm /f 637modifier is specified the complete map is printed. 638.\" -------------------- 639.It Xo 640.Ic show malloc 641.Op Ar addr 642.Xc 643Prints malloc debugging information if available. 644If an optional address is specified, only information about that address 645is printed. 646.\" -------------------- 647.It Xo 648.Ic show object 649.Op Cm /f 650.Ar addr 651.Xc 652Prints the 653.Li vm_object 654at 655.Ar addr . 656If the 657.Cm /f 658modifier is specified the complete object is printed. 659.\" -------------------- 660.It Xo 661.Ic show registers 662.Op Cm /u 663.Xc 664Display the register set. 665If the 666.Cm /u 667modifier is specified, it displays user registers (or the currently 668saved registers) instead of the kernel's. 669Note: The 670.Cm /u 671modifier is not supported on every machine, in which case 672incorrect information may be displayed. 673.\" -------------------- 674.It Ic show watches 675Displays all watchpoints set with the 676.Ic watch 677command. 678.\" -------------------- 679.It Xo 680.Ic show all procs 681.Op Cm /anw 682.Xc 683Display information on all processes. 684.Pp 685.Bl -tag -width foo -compact 686.It Cm /n 687(Default) Show process information in a 688.Xr ps 1 No Ns \&-like 689format. 690Information printed includes process ID, parent 691process ID, process group, UID, process status, process flags, process 692command name, and process wait channel message. 693.It Cm /a 694Shows the kernel virtual addresses of each process' 695proc structure, u-area, and vmspace structure. 696The vmspace address is also the address of the process' 697.Li vm_map 698structure 699and can be used in the 700.Ic show map 701command. 702.It Cm /w 703Shows each process' PID, command, system call emulation, 704wait channel address, and wait channel message. 705.El 706.\" -------------------- 707.It Ic show all callout 708Display the contents of the callout table. 709.El 710.It Ic callout 711A synonym for the 712.Ic show all callout 713command. 714.\" -------------------- 715.It Xo 716.Ic ps 717.Op Cm /anw 718.Xc 719A synonym for 720.Ic show all procs . 721.\" -------------------- 722.El 723.Sh VARIABLES 724.Nm 725denotes registers and variables by 726.Ic $ Ns Va name . 727Register names can be found with the 728.Ic show registers 729command. 730.Pp 731Some variables names are suffixed with numbers, and some may have a modifier 732following a colon immediately after the variable name. 733For example, register variables can have the 734.Ql :u 735modifier to indicate a 736user register (e.g., 737.Ql \&$eax:u ) . 738.Pp 739Built-in debugger variables currently supported are: 740.Bl -tag -width 10n -compact -offset indent 741.It Va \&$radix 742Input and output radix 743.It Va \&$maxoff 744Addresses are printed as 745.Ar symbol Ns Li + Ns Ar offset 746unless 747.Ar offset 748is greater than 749.Va \&$maxoff. 750.It Va \&$maxwidth 751The width of the displayed lines. 752.It Va \&$lines 753The number of lines to page. 754This is used by the 755.Dq more 756feature. 757.It Va \&$tabstops 758Tab stop width. 759.It Va \&$work Ns Ar xx 760Work variables. 761The suffix 762.Ar xx 763is a number from 0 to 31. 764.El 765.Sh EXPRESSIONS 766Almost all expression operators in C are supported except for 767.Ql \&~ , 768.Ql \&^ , 769and unary 770.Ql \&& . 771Special rules for expressions in 772.Nm 773are: 774.Bl -tag -width 15n -compact -offset indent 775.It Ar identifier 776The name of a symbol. 777It is translated to the address (or value) of the symbol. 778.Ql \&. 779and 780.Ql \&: 781can be used in the identifier. 782The following can be accepted as an identifier, 783if supported by an object format dependent routine: 784.Bl -item -offset indent -compact 785.It 786.Sm off 787.Oo Ar filename Li \&: Oc Ar func 788.Oo \&: Ar linenumber Oc 789.It 790.Op Ar filename \&: 791.Ar variable 792.It 793.Ar filename 794.Op \&: Ar linenumber 795.Sm on 796.El 797The symbol may be prefixed with 798.Ql Ar symboltablename Ns \&:: 799(e.g., 800.Ql emulator::mach_msg_trap ) 801to specify other than kernel symbols. 802.It Ar number 803The radix is determined by the first two letters: 804.Ql 0x : 805hex, 806.Ql 0o : 807octal, 808.Ql 0t : 809decimal, otherwise, the value of 810.Va \&$radix 811is used. 812.It Li \&. 813.Va dot : 814the current address. 815.It Li \&+ 816.Va next : 817the next address. 818.It Li \.. 819The address of the start of the last line examined. 820Unlike 821.Va dot 822or 823.Va next , 824this is only changed by the 825.Ic examine 826or 827.Ic write 828command. 829.It Li \&' 830The last address explicitly specified. 831.It Li \&$ Ns Ar variable 832The value of a register or variable. 833The name may be followed by a 834.Ql \&: 835and modifiers as described above with 836.Ar identifier . 837.It Ar expr Li \&# Ar expr 838A binary operator which rounds up the left hand side to the next 839multiple of right hand side. 840.It Li \&* Ns Ar expr 841Indirection. 842It may be followed by a ':' and modifiers as described above. 843.El 844.Sh SEE ALSO 845.Xr gdb 1 , 846.Xr nm 1 , 847.Xr sysctl.conf 5 , 848.Xr hangman 6 , 849.Xr sysctl 8 , 850.Xr extent 9 851.Sh HISTORY 852This kernel facility first appeared in MACH 2 operating system 853developed by CMU. 854Hangman (which stands for "hangs maniacal analyzer") first appeared in 855.Ox 1.2 . 856