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