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