1.\" $NetBSD: ddb.4,v 1.112 2008/03/26 13:03:51 chris Exp $ 2.\" 3.\" Copyright (c) 1997 - 2007 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 February 18, 2008 67.Dt DDB 4 68.Os 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.\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS 80.Ic ddb 81upon kernel panic: 82.Cd options DDB_ONPANIC=0 83.Pp 84To enable teeing all 85.\" XXX: hack; .Nm automatically introduces newline in SYNOPSIS 86.Ic ddb 87output to the kernel msgbuf: 88.Cd options DDB_TEE_MSGBUF=1 89.Pp 90To specify commands which will be executed on each entry to 91.Ic ddb : 92.Cd options DDB_COMMANDONENTER="trace;show registers" 93In this case, "trace" and then "show registers" will be executed automatically. 94.Pp 95To enable extended online help: 96.Cd options DDB_VERBOSE_HELP . 97.Sh DESCRIPTION 98.Nm 99is the in-kernel debugger. 100It may be entered at any time via a special key sequence, and 101optionally may be invoked when the kernel panics. 102.Sh ENTERING THE DEBUGGER 103Unless 104.Dv DDB_ONPANIC 105is set to 0, 106.Nm 107will be activated whenever the kernel would otherwise panic. 108.Pp 109.Nm 110may also be activated from the console. 111In general, sending a break on a serial console will activate 112.Nm . 113There are also key sequences for each port that will activate 114.Nm 115from the keyboard: 116.Bl -tag -offset indent -width "mvme68k" -compact 117.It alpha 118\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] on PC style keyboards. 119.It amd64 120\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 121.br 122\*[Lt]Break\*[Gt] on serial console. 123.It amiga 124\*[Lt]LAlt\*[Gt]-\*[Lt]LAmiga\*[Gt]-\*[Lt]F10\*[Gt] 125.It atari 126\*[Lt]Alt\*[Gt]-\*[Lt]LeftShift\*[Gt]-\*[Lt]F9\*[Gt] 127.It hp300 128\*[Lt]Shift\*[Gt]-\*[Lt]Reset\*[Gt] 129.It hp700 130+++++ 131(five plus signs) 132.br 133\*[Lt]Break\*[Gt] on serial console. 134.It hpcarm 135\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 136.It hpcmips 137\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 138.It hpcsh 139\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 140.It i386 141\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 142.br 143\*[Lt]Break\*[Gt] on serial console. 144.It mac68k 145\*[Lt]Command\*[Gt]-\*[Lt]Power\*[Gt], or the Interrupt switch. 146.It macppc 147Some models: 148\*[Lt]Command\*[Gt]-\*[Lt]Option\*[Gt]-\*[Lt]Power\*[Gt] 149.It mvme68k 150Abort switch on CPU card. 151.It pmax 152\*[Lt]Do\*[Gt] on 153.Tn LK-201 154rcons console. 155.br 156\*[Lt]Break\*[Gt] on serial console. 157.It sparc 158\*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a 159.Tn Sun 160keyboard. 161.br 162\*[Lt]Break\*[Gt] on serial console. 163.It sparc64 164\*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a 165.Tn Sun 166keyboard. 167.br 168\*[Lt]Break\*[Gt] on serial console. 169.It sun3 170\*[Lt]L1\*[Gt]-A, or \*[Lt]Stop\*[Gt]-A on a 171.Tn Sun 172keyboard. 173.br 174\*[Lt]Break\*[Gt] on serial console. 175.It vax 176\*[Lt]Esc\*[Gt]-\*[Lt]Shift\*[Gt]-D on serial console. 177.It x68k 178Interrupt switch on the body. 179.It xen 180+++++ 181(five plus signs) 182.El 183.Pp 184The key sequence to activate 185.Nm 186can be changed by modifying 187.Dq hw.cnmagic 188with 189.Xr sysctl 8 . 190If the console is not dedicated to 191.Nm 192the sequence should not be easily typed by accident. 193In addition, 194.Nm 195may be explicitly activated by the debugging code in the kernel 196if 197.Cm DDB 198is configured. 199.Sh COMMAND SYNTAX 200The general command syntax is: 201.Bd -ragged -offset indent 202.Ic command Ns Op Cm / Ns Ar modifier 203.Ar address 204.Op Cm , Ns Ar count 205.Ed 206.Pp 207The current memory location being edited is referred to as 208.Ar dot , 209and the next location is 210.Ar next . 211They are displayed as hexadecimal numbers. 212.Pp 213Commands that examine and/or modify memory update 214.Ar dot 215to the address of the last line examined or the last location 216modified, and set 217.Ar next 218to the next location to be examined or modified. 219Other commands don't change 220.Ar dot , 221and set 222.Ar next 223to be the same as 224.Ar dot . 225.Pp 226A blank line repeats the previous command from the address 227.Ar next 228with the previous 229.Cm count 230and no modifiers. 231Specifying 232.Cm address 233sets 234.Em dot 235to the address. 236If 237.Cm address 238is omitted, 239.Em dot 240is used. 241A missing 242.Cm count 243is taken to be 1 for printing commands, and infinity for stack traces. 244.Pp 245The syntax: 246.Bd -ragged -offset indent 247.Cm , Ns Ar count 248.Ed 249.Pp 250repeats the previous command, just as a blank line does, but with 251the specified 252.Cm count . 253.Pp 254.Nm 255has a 256.Xr more 1 Ns -like 257functionality; if a number of lines in a command's output exceeds the number 258defined in the 259.Va lines 260variable, then 261.Nm 262displays 263.Dq "--db more--" 264and waits for a response, which may be one of: 265.Bl -tag -offset indent -width "\*[Lt]return\*[Gt]" 266.It Aq return 267one more line. 268.It Aq space 269one more page. 270.It Ic q 271abort the current command, and return to the command input mode. 272.El 273.Pp 274You can set 275.Va lines 276variable to zero to disable this feature. 277.Pp 278If 279.Nm 280history editing is enabled (by defining the 281.D1 Cd options DDB_HISTORY_SIZE=num 282kernel option), then a history of the last 283.Cm num 284commands is kept. 285The history can be manipulated with the following key sequences: 286.Bl -tag -offset indent -width "\*[Lt]Ctrl\*[Gt]-P" 287.It \*[Lt]Ctrl\*[Gt]-P 288retrieve previous command in history (if any). 289.It \*[Lt]Ctrl\*[Gt]-N 290retrieve next command in history (if any). 291.El 292.Sh COMMANDS 293.Nm 294supports the following commands: 295.Bl -tag -width 5n 296.It Xo 297.Sm off 298.Ic \&! 299.Ar address 300.Oo 301.Cm ( Ar expression 302.Op Ar ,... 303.Cm ) 304.Oc 305.Sm on 306.Xc 307A synonym for 308.Ic call . 309.It Xo 310.Ic break Ns Op Cm /u 311.Ar address Ns Op Cm , Ns Ar count 312.Xc 313Set a breakpoint at 314.Ar address . 315If 316.Ar count 317is supplied, continues 318.Pq Ar count Ns -1 319times before stopping at the breakpoint. 320If the breakpoint is set, a breakpoint number is printed with 321.Sq \&# . 322This number can be used to 323.Ic delete 324the breakpoint, or to add 325conditions to it. 326.Pp 327If 328.Cm /u 329is specified, 330set a breakpoint at a user-space address. 331Without 332.Cm /u , 333.Ar address 334is considered to be in the kernel-space, and an address in the wrong 335space will be rejected, and an error message will be emitted. 336This modifier may only be used if it is supported by machine dependent 337routines. 338.Pp 339Warning: if a user text is shadowed by a normal user-space debugger, 340user-space breakpoints may not work correctly. 341Setting a breakpoint at the low-level code paths may also cause 342strange behavior. 343.It Xo 344.Ic bt Ns Op Cm /ul 345.Sm off 346.Op Ar frame-address 347.Op Cm , Ar count 348.Sm on 349.Xc 350A synonym for 351.Ic trace . 352.It Xo 353.Ic bt/t Ns Op Cm /ul 354.Sm off 355.Op Ar pid 356.Op Cm , Ar count 357.Sm on 358.Xc 359A synonym for 360.Ic trace/t . 361.It Xo 362.Ic bt/a Ns Op Cm /ul 363.Sm off 364.Op Ar lwpaddr 365.Op Cm , Ar count 366.Sm on 367.Xc 368A synonym for 369.Ic trace/a . 370.It Xo 371.Ic call 372.Sm off 373.Ar address 374.Oo 375.Cm ( Ar expression 376.Op Ar ,... 377.Cm ) 378.Oc 379.Sm on 380.Xc 381Call the function specified by 382.Ar address 383with the argument(s) listed in parentheses. 384Parentheses may be omitted if the function takes no arguments. 385The number of arguments is currently limited to 10. 386.It Ic continue Ns Op Cm /c 387Continue execution until a breakpoint or watchpoint. 388If 389.Cm /c 390is specified, count instructions while executing. 391Some machines (e.g., pmax) also count loads and stores. 392.Pp 393Warning: when counting, the debugger is really silently 394single-stepping. 395This means that single-stepping on low-level may cause strange 396behavior. 397.It Xo 398.Ic delete 399.Ar "address" | 400.Cm # Ns Ar number 401.Xc 402Delete a breakpoint. 403The target breakpoint may be specified by 404.Ar address , 405as per 406.Ic break , 407or by the breakpoint number returned by 408.Ic break 409if it's prefixed with 410.Sq Cm \&# . 411.It Xo 412.Ic dmesg Op Ar count 413.Xc 414Prints the contents of the kernel message buffer. 415The optional 416.Ar count 417argument will limit printing to at most the last 418.Ar count 419bytes of the message buffer. 420.It Xo 421.Ic dwatch 422.Ar address 423.Xc 424Delete the watchpoint at 425.Ar address 426that was previously set with 427.Ic watch 428command. 429.It Xo 430.Ic examine Ns Op Cm / Ns Ar modifier 431.Ar address Ns Op Cm , Ns Ar count 432.Xc 433Display the address locations according to the format in 434.Ar modifier . 435Multiple modifier formats display multiple locations. 436If 437.Ar modifier 438isn't specified, the modifier from the last use of 439.Ic examine 440is used. 441.Pp 442The valid format characters for 443.Ar modifier 444are: 445.Bl -tag -offset indent -width 2n -compact 446.It Cm b 447examine bytes (8 bits). 448.It Cm h 449examine half-words (16 bits). 450.It Cm l 451examine words (legacy 452.Dq long , 45332 bits). 454.It Cm L 455examine long words (implementation dependent) 456.It Cm a 457print the location being examined. 458.It Cm A 459print the location with a line number if possible. 460.It Cm x 461display in unsigned hex. 462.It Cm z 463display in signed hex. 464.It Cm o 465display in unsigned octal. 466.It Cm d 467display in signed decimal. 468.It Cm u 469display in unsigned decimal. 470.It Cm r 471display in current radix, signed. 472.It Cm c 473display low 8 bits as a character. 474Non-printing characters as displayed as an octal escape code 475(e.g., 476.Sq \e000 ) . 477.It Cm s 478display the NUL terminated string at the location. 479Non-printing characters are displayed as octal escapes. 480.It Cm m 481display in unsigned hex with a character dump at the end of each line. 482The location is displayed as hex at the beginning of each line. 483.It Cm i 484display as a machine instruction. 485.It Cm I 486display as a machine instruction, with possible alternative formats 487depending upon the machine: 488.Bl -tag -offset indent -width "sparc" -compact 489.It alpha 490print register operands 491.It m68k 492use Motorola syntax 493.It vax 494don't assume that each external label is a procedure entry mask 495.El 496.El 497.It Xo 498.Ic kill 499.Ar pid Ns Op Cm , Ns Ar signal_number 500.Xc 501Send a signal to the process specified by the 502.Ar pid . 503Note that 504.Ar pid 505is interpreted using the current radix (see 506.Cm trace/t 507command for details). 508If 509.Ar signal_number 510isn't specified, the SIGTERM signal is sent. 511.It Ic match Ns Op Cm /p 512A synonym for 513.Ic next . 514.It Ic next Ns Op Cm /p 515Stop at the matching return instruction. 516If 517.Cm /p 518is specified, print the call nesting depth and the 519cumulative instruction count at each call or return. 520Otherwise, only print when the matching return is hit. 521.It Xo 522.Ic print Ns Op Cm /axzodurc 523.Ar address Op Ar address ... 524.Xc 525Print addresses 526.Ar address 527according to the modifier character, as per 528.Ic examine . 529Valid modifiers are: 530.Cm /a , 531.Cm /x , 532.Cm /z , 533.Cm /o , 534.Cm /d , 535.Cm /u , 536.Cm /r , 537and 538.Cm /c 539(as per 540.Ic examine ) . 541If no modifier is specified, the most recent one specified is used. 542.Ar address 543may be a string, and is printed 544.Dq as-is . 545For example: 546.Bd -literal -offset indent 547print/x "eax = " $eax "\enecx = " $ecx "\en" 548.Ed 549.Pp 550will produce: 551.Bd -literal -offset indent 552eax = xxxxxx 553ecx = yyyyyy 554.Ed 555.It Xo 556.Sm off 557.Ic ps 558.Op Cm /a 559.Op Cm /n 560.Op Cm /w 561.Op Cm /l 562.Sm on 563.Xc 564A synonym for 565.Ic show all procs . 566.It Ic reboot Op Ar flags 567Reboot, using the optionally supplied boot 568.Ar flags , 569which is a bitmask supporting the same values as for 570.Xr reboot 2 . 571Some of the more useful flags: 572.Bl -column "Value" "RB_POWERDOWN" "Description" 573.It Sy "Value" Ta Sy "Name" Ta Sy "Description" 574.It 0x1 Ta RB_ASKNAME Ta Ask for file name to reboot from 575.It 0x2 Ta RB_SINGLE Ta Reboot to single user mode 576.It 0x4 Ta RB_NOSYNC Ta Don't sync before reboot 577.It 0x8 Ta RB_HALT Ta Halt instead of reboot 578.It 0x40 Ta RB_KDB Ta Boot into kernel debugger 579.It 0x100 Ta RB_DUMP Ta Dump unconditionally before reboot 580.It 0x808 Ta RB_POWERDOWN Ta Power off (or at least halt) 581.El 582.Pp 583Note: Limitations of the command line interface preclude 584specification of a boot string. 585.It Xo 586.Ic search Ns Op Cm /bhl 587.Ar address 588.Ar value 589.Op Ar mask 590.Op Cm , Ns Ar count 591.Xc 592Search memory from 593.Ar address 594for 595.Ar value . 596The unit size is specified with a modifier character, as per 597.Ic examine . 598Valid modifiers are: 599.Cm /b , 600.Cm /h , 601and 602.Cm /l . 603If no modifier is specified, 604.Cm /l 605is used. 606.Pp 607This command might fail in interesting ways if it doesn't find 608.Ar value . 609This is because 610.Nm 611doesn't always recover from touching bad memory. 612The optional 613.Ar count 614limits the search. 615.It Xo 616.Ic set 617.Cm $ Ns Ar variable 618.Op Cm = 619.Ar expression 620.Xc 621Set the named variable or register to the value of 622.Ar expression . 623Valid variable names are described in 624.Sx VARIABLES . 625.It Ic show all callout 626Display information about callouts in the system. 627See 628.Xr callout 9 629for more information on callouts. 630.It Ic show all pages 631Display basic information about all physical pages managed by the VM system. 632For more detailed information about a single page, use 633.Ic show page . 634.It Ic show all pools Ns Op Cm /clp 635Display all pool information. 636Modifiers are the same as 637.Ic show pool . 638.It Xo 639.Sm off 640.Ic "show\ all\ procs" 641.Op Cm /a 642.Op Cm /n 643.Op Cm /w 644.Op Cm /l 645.Sm on 646.Xc 647Display all process information. 648Valid modifiers: 649.Bl -tag -width 3n 650.It Cm /n 651show process information in a 652.Xr ps 1 653style format (this is the default). 654Information printed includes: process ID, parent process ID, 655process group, UID, process status, process flags, process 656command name, and process wait channel message. 657.It Cm /a 658show the kernel virtual addresses of each process' 659proc structure, u-area, and vmspace structure. 660The vmspace address is also the address of the process' 661vm_map structure, and can be used in the 662.Ic show map 663command. 664.It Cm /w 665show each process' PID, command, system call emulation, wait channel 666address, and wait channel message. 667.It Cm /l 668show each process' associated LWP information, including each LWP's 669LID, flags, kernel LWP structure address, u-area, and wait channel. 670.El 671.It Ic show arptab 672Dump the entire 673.Dv AF_INET 674routing table. 675This command is available only on systems which support inet and ARP. 676.It Ic show breaks 677Display all breakpoints. 678.It Xo 679.Ic show buf Ns Op Cm /f 680.Ar address 681.Xc 682Print the struct buf at 683.Ar address . 684The 685.Cm /f 686does nothing at this time. 687.It Xo 688.Ic show event Ns Op Cm /f 689.Xc 690Print all the non-zero 691.Xr evcnt 9 692event counters. 693If 694.Cm /f 695is specified, all event counters with a count of zero are printed as well. 696.It Xo 697.Ic show lock 698.Ar address 699.Xc 700Display information about a lock at 701.Ar address . 702This command is useful only if a kernel is compiled with 703.Cd options LOCKDEBUG . 704.It Xo 705.Ic show malloc 706.Ar address 707.Xc 708If 709.Ar address 710is supplied, display the kernel memory allocator's idea on the 711allocation status for it. 712Also, print out global statistics for the memory allocator. 713This command is useful only if a kernel is compiled with 714.Cd options MALLOC_DEBUG . 715.It Xo 716.Ic show map Ns Op Cm /f 717.Ar address 718.Xc 719Print the vm_map at 720.Ar address . 721If 722.Cm /f 723is specified, the complete map is printed. 724.It Xo 725.Ic show mount Ns Op Cm /f 726.Ar address 727.Xc 728Print the mount structure at 729.Ar address . 730If 731.Cm /f 732is specified, the complete vnode list is printed. 733.It Xo 734.Ic show mbuf Ns Op Cm /c 735.Ar address 736.Xc 737Print the mbuf structure at 738.Ar address . 739If 740.Cm /c 741is specified, the mbufs in the chain are followed. 742.It Ic show ncache Ar address 743Dump the namecache list associated with vnode at 744.Ar address . 745.It Xo 746.Ic show object Ns Op Cm /f 747.Ar address 748.Xc 749Print the vm_object at 750.Ar address . 751If 752.Cm /f 753is specified, the complete object is printed. 754.It Xo 755.Ic show page Ns Op Cm /f 756.Ar address 757.Xc 758Print the vm_page at 759.Ar address . 760If 761.Cm /f 762is specified, the complete page is printed. 763.It Xo 764.Ic show pool Ns Op Cm /clp 765.Ar address 766.Xc 767Print the pool at 768.Ar address . 769Valid modifiers: 770.Bl -tag -width 4n -compact 771.It Cm /c 772Print the cachelist and its statistics for this pool. 773.It Cm /l 774Print the log entries for this pool. 775.It Cm /p 776Print the pagelist for this pool. 777.El 778.It Ic show registers Ns Op Cm /u 779Display the register set. 780If 781.Cm /u 782is specified, display user registers instead of kernel registers 783or the currently save one. 784.Pp 785Warning: support for 786.Cm /u 787is machine dependent. 788If not supported, incorrect information will be displayed. 789.It Ic show sched_qs 790Print the state of the scheduler's run queues. 791For each run queue that has an LWP, the run queue index and the list 792of LWPs will be shown. 793If the run queue has LWPs, but the sched_whichqs bit is not set for that 794queue, the queue index will be prefixed with a 795.Sq \&! . 796.It Ic show uvmexp 797Print a selection of UVM counters and statistics. 798.It Xo 799.Ic show vnode Ns Op Cm /f 800.Ar address 801.Xc 802Print the vnode at 803.Ar address . 804If 805.Cm /f 806is specified, the complete vnode is printed. 807.It Ic show watches 808Display all watchpoints. 809.It Xo 810.Ic sifting Ns Op Cm /F 811.Ar string 812.Xc 813Search the symbol tables for all symbols of which 814.Ar string 815is a substring, and display them. 816If 817.Cm /F 818is specified, a character is displayed immediately after each symbol 819name indicating the type of symbol. 820.Pp 821For 822.Xr a.out 5 Ns -format 823symbol tables, 824absolute symbols display 825.Sy @ , 826text segment symbols display 827.Sy * , 828data segment symbols display 829.Sy + , 830.Tn BSS 831segment symbols display 832.Sy - , 833and filename symbols display 834.Sy / . 835For 836.Tn ELF Ns -format 837symbol tables, 838object symbols display 839.Sy + , 840function symbols display 841.Sy * , 842section symbols display 843.Sy \*[Am] , 844and file symbols display 845.Sy / . 846.Pp 847To sift for a string beginning with a number, escape the first 848character with a backslash as: 849.Bd -literal -offset indent 850sifting \\386 851.Ed 852.It Xo 853.Ic step Ns Op Cm /p 854.Op Cm , Ns Ar count 855.Xc 856Single-step 857.Ar count 858times. 859If 860.Cm /p 861is specified, print each instruction at each step. 862Otherwise, only print the last instruction. 863.Pp 864Warning: depending on the machine type, it may not be possible 865to single-step through some low-level code paths or user-space 866code. 867On machines with software-emulated single-stepping (e.g., pmax), 868stepping through code executed by interrupt handlers will probably 869do the wrong thing. 870.It Ic sync 871Force a crash dump, and then reboot. 872.It Xo 873.Ic trace Ns Op Cm /u Ns Op Cm l 874.Sm off 875.Op Ar frame-address 876.Op Cm , Ar count 877.Sm on 878.Xc 879Stack trace from 880.Ar frame-address . 881If 882.Cm /u 883is specified, trace user-space, otherwise trace kernel-space. 884.Ar count 885is the number of frames to be traced. 886If 887.Ar count 888is omitted, all frames are printed. 889If 890.Cm /l 891is specified, the trace is printed and also stored in the kernel 892message buffer. 893.Pp 894Warning: user-space stack trace is valid only if the machine dependent 895code supports it. 896.It Xo 897.Ic trace/t Ns Op Cm l 898.Sm off 899.Op Ar pid 900.Op Cm , Ar count 901.Sm on 902.Xc 903Stack trace by 904.Dq thread 905(process, on 906.Nx ) 907rather than by stack frame address. 908Note that 909.Ar pid 910is interpreted using the current radix, whilst 911.Ic ps 912displays pids in decimal; prefix 913.Ar pid 914with 915.Sq 0t 916to force it to be interpreted as decimal (see 917.Sx VARIABLES 918section for radix). 919If 920.Cm /l 921is specified, the trace is printed and also stored in the kernel 922message buffer. 923.Pp 924Warning: trace by pid is valid only if the machine dependent code 925supports it. 926.It Xo 927.Ic trace/a Ns Op Cm l 928.Sm off 929.Op Ar lwpaddr 930.Op Cm , Ar count 931.Sm on 932.Xc 933Stack trace by light weight process (LWP) address 934rather than by stack frame address. 935If 936.Cm /l 937is specified, the trace is printed and also stored in the kernel 938message buffer. 939.Pp 940Warning: trace by LWP address is valid only if the machine dependent 941code supports it. 942.It Ic until Ns Op Cm /p 943Stop at the next call or return instruction. 944If 945.Cm /p 946is specified, print the call nesting depth and the 947cumulative instruction count at each call or return. 948Otherwise, only print when the matching return is hit. 949.It Xo 950.Ic watch 951.Sm off 952.Ar address 953.Op Cm , Ar size 954.Sm on 955.Xc 956Set a watchpoint for a region. 957Execution stops when an attempt to modify the region occurs. 958.Ar size 959defaults to 4. 960.Pp 961If you specify a wrong space address, the request is 962rejected with an error message. 963.Pp 964Warning: attempts to watch wired kernel memory may cause 965an unrecoverable error in some systems such as i386. 966Watchpoints on user addresses work the best. 967.It Xo 968.Ic whatis 969.Sm off 970.Ar address 971.Sm on 972.Xc 973Describe what an address is. 974.It Xo 975.Ic write Ns Op Cm /bhl 976.Ar address 977.Ar expression Op Ar expression ... 978.Xc 979Write the 980.Ar expression Ns s 981at succeeding locations. 982The unit size is specified with a modifier character, as per 983.Ic examine . 984Valid modifiers are: 985.Cm /b , 986.Cm /h , 987and 988.Cm /l . 989If no modifier is specified, 990.Cm /l 991is used. 992.Pp 993Warning: since there is no delimiter between 994.Ar expression Ns s , 995strange things may occur. 996It's best to enclose each 997.Ar expression 998in parentheses. 999.It Xo 1000.Ic x Ns Op Cm / Ns Ar modifier 1001.Ar address Ns Op Cm , Ns Ar count 1002.Xc 1003A synonym for 1004.Ic examine . 1005.\" XXX - these commands aren't implemented; jhawk 19 May 2000 1006.\" .It Ic xf 1007.\" Examine forward. 1008.\" .Ic xf 1009.\" re-executes the most recent 1010.\" .Ic execute 1011.\" command with the same parameters except that 1012.\" .Ar address 1013.\" is set to 1014.\" .Ar next . 1015.\" .It Ic xb 1016.\" Examine backward. 1017.\" .Ic xb 1018.\" re-executes the most recent 1019.\" .Ic execute 1020.\" command with the same parameters, except that 1021.\" .Ar address 1022.\" is set to the last start address minus its size. 1023.El 1024.Sh MACHINE-SPECIFIC COMMANDS 1025The "glue" code that hooks 1026.Nm 1027into the 1028.Nx 1029kernel for any given port can also add machine specific commands 1030to the 1031.Nm 1032command parser. 1033All of these commands are preceded by the command word 1034.Em machine 1035to indicate that they are part of the machine-specific command 1036set (e.g. 1037.Ic machine reboot ) . 1038Some of these commands are: 1039.Ss ALPHA 1040.Bl -tag -width "traptrace" -compact 1041.It Ic halt 1042Call the PROM monitor to halt the CPU. 1043.It Ic reboot 1044Call the PROM monitor to reboot the CPU. 1045.El 1046.Ss ARM32 1047.Bl -tag -width "traptrace" -compact 1048.It Ic panic 1049Print the current "panic" string. 1050.It Ic frame 1051Given a trap frame address, print out the trap frame. 1052.El 1053.Ss MIPS 1054.Bl -tag -width "traptrace" -compact 1055.It Ic kvtop 1056Print the physical address for a given kernel virtual address. 1057.It Ic tlb 1058Print out the Translation Lookaside Buffer (TLB). 1059Only works in 1060.Nx 1061kernels compiled with 1062.Dv DEBUG 1063option. 1064.El 1065.Ss SH3 1066.Bl -tag -width "traptrace" -compact 1067.It Ic tlb 1068Print TLB entries 1069.It Ic cache 1070Print cache entries 1071.It Ic frame 1072Print switch frame and trap frames. 1073.It Ic stack 1074Print kernel stack usage. 1075Only works in 1076.Nx 1077kernels compiled with the 1078.Dv KSTACK_DEBUG 1079option. 1080.El 1081.Ss SPARC 1082.Bl -tag -width "traptrace" -compact 1083.It Ic prom 1084Exit to the Sun PROM monitor. 1085.El 1086.Ss SPARC64 1087.Bl -tag -width "traptrace" -compact 1088.It Ic ctx 1089Print process context information. 1090.It Ic cpu 1091Switch to another cpu. 1092.It Ic dtlb 1093Print data translation look-aside buffer context information. 1094.It Ic dtsb 1095Display data translation storage buffer information. 1096.It Ic kmap 1097Display information about the listed mapping in the kernel pmap. 1098Use the 1099.Dq f 1100modifier to get a full listing. 1101.It Ic extract 1102Extract the physical address for a given virtual address from the kernel pmap. 1103.It Ic fpstate 1104Dump the FPU state. 1105.It Ic itlb 1106Print instruction translation look-aside buffer context information. 1107.It Ic itsb 1108Display instruction translation storage buffer information. 1109.It Ic lwp 1110Display a struct lwp 1111.It Ic pcb 1112Display information about the 1113.Dq struct pcb 1114listed. 1115.It Ic pctx 1116Attempt to change process context. 1117.It Ic page 1118Display the pointer to the 1119.Dq struct vm_page 1120for this physical address. 1121.It Ic phys 1122Display physical memory. 1123.It Ic pmap 1124Display the pmap. 1125Use the 1126.Dq f 1127modifier to get a fuller listing. 1128.It Ic proc 1129Display some information about the process pointed to, or curproc. 1130.It Ic prom 1131Enter the OFW PROM. 1132.It Ic pv 1133Display the 1134.Dq struct pv_entry 1135pointed to. 1136.It Ic sir 1137Reset the machine and enter prom (do a Software Initiated Reset). 1138.It Ic stack 1139Dump the window stack. 1140Use the 1141.Dq u 1142modifier to get userland information. 1143.It Ic tf 1144Display full trap frame state. 1145This is most useful for inclusion with bug reports. 1146.It Ic ts 1147Display trap state. 1148.It Ic traptrace 1149Display or set trap trace information. 1150Use the 1151.Dq r 1152and 1153.Dq f 1154modifiers to get reversed and full information, respectively. 1155.It Ic uvmdump 1156Dumps the UVM histories. 1157.It Ic watch 1158Set or clear a physical or virtual hardware watchpoint. 1159Pass the address to be watched, or 1160.Dq 0 1161(or omit the address) to clear the watchpoint. 1162Optional modifiers are 1163.Dq p 1164for physical address, 1165.Dq r 1166for trap on read access (default: trap on write access only), 1167.Dq b 1168for 8 bit width, 1169.Dq h 1170for 16 bit, 1171.Dq l 1172for 32 bit or 1173.Dq L 1174for 64 bit. 1175.It Ic window 1176Print register window information. Argument is a stack frame number (0 is 1177top of stack, which is used when no index is given). 1178.El 1179.Ss SUN3 and SUN3X 1180.Bl -tag -width "traptrace" -compact 1181.It Ic abort 1182Drop into monitor via abort (allows continue). 1183.It Ic halt 1184Exit to Sun PROM monitor as in 1185.Xr halt 8 . 1186.It Ic reboot 1187Reboot the machine as in 1188.Xr reboot 8 . 1189.It Ic pgmap 1190Given an address, print the address, segment map, page map, and 1191Page Table Entry (PTE). 1192.El 1193.Sh VARIABLES 1194.Nm 1195accesses registers and variables as 1196.Cm $ Ns Ar name . 1197Register names are as per the 1198.Ic show registers 1199command. 1200Some variables are suffixed with numbers, and may have a modifier 1201following a colon immediately after the variable name. 1202For example, register variables may have a 1203.Sq u 1204modifier to indicate user register 1205(e.g., 1206.Li "$eax:u" ) . 1207.Pp 1208Built-in variables currently supported are: 1209.Bl -tag -offset indent -width "maxwidth" -compact 1210.It Va lines 1211The number of lines. 1212This is used by the 1213.Ic more 1214feature. 1215When this variable is set to zero the 1216.Ic more 1217feature is disabled. 1218.It Va maxoff 1219Addresses are printed as 1220.Li 'symbol'+offset 1221unless 1222.Li offset 1223is greater than 1224.Va maxoff . 1225.It Va maxwidth 1226The width of the displayed line. 1227.Nm 1228wraps the current line by printing new line when 1229.Va maxwidth 1230column is reached. 1231When this variable is set to zero 1232.Nm 1233doesn't perform any wrapping. 1234.It Va onpanic 1235If non-zero (the default), 1236.Nm 1237will be invoked when the kernel panics. 1238If the kernel configuration option 1239.D1 Cd options DDB_ONPANIC=0 1240is used, 1241.Va onpanic 1242will be initialized to off. 1243.It Va fromconsole 1244If non-zero (the default), 1245the kernel allows to enter 1246.Nm 1247from the console (by break signal or special key sequence). 1248If the kernel configuration option 1249.D1 Cd options DDB_FROMCONSOLE=0 1250is used, 1251.Va fromconsole 1252will be initialized to off. 1253.It Va radix 1254Input and output radix. 1255.It Va tabstops 1256Tab stop width. 1257.It Va tee_msgbuf 1258If explicitly set to non zero (zero is the default) all 1259.Nm 1260output will not only be displayed on screen but 1261also be fed to the msgbuf. 1262The default of the variable can be set using the kernel configuration option 1263.D1 Cd options DDB_TEE_MSGBUF=1 1264which will initialize 1265.Va tee_msgbuf 1266to be 1. 1267This option is especially handy for poor souls 1268who don't have a serial console but want to recall 1269.Nm 1270output from a crash investigation. 1271This option is more generic than the /l command modifier possible for 1272selected commands as discussed above to log the output. 1273Mixing both /l 1274and this setting can give double loggings. 1275.\" .It Va work Ns Sy xx 1276.\" Temporary work variable. 1277.\" .Sq Sy xx 1278.\" is between 0 and 31. 1279.El 1280.Pp 1281All built-in variables are accessible via 1282.Xr sysctl 3 . 1283.Sh EXPRESSIONS 1284Almost all expression operators in C are supported, except 1285.Sq \&~ , 1286.Sq \&^ , 1287and unary 1288.Sq \&\*[Am] . 1289Special rules in 1290.Nm 1291are: 1292.Bl -tag -offset indent -width "identifier" 1293.It Ar identifier 1294name of a symbol. 1295It is translated to the address (or value) of it. 1296.Sq \&. 1297and 1298.Sq \&: 1299can be used in the identifier. 1300If supported by an object format dependent routine, 1301.Sm off 1302.Xo 1303.Oo Ar filename : Oc 1304.Ar function 1305.Oo : Ar line\ number Oc , 1306.Xc 1307.Sm on 1308.Sm off 1309.Xo 1310.Oo Ar filename : Oc 1311.Ar variable , 1312.Xc 1313.Sm on 1314and 1315.Sm off 1316.Xo 1317.Ar filename 1318.Oo : Ar "line number" Oc , 1319.Xc 1320.Sm on 1321can be accepted as a symbol. 1322The symbol may be prefixed with 1323.Ar symbol_table_name\^ : : 1324(e.g., 1325.Li emulator::mach_msg_trap ) 1326to specify other than kernel symbols. 1327.It Ar number 1328number. 1329Radix is determined by the first two characters: 1330.Sq 0x 1331- hex, 1332.Sq 0o 1333- octal, 1334.Sq 0t 1335- decimal, 1336otherwise follow current radix. 1337.It Cm . 1338.Ar dot 1339.It Cm + 1340.Ar next 1341.It Cm .. 1342address of the start of the last line examined. 1343Unlike 1344.Ar dot 1345or 1346.Ar next , 1347this is only changed by the 1348.Ic examine 1349or 1350.Ic write 1351commands. 1352.It Cm \&" \"" XXX: emacs highlighting 1353last address explicitly specified. 1354.It Cm $ Ns Ar name 1355register name or variable. 1356It is translated to the value of it. 1357It may be followed by a 1358.Sq \&: 1359and modifiers as described above. 1360.It Cm # 1361a binary operator which rounds up the left hand side to the next 1362multiple of right hand side. 1363.It Cm * Ns Ar expr 1364expression indirection. 1365It may be followed by a 1366.Sq \&: 1367and modifiers as described above. 1368.El 1369.Sh SEE ALSO 1370.Xr reboot 2 , 1371.Xr options 4 , 1372.Xr reboot 8 , 1373.Xr sysctl 8 , 1374.Xr cnmagic 9 1375.Sh HISTORY 1376The 1377.Nm 1378kernel debugger was written as part of the MACH project at 1379Carnegie-Mellon University. 1380