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