1.\" $NetBSD: ddb.4,v 1.156 2014/06/12 13:47:58 christos 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 12, 2014 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 hpcarm 123\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 124.It hpcmips 125\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 126.It hpcsh 127\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] 128.It hppa 129\*[Lt]Ctrl\*[Gt]-\*[Lt]Alt\*[Gt]-\*[Lt]Esc\*[Gt] on PC style keyboards. 130.It "" 131+++++ 132(five plus signs) on PDC console 133.It "" 134\*[Lt]Break\*[Gt] on serial console. 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 map Ns Oo Cm /f Oc Ar address 661Print the vm_map at 662.Ar address . 663If 664.Cm /f 665is specified, the complete map is printed. 666.It Ic show mount Ns Oo Cm /f Oc Ar address 667Print the mount structure at 668.Ar address . 669If 670.Cm /f 671is specified, the complete vnode list is printed. 672.It Ic show mbuf Ns Oo Cm /c Oc Ar address 673Print the mbuf structure at 674.Ar address . 675If 676.Cm /c 677is specified, the mbufs in the chain are followed. 678.It Ic show ncache Ar address 679Dump the namecache list associated with vnode at 680.Ar address . 681.It Ic show object Ns Oo Cm /f Oc Ar address 682Print the vm_object at 683.Ar address . 684If 685.Cm /f 686is specified, the complete object is printed. 687.It Ic show page Ns Oo Cm /f Oc Ar address 688Print the vm_page at 689.Ar address . 690If 691.Cm /f 692is specified, the complete page is printed. 693.It Ic show panic 694Print the current "panic" string. 695.It Ic show pool Ns Oo Cm /clp Oc Ar address 696Print the pool at 697.Ar address . 698Valid modifiers: 699.Bl -tag -width 4n -compact 700.It Cm /c 701Print the cachelist and its statistics for this pool. 702.It Cm /l 703Print the log entries for this pool. 704.It Cm /p 705Print the pagelist for this pool. 706.El 707.It Ic show proc Ns Oo Cm /ap Oc Ar address | pid 708Show information about a process and its LWPs. 709LWPs currently running on a CPU are marked with the '\&>' sign. 710.Bl -tag -width 4n -compact 711.It Cm /a 712The argument passed is the kernel virtual address 713of LWP structure. 714.It Cm /p 715The argument passed is a PID. 716Note that 717.Ar pid 718is interpreted using the current radix (see 719.Cm trace/t 720command for details). 721This is the default. 722.El 723.It Ic show registers Ns Op Cm /u 724Display the register set. 725If 726.Cm /u 727is specified, display user registers instead of kernel registers 728or the currently save one. 729.Pp 730Warning: support for 731.Cm /u 732is machine dependent. 733If not supported, incorrect information will be displayed. 734.It Ic show sched_qs 735Print the state of the scheduler's run queues. 736For each run queue that has an LWP, the run queue index and the list 737of LWPs will be shown. 738If the run queue has LWPs, but the sched_whichqs bit is not set for that 739queue, the queue index will be prefixed with a 740.Sq \&! . 741.It Ic show uvmexp 742Print a selection of UVM counters and statistics. 743.It Ic show kernhist 744Dumps the kernel histories. 745This command is available only if a kernel is compiled with 746.Cd options KERNHIST 747or 748.Cd options UVMHIST . 749.It Ic show vnode Ns Oo Cm /f Oc Ar address 750Print the vnode at 751.Ar address . 752If 753.Cm /f 754is specified, the complete vnode is printed. 755.It Ic show watches 756Display all watchpoints. 757.It Ic sifting Ns Oo Cm /F Oc Ar string 758Search the symbol tables for all symbols of which 759.Ar string 760is a substring, and display them. 761If 762.Cm /F 763is specified, a character is displayed immediately after each symbol 764name indicating the type of symbol. 765.Pp 766For 767.Xr a.out 5 Ns -format 768symbol tables, 769absolute symbols display 770.Sy @ , 771text segment symbols display 772.Sy * , 773data segment symbols display 774.Sy + , 775.Tn BSS 776segment symbols display 777.Sy - , 778and filename symbols display 779.Sy / . 780For 781.Tn ELF Ns -format 782symbol tables, 783object symbols display 784.Sy + , 785function symbols display 786.Sy * , 787section symbols display 788.Sy \*[Am] , 789and file symbols display 790.Sy / . 791.Pp 792To sift for a string beginning with a number, escape the first 793character with a backslash as: 794.Bd -literal -offset indent 795sifting \\386 796.Ed 797.It Ic step Ns Oo Cm /p Oc Op Cm , Ns Ar count 798Single-step 799.Ar count 800times. 801If 802.Cm /p 803is specified, print each instruction at each step. 804Otherwise, only print the last instruction. 805.Pp 806Warning: depending on the machine type, it may not be possible 807to single-step through some low-level code paths or user-space 808code. 809On machines with software-emulated single-stepping (e.g., pmax), 810stepping through code executed by interrupt handlers will probably 811do the wrong thing. 812.It Ic sync 813Sync the disks, force a crash dump, and then reboot. 814.It Ic trace Ns Oo Cm /u Ns Oo Cm l Oc Oc Oo Ar frame-address Oc Ns \ 815Oo Cm , Ns Ar count Oc 816Stack trace from 817.Ar frame-address . 818If 819.Cm /u 820is specified, trace user-space, otherwise trace kernel-space. 821.Ar count 822is the number of frames to be traced. 823If 824.Ar count 825is omitted, all frames are printed. 826If 827.Cm /l 828is specified, the trace is printed and also stored in the kernel 829message buffer. 830.Pp 831Warning: user-space stack trace is valid only if the machine dependent 832code supports it. 833.It Ic trace/t Ns Oo Cm l Oc Oo Ar pid Oc Ns Oo Cm , Ns Ar count Oc 834Stack trace by 835.Dq thread 836(process, on 837.Nx ) 838rather than by stack frame address. 839Note that 840.Ar pid 841is interpreted using the current radix, whilst 842.Ic ps 843displays pids in decimal; prefix 844.Ar pid 845with 846.Sq 0t 847to force it to be interpreted as decimal (see 848.Sx VARIABLES 849section for radix). 850If 851.Cm /l 852is specified, the trace is printed and also stored in the kernel 853message buffer. 854.Pp 855Warning: trace by pid is valid only if the machine dependent code 856supports it. 857.It Ic trace/a Ns Oo Cm l Oc Oo Ar lwpaddr Oc Ns Oo Cm , Ns Ar count Oc 858Stack trace by light weight process (LWP) address 859rather than by stack frame address. 860If 861.Cm /l 862is specified, the trace is printed and also stored in the kernel 863message buffer. 864.Pp 865Warning: trace by LWP address is valid only if the machine dependent 866code supports it. 867.It Ic until Ns Op Cm /p 868Stop at the next call or return instruction. 869If 870.Cm /p 871is specified, print the call nesting depth and the 872cumulative instruction count at each call or return. 873Otherwise, only print when the matching return is hit. 874.It Ic watch Ar address Ns Oo Cm , Ns Ar size Oc 875Set a watchpoint for a region. 876Execution stops when an attempt to modify the region occurs. 877.Ar size 878defaults to 4. 879.Pp 880If you specify a wrong space address, the request is 881rejected with an error message. 882.Pp 883Warning: attempts to watch wired kernel memory may cause 884an unrecoverable error in some systems such as i386. 885Watchpoints on user addresses work the best. 886.It Ic whatis Ar address 887Describe what an address is. 888.It Ic write Ns Oo Cm /bhlBHL Oc Ar address Ar expression Oo Ar expression ... Oc 889Write the 890.Ar expression Ns s 891at succeeding locations. 892The unit size is specified with a modifier character, as per 893.Ic examine . 894Valid modifiers are: 895.Cm /b , 896.Cm /h , 897and 898.Cm /l . 899If no modifier is specified, 900.Cm /l 901is used. 902.Pp 903Specifying the modifiers in upper case, 904.Cm /B , 905.Cm /H , 906.Cm /L , 907will prevent 908.Nm 909from reading the memory location first, which is useful for avoiding 910side effects when writing to I/O memory regions. 911.Pp 912Warning: since there is no delimiter between 913.Ar expression Ns s , 914strange things may occur. 915It's best to enclose each 916.Ar expression 917in parentheses. 918.It Ic x Ns Oo Cm / Ns Ar modifier Oc Ar address Ns Op Cm , Ns Ar count 919A synonym for 920.Ic examine . 921.\" XXX - these commands aren't implemented; jhawk 19 May 2000 922.\" .It Ic xf 923.\" Examine forward. 924.\" .Ic xf 925.\" re-executes the most recent 926.\" .Ic execute 927.\" command with the same parameters except that 928.\" .Ar address 929.\" is set to 930.\" .Ar next . 931.\" .It Ic xb 932.\" Examine backward. 933.\" .Ic xb 934.\" re-executes the most recent 935.\" .Ic execute 936.\" command with the same parameters, except that 937.\" .Ar address 938.\" is set to the last start address minus its size. 939.El 940.Sh MACHINE-SPECIFIC COMMANDS 941The "glue" code that hooks 942.Nm 943into the 944.Nx 945kernel for any given port can also add machine specific commands 946to the 947.Nm 948command parser. 949All of these commands are preceded by the command word 950.Em machine 951to indicate that they are part of the machine-specific command 952set (e.g. 953.Ic machine reboot ) . 954Some of these commands are: 955.Ss ACORN26 956.Bl -tag -width "traptrace" -compact 957.It Ic bsw 958Writes one or two bytes to the IObus. 959Takes an address and a value. 960Use the 961.Dq b 962modifier to write a single byte and the 963.Dq h 964modifier to write two bytes. 965.It Ic frame 966Given a trap frame address, print out the trap frame. 967.It Ic irqstat 968Display the IRQ statistics 969.El 970.Ss ALPHA 971.Bl -tag -width "traptrace" -compact 972.It Ic cpu 973Switch to another cpu. 974.\" .It Ic halt 975.\" Call the PROM monitor to halt the CPU. 976.\" .It Ic reboot 977.\" Call the PROM monitor to reboot the CPU. 978.El 979.Ss AMD64 980.Bl -tag -width "traptrace" -compact 981.It Ic cpu 982Switch to another cpu. 983.El 984.Ss ARM32 985.Bl -tag -width "traptrace" -compact 986.It Ic frame 987Given a trap frame address, print out the trap frame. 988.El 989.Ss HPPA 990.Bl -tag -width "traptrace" -compact 991.It Ic frame 992Without an address the default trap frame is printed. 993Otherwise, the trap frame address can be given, or, when the 994.Dq l 995modifier is used, an LWP address. 996.El 997.Ss I386 998.Bl -tag -width "traptrace" -compact 999.It Ic cpu 1000Switch to another cpu. 1001.El 1002.Ss IA64 1003.Bl -tag -width "traptrace" -compact 1004.It Ic vector 1005Without a vector, information about all 256 vectors is shown. 1006Otherwise, the given vector is shown. 1007.El 1008.Ss MIPS 1009.Bl -tag -width "traptrace" -compact 1010.It Ic cp0 1011Dump CP0 (coprocessor 0) register values. 1012.It Ic kvtop 1013Print the physical address for a given kernel virtual address. 1014.It Ic tlb 1015Print out the Translation Lookaside Buffer (TLB). 1016Only works in 1017.Nx 1018kernels compiled with 1019.Dv DEBUG 1020option. 1021.El 1022.Ss POWERPC 4xx 1023.Bl -tag -width "traptrace" -compact 1024.It Ic ctx 1025Print process MMU context information. 1026.It Ic pv 1027Print PA-\*[Gt]VA mapping information. 1028.It Ic reset 1029Reset the system. 1030.It Ic tf 1031Display the contents of the trapframe. 1032.It Ic tlb 1033Display instruction translation storage buffer information. 1034.It Ic dcr 1035Set the DCR register. 1036Must be between 0x00 and 0x3ff. 1037.It Ic user 1038Display user memory. 1039Use the 1040.Dq i 1041modifier to get instruction decoding. 1042.El 1043.Ss POWERPC OEA 1044.Bl -tag -width "traptrace" -compact 1045.It Ic bat 1046Print BAT registers and translations. 1047.It Ic mmu 1048Print MMU registers. 1049.El 1050.Ss SH3 1051.Bl -tag -width "traptrace" -compact 1052.It Ic tlb 1053Print TLB entries. 1054.It Ic cache 1055Print cache entries. 1056.It Ic frame 1057Print switch frame and trap frames. 1058.It Ic stack 1059Print kernel stack usage. 1060Only works in 1061.Nx 1062kernels compiled with the 1063.Dv KSTACK_DEBUG 1064option. 1065.El 1066.Ss SPARC 1067.Bl -tag -width "traptrace" -compact 1068.It Ic cpu 1069Switch to another cpu. 1070.It Ic prom 1071Enter the Sun PROM monitor. 1072.It Ic proc 1073Display some information about the LWP pointed to, or curlwp. 1074.It Ic pcb 1075Display information about the 1076.Dq struct pcb 1077listed. 1078.It Ic page 1079Display the pointer to the 1080.Dq struct vm_page 1081for this physical address. 1082.El 1083.Ss SPARC64 1084.Bl -tag -width "traptrace" -compact 1085.It Ic ctx 1086Print process context information. 1087.It Ic cpu 1088Switch to another cpu. 1089.It Ic dtlb 1090Print data translation look-aside buffer context information. 1091.It Ic dtsb 1092Display data translation storage buffer information. 1093.It Ic kmap 1094Display information about the listed mapping in the kernel pmap. 1095Use the 1096.Dq f 1097modifier to get a full listing. 1098.It Ic extract 1099Extract the physical address for a given virtual address from the kernel pmap. 1100.It Ic fpstate 1101Dump the FPU state. 1102.It Ic itlb 1103Print instruction translation look-aside buffer context information. 1104.It Ic itsb 1105Display instruction translation storage buffer information. 1106.It Ic lwp 1107Display a struct lwp 1108.It Ic pcb 1109Display information about the 1110.Dq struct pcb 1111listed. 1112.It Ic pctx 1113Attempt to change process context. 1114.It Ic page 1115Display the pointer to the 1116.Dq struct vm_page 1117for this physical address. 1118.It Ic phys 1119Display physical memory. 1120.It Ic pmap 1121Display the pmap. 1122Use the 1123.Dq f 1124modifier to get a fuller listing. 1125.It Ic proc 1126Display some information about the process pointed to, or curproc. 1127.It Ic prom 1128Enter the OFW PROM. 1129.It Ic pv 1130Display the 1131.Dq struct pv_entry 1132pointed to. 1133.It Ic sir 1134Reset the machine and enter prom (do a Software Initiated Reset). 1135.It Ic stack 1136Dump the window stack. 1137Use the 1138.Dq u 1139modifier to get userland information. 1140.It Ic tf 1141Display full trap frame state. 1142This is most useful for inclusion with bug reports. 1143.It Ic ts 1144Display trap state. 1145.It Ic traptrace 1146Display or set trap trace information. 1147Use the 1148.Dq r 1149and 1150.Dq f 1151modifiers to get reversed and full information, respectively. 1152.It Ic watch 1153Set or clear a physical or virtual hardware watchpoint. 1154Pass the address to be watched, or 1155.Dq 0 1156(or omit the address) to clear the watchpoint. 1157Optional modifiers are 1158.Dq p 1159for physical address, 1160.Dq r 1161for trap on read access (default: trap on write access only), 1162.Dq b 1163for 8 bit width, 1164.Dq h 1165for 16 bit, 1166.Dq l 1167for 32 bit or 1168.Dq L 1169for 64 bit. 1170.It Ic window 1171Print register window information. 1172Argument is a stack frame number (0 is 1173top of stack, which is used when no index is given). 1174.El 1175.Ss SUN2, SUN3 and SUN3X 1176.Bl -tag -width "traptrace" -compact 1177.It Ic abort 1178Drop into monitor via abort (allows continue). 1179.It Ic halt 1180Exit to Sun PROM monitor as in 1181.Xr halt 8 . 1182.It Ic reboot 1183Reboot the machine as in 1184.Xr reboot 8 . 1185.It Ic pgmap 1186Given an address, print the address, segment map, page map, and 1187Page Table Entry (PTE). 1188.El 1189.Ss VAX 1190.Bl -tag -width "traptrace" -compact 1191.It Ic cpu 1192Switch to another cpu. 1193.El 1194.Sh VARIABLES 1195.Nm 1196accesses registers and variables as 1197.Cm $ Ns Ar name . 1198Register names are as per the 1199.Ic show registers 1200command. 1201Some variables are suffixed with numbers, and may have a modifier 1202following a colon immediately after the variable name. 1203For example, register variables may have a 1204.Sq u 1205modifier to indicate user register 1206(e.g., 1207.Li "$eax:u" ) . 1208.Pp 1209Built-in variables currently supported are: 1210.Bl -tag -offset indent -width "maxwidth" -compact 1211.It Va lines 1212The number of lines. 1213This is used by the 1214.Ic more 1215feature. 1216When this variable is set to zero the 1217.Ic more 1218feature is disabled. 1219.It Va maxoff 1220Addresses are printed as 1221.Li 'symbol'+offset 1222unless 1223.Li offset 1224is greater than 1225.Va maxoff . 1226.It Va maxwidth 1227The width of the displayed line. 1228.Nm 1229wraps the current line by printing new line when 1230.Va maxwidth 1231column is reached. 1232When this variable is set to zero 1233.Nm 1234doesn't perform any wrapping. 1235.It Va onpanic 1236If greater than zero (the default is 1), 1237.Nm 1238will be invoked when the kernel panics. 1239If the kernel configuration option 1240.D1 Cd options DDB_ONPANIC=0 1241is used, 1242.Va onpanic 1243will be initialized to off, causing a stack trace to be printed and 1244the system to be rebooted instead of 1245.Nm 1246being entered. 1247Other useful settings are \-1, which suppresses the stack trace before 1248reboot, and 2, which causes a stack trace to be printed and 1249.Nm 1250to be entered. 1251.It Va fromconsole 1252If non-zero (the default), 1253the kernel allows to enter 1254.Nm 1255from the console (by break signal or special key sequence). 1256If the kernel configuration option 1257.D1 Cd options DDB_FROMCONSOLE=0 1258is used, 1259.Va fromconsole 1260will be initialized to off. 1261.It Va radix 1262Input and output radix. 1263.It Va tabstops 1264Tab stop width. 1265.It Va tee_msgbuf 1266If explicitly set to non zero (zero is the default) all 1267.Nm 1268output will not only be displayed on screen but 1269also be fed to the msgbuf. 1270The default of the variable can be set using the kernel configuration option 1271.D1 Cd options DDB_TEE_MSGBUF=1 1272which will initialize 1273.Va tee_msgbuf 1274to be 1. 1275This option is especially handy for poor souls 1276who don't have a serial console but want to recall 1277.Nm 1278output from a crash investigation. 1279This option is more generic than the /l command modifier possible for 1280selected commands as discussed above to log the output. 1281Mixing both /l 1282and this setting can give double loggings. 1283.\" .It Va work Ns Sy xx 1284.\" Temporary work variable. 1285.\" .Sq Sy xx 1286.\" is between 0 and 31. 1287.El 1288.Pp 1289All built-in variables are accessible via 1290.Xr sysctl 3 . 1291.Sh EXPRESSIONS 1292Almost all expression operators in C are supported, except 1293.Sq \&~ , 1294.Sq \&^ , 1295and unary 1296.Sq \&\*[Am] . 1297Special rules in 1298.Nm 1299are: 1300.Bl -tag -offset indent -width "identifier" 1301.It Ar identifier 1302name of a symbol. 1303It is translated to the address (or value) of it. 1304.Sq \&. 1305and 1306.Sq \&: 1307can be used in the identifier. 1308If supported by an object format dependent routine, 1309.Sm off 1310.Xo 1311.Oo Ar filename : Oc 1312.Ar function 1313.Oo : Ar line\ number Oc , 1314.Xc 1315.Sm on 1316.Sm off 1317.Xo 1318.Oo Ar filename : Oc 1319.Ar variable , 1320.Xc 1321.Sm on 1322and 1323.Sm off 1324.Xo 1325.Ar filename 1326.Oo : Ar "line number" Oc , 1327.Xc 1328.Sm on 1329can be accepted as a symbol. 1330The symbol may be prefixed with 1331.Ar symbol_table_name\^ : : 1332(e.g., 1333.Li emulator::mach_msg_trap ) 1334to specify other than kernel symbols. 1335.It Ar number 1336number. 1337Radix is determined by the first two characters: 1338.Sq 0x 1339- hex, 1340.Sq 0o 1341- octal, 1342.Sq 0t 1343- decimal, 1344otherwise follow current radix. 1345.It Cm . 1346.Ar dot 1347.It Cm + 1348.Ar next 1349.It Cm .. 1350address of the start of the last line examined. 1351Unlike 1352.Ar dot 1353or 1354.Ar next , 1355this is only changed by the 1356.Ic examine 1357or 1358.Ic write 1359commands. 1360.It Cm \&" \"" XXX: emacs highlighting 1361last address explicitly specified. 1362.It Cm $ Ns Ar name 1363register name or variable. 1364It is translated to the value of it. 1365It may be followed by a 1366.Sq \&: 1367and modifiers as described above. 1368.It Cm # 1369a binary operator which rounds up the left hand side to the next 1370multiple of right hand side. 1371.It Cm * Ns Ar expr 1372expression indirection. 1373It may be followed by a 1374.Sq \&: 1375and modifiers as described above. 1376.El 1377.Sh SEE ALSO 1378.Xr reboot 2 , 1379.Xr options 4 , 1380.Xr crash 8 , 1381.Xr reboot 8 , 1382.Xr sysctl 8 , 1383.Xr cnmagic 9 1384.Sh HISTORY 1385The 1386.Nm 1387kernel debugger was written as part of the MACH project at 1388Carnegie-Mellon University. 1389