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