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