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