1.\" $NetBSD: ddb.4,v 1.16 1997/11/23 18:37:33 chopps Exp $ 2.\" 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" --- 38.\" This manual page was derived from a -man.old document which bore 39.\" the following copyright message: 40.\" --- 41.\" 42.\" Mach Operating System 43.\" Copyright (c) 1991,1990 Carnegie Mellon University 44.\" All Rights Reserved. 45.\" 46.\" Permission to use, copy, modify and distribute this software and its 47.\" documentation is hereby granted, provided that both the copyright 48.\" notice and this permission notice appear in all copies of the 49.\" software, derivative works or modified versions, and any portions 50.\" thereof, and that both notices appear in supporting documentation. 51.\" 52.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 53.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR 54.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 55.\" 56.\" Carnegie Mellon requests users of this software to return to 57.\" 58.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 59.\" School of Computer Science 60.\" Carnegie Mellon University 61.\" Pittsburgh PA 15213-3890 62.\" 63.\" any improvements or extensions that they make and grant Carnegie Mellon 64.\" the rights to redistribute these changes. 65.\" 66.Dd November 17, 1997 67.Dt DDB 4 68.Os NetBSD 69.Sh NAME 70.Nm ddb 71.Nd in-kernel debugger 72.Sh SYNOPSIS 73.Cd options DDB 74.Pp 75To enable history editing: 76.Cd options DDB_HISTORY_SIZE=integer 77.Pp 78To disable entering 79.Nm 80upon kernel panic: 81.Cd options DDB_ONPANIC=0 82.Sh DESCRIPTION 83.Nm 84is the in-kernel debugger. 85It may be entered at any time via a special key sequence, and 86optionally may be invoked when the kernel panics. 87.Pp 88The current memory location being edited is referred to as 89.Ar dot , 90and the next location is 91.Ar next . 92They are displayed as hexadecimal numbers. 93.Pp 94Commands that examine and/or modify memory update 95.Ar dot 96to the address of the last line examined or the last location 97modified, and set 98.Ar next 99to the next location to be examined or modified. 100Other commands don't change 101.Ar dot , 102and set 103.Ar next 104to be the same as 105.Ar dot . 106.Pp 107The general command syntax is: 108.Bd -ragged -offset indent 109.Ic command Ns Op Cm / Ns Ar modifier 110.Ar address 111.Op Cm , Ns Ar count 112.Ed 113.Pp 114A blank line repeats the previous command from the address 115.Ar next 116with a 117.Cm count 118of 1 and no modifiers. 119Specifying 120.Cm address 121sets 122.Em dot 123to the address. 124If 125.Cm address 126is omitted, 127.Em dot 128is used. 129A missing 130.Cm count 131is taken to be 1 for printing commands, and infinity for stack traces. 132.Pp 133.Nm 134has a 135.Xr more 1 -like 136functionality; if a number of lines in a command's output exceeds the number 137defined in the 138.Va lines 139variable, then 140.Nm 141displays 142.Dq "--db more--" 143and waits for a response, which may be one of: 144.Bl -tag -offset indent -width "<return>" 145.It <return> 146one more line. 147.It <space> 148one more page. 149.It Ic q 150abort the current command, and return to the command input mode. 151.El 152.Pp 153If 154.Nm 155history editing is enabled (by defining the 156.D1 Cd options DDB_HISTORY_SIZE=num 157kernel option), then a history of the last 158.Cm num 159commands is kept. 160The history can be manipulated with the following key sequences: 161.Bl -tag -offset indent -width "<Ctrl>-P" 162.It <Ctrl>-P 163retrieve previous command in history (if any). 164.It <Ctrl>-N 165retrieve next command in history (if any). 166.El 167.Sh COMMANDS 168.Nm 169supports the following commands: 170.Bl -tag -width 5n 171.It Xo 172.Ic examine Ns Op Cm / Ns Ar modifier 173.Ar address Ns Op Cm , Ns Ar count 174.Xc 175Display the address locations according to the format in 176.Ar modifier . 177Multiple modifier formats display multiple locations. 178If 179.Ar modifier 180isn't specified, the modifier from the last use of 181.Ic examine 182is used. 183.Pp 184The valid format characters for 185.Ar modifier 186are: 187.Bl -tag -offset indent -width 2n 188.It Cm b 189examine bytes (8 bits). 190.It Cm h 191examine half-words (16 bits). 192.It Cm l 193examine long-words (32 bits). 194.It Cm a 195print the location being examined. 196.It Cm A 197print the location with a line number if possible. 198.It Cm x 199display in unsigned hex. 200.It Cm z 201display in signed hex. 202.It Cm o 203display in unsigned octal. 204.It Cm d 205display in signed decimal. 206.It Cm u 207display in unsigned decimal. 208.It Cm r 209display in current radix, signed. 210.It Cm c 211display low 8 bits as a character. 212Non-printing characters as displayed as an octal escape code 213(e.g., 214.Sq \e000 ) . 215.It Cm s 216display the NUL terminated string at the location. 217Non-printing characters are displayed as octal escapes. 218.It Cm m 219display in unsigned hex with a character dump at the end of each line. 220The location is displayed as hex at the beginning of each line. 221.It Cm i 222display as a machine instruction. 223.It Cm I 224display as a machine instruction, with possible alternative formats 225depending upon the machine: 226.Bl -tag -offset indent -width "sparc" 227.It i386 228don't round to the next long word boundary 229.It mips 230print register contents 231.It vax 232don't assume that each external label is a procedure entry mask 233.El 234.El 235.It Xo 236.Ic x Ns Op Cm / Ns Ar modifier 237.Ar address Ns Op Cm , Ns Ar count 238.Xc 239A synonym for 240.Ic examine . 241.It Ic xf 242Examine forward. 243.Ic xf 244re-executes the most recent 245.Ic execute 246command with the same parameters except that 247.Ar address 248is set to 249.Ar next . 250.It Ic xb 251Examine backward. 252.Ic xb 253re-executes the most recent 254.Ic execute 255command with the same parameters, except that 256.Ar address 257is set to the last start address minus its size. 258.It Xo 259.Ic print Ns Op Cm /axzodurc 260.Ar address Op Ar address ... 261.Xc 262Print addresses 263.Ar address 264according to the modifier character, as per 265.Ic examine . 266Valid modifiers are: 267.Cm /a , 268.Cm /x , 269.Cm /z , 270.Cm /o , 271.Cm /d , 272.Cm /u , 273.Cm /r , 274and 275.Cm /c 276(as per 277.Ic examine ) . 278If no modifier is specified, the most recent one specified is used. 279.Ar address 280may be a string, and is printed 281.Dq as-is . 282For example: 283.Bd -literal -offset indent 284print/x "eax = " $eax "\enecx = " $ecx "\en" 285.Ed 286.Pp 287will produce: 288.Bd -literal -offset indent 289eax = xxxxxx 290ecx = yyyyyy 291.Ed 292.It Xo 293.Ic write Ns Op Cm /bhl 294.Ar address 295.Ar expression Op Ar expression ... 296.Xc 297Write the 298.Ar expression Ns s 299at succeeding locations. 300The unit size is specified with a modifier character, as per 301.Ic examine . 302Valid modifiers are: 303.Cm /b , 304.Cm /h , 305and 306.Cm /l . 307If no modifier is specified, 308.Cm /l 309is used. 310.Pp 311Warning: since there is no delimiter between 312.Ar expression Ns s , 313strange things may occur. 314It's best to enclose each 315.Ar expression 316in parentheses. 317.It Xo 318.Ic set 319.Cm $ Ns Ar variable 320.Op Cm = 321.Ar expression 322.Xc 323Set the named variable or register to the value of 324.Ar expression . 325Valid variable names are described in 326.Sx VARIABLES . 327.It Xo 328.Cm break Ns Op Cm /u 329.Ar address Ns Op Cm , Ns Ar count 330.Xc 331Set a breakpoint at 332.Ar address . 333If 334.Ar count 335is supplied, continues 336.Pq Ar count Ns -1 337times before stopping at the breakpoint. 338If the breakpoint is set, a breakpoint number is printed with 339.Sq # . 340This number can be used to 341.Ic delete 342the breakpoint, or to add 343conditions to it. 344.Pp 345If 346.Cm /u 347is specified, 348set a breakpoint at a user-space address. 349Without 350.Cm /u , 351.Ar address 352is considered to be in the kernel-space, and an address in the wrong 353space will be rejected, and an error message will be emitted. 354This modifier may only be used if it is supported by machine dependent 355routines. 356.Pp 357Warning: if a user text is shadowed by a normal user-space debugger, 358user-space breakpoints may not work correctly. 359Setting a breakpoint at the low-level code paths may also cause 360strange behavior. 361.It Xo 362.Ic delete 363.Ar "address" | 364.Cm # Ns Ar number 365.Xc 366Delete a breakpoint. 367The target breakpoint may be specified by 368.Ar address , 369as per 370.Ic break , 371or by the breakpoint number returned by 372.Ic break 373if it's prefixed with 374.Sq Cm # . 375.It Xo 376.Ic step Ns Op Cm /p 377.Op Cm , Ns Ar count 378.Xc 379Single-step 380.Ar count 381times. 382If 383.Cm /p 384is specified, print each instruction at each step. 385Otherwise, only print the last instruction. 386.Pp 387Warning: depending on the machine type, it may not be possible 388to single-step through some low-level code paths or user-space 389code. 390On machines with software-emulated single-stepping (e.g., pmax), 391stepping through code executed by interrupt handlers will probably 392do the wrong thing. 393.It Ic continue Ns Op Cm /c 394Continue execution until a breakpoint or watchpoint. 395If 396.Cm /c 397is specified, count instructions while executing. 398Some machines (e.g., pmax) also count loads and stores. 399.Pp 400Warning: when counting, the debugger is really silently 401single-stepping. 402This means that single-stepping on low-level may cause strange 403behavior. 404.It Ic until Ns Op Cm /p 405Stop at the next call or return instruction. 406If 407.Cm /p 408is specified, print the call nesting depth and the 409cumulative instruction count at each call or return. 410Otherwise, only print when the matching return is hit. 411.It Ic next Ns Op Cm /p 412Stop at the matching return instruction. 413If 414.Cm /p 415is specified, print the call nesting depth and the 416cumulative instruction count at each call or return. 417Otherwise, only print when the matching return is hit. 418.It Ic match Ns Op Cm /p 419A synonym for 420.Ic next . 421.It Xo 422.Cm trace Ns Op Cm /u 423.Sm off 424.Op Ar frame-address 425.Op Cm , Ar count 426.Sm on 427.Xc 428Stack trace from 429.Ar frame-address . 430If 431.Cm /u 432is specified, trace user-space, otherwise trace kernel-space. 433.Ar count 434is the number of frames to be traced. 435If 436.Ar count 437is omitted, all frames are printed. 438.Pp 439Warning: user-space stack trace is valid only if the machine dependent 440code supports it. 441.It Xo 442.Cm trace/t 443.Sm off 444.Op Ar pid 445.Op Cm , Ar count 446.Sm on 447.Xc 448Stack trace by 449.Dq thread 450(process, on NetBSD) rather than by stack frame address. 451Note that 452.Ar pid 453is interpreted using the current radix, whilst 454.Ic ps 455displays pids in decimal; prefix 456.Ar pid 457with 458.Sq 0t 459to force it to be interpreted as decimal. 460.Pp 461Warning: trace by pid is valid only if the machine dependent code 462supports it. 463.It Xo 464.Ic search Ns Op Cm /bhl 465.Ar address 466.Ar value 467.Op Ar mask 468.Op Cm , Ns Ar count 469.Xc 470Search memory from 471.Ar address 472for 473.Ar value . 474The unit size is specified with a modifier character, as per 475.Ic examine . 476Valid modifiers are: 477.Cm /b , 478.Cm /h , 479and 480.Cm /l . 481If no modifier is specified, 482.Cm /l 483is used. 484.Pp 485This command might fail in interesting ways if it doesn't find 486.Ar value . 487This is because 488.Nm 489doesn't always recover from touching bad memory. 490The optional 491.Ar count 492limits the search. 493.It Ic reboot Op Ar flags 494Reboot, using the optionally supplied boot 495.Ar flags . 496.Pp 497Note: Limitations of the command line interface preclude 498specification of a boot string. 499.It Xo 500.Sm off 501.Ic "show\ all\ procs" 502.Op Cm /a 503.Op Cm /n 504.Op Cm /w 505.Sm on 506.Xc 507Display all process information. 508Valid modifiers: 509.Bl -tag -width 3n 510.It Cm /n 511show process information in a 512.Xr ps 1 513style format (this is the default). 514Information printed includes: process ID, parent process ID, 515process group, UID, process status, process flags, process 516command name, and process wait channel message. 517.It Cm /a 518show the kernel virtual addresses of each process' 519proc structure, u-are, and vmspace structure. 520The vmspace address is also the address of the process' 521vm_map structure, and can be used in the 522.Ic "show map" 523command. 524.It Cm /w 525show each process' PID, command, system call emulation, wait channel 526address, and wait channel message. 527.El 528.It Xo 529.Sm off 530.Ic ps 531.Op Cm /a 532.Op Cm /n 533.Op Cm /w 534.Sm on 535.Xc 536A synonym for 537.Ic "show all procs" . 538.It Ic "show registers" Ns Op Cm /u 539Display the register set. 540If 541.Cm /u 542is specified, display user registers instead of kernel registers 543or the currently save one. 544.Pp 545Warning: support for 546.Cm /u 547is machine dependent. 548If not supported, incorrect information will be displayed. 549.It Xo 550.Ic "show map" Ns Op Cm /f 551.Ar address 552.Xc 553Print the vm_map at 554.Ar address . 555If 556.Cm /f 557is specified the complete map is printed. 558.It Xo 559.Ic "show object" Ns Op Cm /f 560.Ar address 561.Xc 562Print the vm_object at 563.Ar address . 564If 565.Cm /f 566is specified the complete object is printed. 567.It Ic "show watches" 568Display all watchpoints. 569.It Xo 570.Ic watch 571.Sm off 572.Ar address 573.Op Cm , Ar size 574.Sm on 575.Xc 576Set a watchpoint for a region. 577Execution stops when an attempt to modify the region occurs. 578.Ar size 579defaults to 4. 580.Pp 581If you specify a wrong space address, the request is 582rejected with an error message. 583.Pp 584Warning: attempts to watch wired kernel memory may cause 585an unrecoverable error in some systems such as i386. 586Watchpoints on user addresses work the best. 587.El 588.Sh VARIABLES 589.Nm 590accesses registers and variables as 591.Cm $ Ns Ar name . 592Register names are as per the 593.Ic "show registers" 594command. 595Some variables are suffixed with numbers, and may have a modifier 596following a colon immediately after the variable name. 597For example, register variables may have a 598.Sq u 599modifier to indicate user register 600(e.g., 601.Li "$eax:u" ) . 602.Pp 603Built-in variables currently supported are: 604.Bl -tag -offset indent -width "maxwidth" 605.It Va lines 606The number of lines. 607This is used by the 608.Ic more 609feature. 610.It Va maxoff 611Addresses are printed as 612.Li 'symbol'+offset 613unless 614.Li offset 615is greater than 616.Va maxoff . 617.It Va maxwidth 618The width of the displayed line. 619.It Va onpanic 620If non-zero (the default), 621.Nm 622will be invoked when the kernel panics. 623If the kernel configuration option 624.D1 Cd options DDB_ONPANIC=0 625is used, 626.Va onpanic 627will be initialised to off. 628.It Va radix 629Input and output radix. 630.It Va tabstops 631Tab stop width. 632.It Va work Ns Sy xx 633Temporary work variable. 634.Sq Sy xx 635is between 0 and 31. 636.El 637.Pp 638All built-in variables are accessible via 639.Xr sysctl 3 . 640.Sh EXPRESSIONS 641Almost all expression operators in C are supported, except 642.Sq ~ , 643.Sq ^ , 644and unary 645.Sq & . 646Special rules in 647.Nm 648are: 649.Bl -tag -offset indent -width "identifier" 650.It Ar identifier 651name of a symbol. 652It is translated to the address (or value) of it. 653.Sq . 654and 655.Sq : 656can be used in the identifier. 657If supported by an object format dependent routine, 658.Sm off 659.Xo 660.Oo Ar filename : Oc 661.Ar function 662.Oo : Ar "line number" Oc , 663.Xc 664.Xo 665.Oo Ar filename : Oc 666.Ar variable , 667.Xc 668and 669.Xo 670.Ar filename 671.Oo : Ar "line number" Oc , 672.Xc 673.Sm on 674can be accepted as a symbol. 675The symbol may be prefixed with 676.Ar "symbol_table_name" Ns :: 677(e.g., 678.Li emulator::mach_msg_trap ) 679to specify other than kernel symbols. 680.It Ar number 681number. 682Radix is determined by the first two characters: 683.Sq 0x 684- hex, 685.Sq 0o 686- octal, 687.Sq 0t 688- decimal, 689otherwise follow current radix. 690.It Cm . 691.Ar dot 692.It Cm + 693.Ar next 694.It Cm .. 695address of the start of the last line examined. 696Unlike 697.Ar dot 698or 699.Ar next , 700this is only changed by the 701.Ic examine 702or 703.Ic write 704commands. 705.It Cm , 706last address explicitly specified. 707.It Cm $ Ns Ar name 708register name or variable. 709It is translated to the value of it. 710It may be followed by a 711.Sq : 712and modifiers as described above. 713.It Cm a 714multiple of right-hand side. 715.It Cm * Ns Ar expr 716expression indirection. 717It may be followed by a 718.Sq : 719and modifiers as described above. 720.El 721.Sh ENTERING THE DEBUGGER 722Unless 723.Va onpanic 724is set to 0, 725.Nm 726will be activated whenever the kernel would otherwise panic. 727.Pp 728.Nm 729may also be activated from the console. 730In general, sending a break on a serial console will activate 731.Nm "" . 732There are also key sequences for each port that will activate 733.Nm 734from the keyboard: 735.Bl -tag -offset indent -width "mac68k" 736.It amiga 737<LAlt>-<LAmiga>-<F10> 738.It hp300 739<Shift>-<Reset> 740.It i386 741<Ctrl>-<Alt>-<Esc> 742.It mac68k 743<Command>-<Power>, or the Interrupt switch. 744.It sparc 745<L1>-A, or <Stop>-A 746.El 747.Pp 748In addition, 749.Nm 750may be explicitly activated by the debugging code in the kernel 751if 752.Cm DDB 753is configured. 754.Sh SEE ALSO 755.Xr options 4 , 756.Xr sysctl 8 757