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