1.\" $NetBSD: ddb.4,v 1.114 2008/05/23 17:01:32 tsutsui 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 lock 691.Ar address 692.Xc 693Display information about a lock at 694.Ar address . 695This command is useful only if a kernel is compiled with 696.Cd options LOCKDEBUG . 697.It Xo 698.Ic show malloc 699.Ar address 700.Xc 701If 702.Ar address 703is supplied, display the kernel memory allocator's idea on the 704allocation status for it. 705Also, print out global statistics for the memory allocator. 706This command is useful only if a kernel is compiled with 707.Cd options MALLOC_DEBUG . 708.It Xo 709.Ic show map Ns Op Cm /f 710.Ar address 711.Xc 712Print the vm_map at 713.Ar address . 714If 715.Cm /f 716is specified, the complete map is printed. 717.It Xo 718.Ic show mount Ns Op Cm /f 719.Ar address 720.Xc 721Print the mount structure at 722.Ar address . 723If 724.Cm /f 725is specified, the complete vnode list is printed. 726.It Xo 727.Ic show mbuf Ns Op Cm /c 728.Ar address 729.Xc 730Print the mbuf structure at 731.Ar address . 732If 733.Cm /c 734is specified, the mbufs in the chain are followed. 735.It Ic show ncache Ar address 736Dump the namecache list associated with vnode at 737.Ar address . 738.It Xo 739.Ic show object Ns Op Cm /f 740.Ar address 741.Xc 742Print the vm_object at 743.Ar address . 744If 745.Cm /f 746is specified, the complete object is printed. 747.It Xo 748.Ic show page Ns Op Cm /f 749.Ar address 750.Xc 751Print the vm_page at 752.Ar address . 753If 754.Cm /f 755is specified, the complete page is printed. 756.It Xo 757.Ic show pool Ns Op Cm /clp 758.Ar address 759.Xc 760Print the pool at 761.Ar address . 762Valid modifiers: 763.Bl -tag -width 4n -compact 764.It Cm /c 765Print the cachelist and its statistics for this pool. 766.It Cm /l 767Print the log entries for this pool. 768.It Cm /p 769Print the pagelist for this pool. 770.El 771.It Ic show registers Ns Op Cm /u 772Display the register set. 773If 774.Cm /u 775is specified, display user registers instead of kernel registers 776or the currently save one. 777.Pp 778Warning: support for 779.Cm /u 780is machine dependent. 781If not supported, incorrect information will be displayed. 782.It Ic show sched_qs 783Print the state of the scheduler's run queues. 784For each run queue that has an LWP, the run queue index and the list 785of LWPs will be shown. 786If the run queue has LWPs, but the sched_whichqs bit is not set for that 787queue, the queue index will be prefixed with a 788.Sq \&! . 789.It Ic show uvmexp 790Print a selection of UVM counters and statistics. 791.It Xo 792.Ic show vnode Ns Op Cm /f 793.Ar address 794.Xc 795Print the vnode at 796.Ar address . 797If 798.Cm /f 799is specified, the complete vnode is printed. 800.It Ic show watches 801Display all watchpoints. 802.It Xo 803.Ic sifting Ns Op Cm /F 804.Ar string 805.Xc 806Search the symbol tables for all symbols of which 807.Ar string 808is a substring, and display them. 809If 810.Cm /F 811is specified, a character is displayed immediately after each symbol 812name indicating the type of symbol. 813.Pp 814For 815.Xr a.out 5 Ns -format 816symbol tables, 817absolute symbols display 818.Sy @ , 819text segment symbols display 820.Sy * , 821data segment symbols display 822.Sy + , 823.Tn BSS 824segment symbols display 825.Sy - , 826and filename symbols display 827.Sy / . 828For 829.Tn ELF Ns -format 830symbol tables, 831object symbols display 832.Sy + , 833function symbols display 834.Sy * , 835section symbols display 836.Sy \*[Am] , 837and file symbols display 838.Sy / . 839.Pp 840To sift for a string beginning with a number, escape the first 841character with a backslash as: 842.Bd -literal -offset indent 843sifting \\386 844.Ed 845.It Xo 846.Ic step Ns Op Cm /p 847.Op Cm , Ns Ar count 848.Xc 849Single-step 850.Ar count 851times. 852If 853.Cm /p 854is specified, print each instruction at each step. 855Otherwise, only print the last instruction. 856.Pp 857Warning: depending on the machine type, it may not be possible 858to single-step through some low-level code paths or user-space 859code. 860On machines with software-emulated single-stepping (e.g., pmax), 861stepping through code executed by interrupt handlers will probably 862do the wrong thing. 863.It Ic sync 864Force a crash dump, and then reboot. 865.It Xo 866.Ic trace Ns Op Cm /u Ns Op Cm l 867.Sm off 868.Op Ar frame-address 869.Op Cm , Ar count 870.Sm on 871.Xc 872Stack trace from 873.Ar frame-address . 874If 875.Cm /u 876is specified, trace user-space, otherwise trace kernel-space. 877.Ar count 878is the number of frames to be traced. 879If 880.Ar count 881is omitted, all frames are printed. 882If 883.Cm /l 884is specified, the trace is printed and also stored in the kernel 885message buffer. 886.Pp 887Warning: user-space stack trace is valid only if the machine dependent 888code supports it. 889.It Xo 890.Ic trace/t Ns Op Cm l 891.Sm off 892.Op Ar pid 893.Op Cm , Ar count 894.Sm on 895.Xc 896Stack trace by 897.Dq thread 898(process, on 899.Nx ) 900rather than by stack frame address. 901Note that 902.Ar pid 903is interpreted using the current radix, whilst 904.Ic ps 905displays pids in decimal; prefix 906.Ar pid 907with 908.Sq 0t 909to force it to be interpreted as decimal (see 910.Sx VARIABLES 911section for radix). 912If 913.Cm /l 914is specified, the trace is printed and also stored in the kernel 915message buffer. 916.Pp 917Warning: trace by pid is valid only if the machine dependent code 918supports it. 919.It Xo 920.Ic trace/a Ns Op Cm l 921.Sm off 922.Op Ar lwpaddr 923.Op Cm , Ar count 924.Sm on 925.Xc 926Stack trace by light weight process (LWP) address 927rather than by stack frame address. 928If 929.Cm /l 930is specified, the trace is printed and also stored in the kernel 931message buffer. 932.Pp 933Warning: trace by LWP address is valid only if the machine dependent 934code supports it. 935.It Ic until Ns Op Cm /p 936Stop at the next call or return instruction. 937If 938.Cm /p 939is specified, print the call nesting depth and the 940cumulative instruction count at each call or return. 941Otherwise, only print when the matching return is hit. 942.It Xo 943.Ic watch 944.Sm off 945.Ar address 946.Op Cm , Ar size 947.Sm on 948.Xc 949Set a watchpoint for a region. 950Execution stops when an attempt to modify the region occurs. 951.Ar size 952defaults to 4. 953.Pp 954If you specify a wrong space address, the request is 955rejected with an error message. 956.Pp 957Warning: attempts to watch wired kernel memory may cause 958an unrecoverable error in some systems such as i386. 959Watchpoints on user addresses work the best. 960.It Xo 961.Ic whatis 962.Sm off 963.Ar address 964.Sm on 965.Xc 966Describe what an address is. 967.It Xo 968.Ic write Ns Op Cm /bhl 969.Ar address 970.Ar expression Op Ar expression ... 971.Xc 972Write the 973.Ar expression Ns s 974at succeeding locations. 975The unit size is specified with a modifier character, as per 976.Ic examine . 977Valid modifiers are: 978.Cm /b , 979.Cm /h , 980and 981.Cm /l . 982If no modifier is specified, 983.Cm /l 984is used. 985.Pp 986Warning: since there is no delimiter between 987.Ar expression Ns s , 988strange things may occur. 989It's best to enclose each 990.Ar expression 991in parentheses. 992.It Xo 993.Ic x Ns Op Cm / Ns Ar modifier 994.Ar address Ns Op Cm , Ns Ar count 995.Xc 996A synonym for 997.Ic examine . 998.\" XXX - these commands aren't implemented; jhawk 19 May 2000 999.\" .It Ic xf 1000.\" Examine forward. 1001.\" .Ic xf 1002.\" re-executes the most recent 1003.\" .Ic execute 1004.\" command with the same parameters except that 1005.\" .Ar address 1006.\" is set to 1007.\" .Ar next . 1008.\" .It Ic xb 1009.\" Examine backward. 1010.\" .Ic xb 1011.\" re-executes the most recent 1012.\" .Ic execute 1013.\" command with the same parameters, except that 1014.\" .Ar address 1015.\" is set to the last start address minus its size. 1016.El 1017.Sh MACHINE-SPECIFIC COMMANDS 1018The "glue" code that hooks 1019.Nm 1020into the 1021.Nx 1022kernel for any given port can also add machine specific commands 1023to the 1024.Nm 1025command parser. 1026All of these commands are preceded by the command word 1027.Em machine 1028to indicate that they are part of the machine-specific command 1029set (e.g. 1030.Ic machine reboot ) . 1031Some of these commands are: 1032.Ss ALPHA 1033.Bl -tag -width "traptrace" -compact 1034.It Ic halt 1035Call the PROM monitor to halt the CPU. 1036.It Ic reboot 1037Call the PROM monitor to reboot the CPU. 1038.El 1039.Ss ARM32 1040.Bl -tag -width "traptrace" -compact 1041.It Ic panic 1042Print the current "panic" string. 1043.It Ic frame 1044Given a trap frame address, print out the trap frame. 1045.El 1046.Ss MIPS 1047.Bl -tag -width "traptrace" -compact 1048.It Ic cp0 1049Dump CP0 (coprocessor 0) register values. 1050.It Ic kvtop 1051Print the physical address for a given kernel virtual address. 1052.It Ic tlb 1053Print out the Translation Lookaside Buffer (TLB). 1054Only works in 1055.Nx 1056kernels compiled with 1057.Dv DEBUG 1058option. 1059.El 1060.Ss SH3 1061.Bl -tag -width "traptrace" -compact 1062.It Ic tlb 1063Print TLB entries 1064.It Ic cache 1065Print cache entries 1066.It Ic frame 1067Print switch frame and trap frames. 1068.It Ic stack 1069Print kernel stack usage. 1070Only works in 1071.Nx 1072kernels compiled with the 1073.Dv KSTACK_DEBUG 1074option. 1075.El 1076.Ss SPARC 1077.Bl -tag -width "traptrace" -compact 1078.It Ic prom 1079Exit to the Sun PROM monitor. 1080.El 1081.Ss SPARC64 1082.Bl -tag -width "traptrace" -compact 1083.It Ic ctx 1084Print process context information. 1085.It Ic cpu 1086Switch to another cpu. 1087.It Ic dtlb 1088Print data translation look-aside buffer context information. 1089.It Ic dtsb 1090Display data translation storage buffer information. 1091.It Ic kmap 1092Display information about the listed mapping in the kernel pmap. 1093Use the 1094.Dq f 1095modifier to get a full listing. 1096.It Ic extract 1097Extract the physical address for a given virtual address from the kernel pmap. 1098.It Ic fpstate 1099Dump the FPU state. 1100.It Ic itlb 1101Print instruction translation look-aside buffer context information. 1102.It Ic itsb 1103Display instruction translation storage buffer information. 1104.It Ic lwp 1105Display a struct lwp 1106.It Ic pcb 1107Display information about the 1108.Dq struct pcb 1109listed. 1110.It Ic pctx 1111Attempt to change process context. 1112.It Ic page 1113Display the pointer to the 1114.Dq struct vm_page 1115for this physical address. 1116.It Ic phys 1117Display physical memory. 1118.It Ic pmap 1119Display the pmap. 1120Use the 1121.Dq f 1122modifier to get a fuller listing. 1123.It Ic proc 1124Display some information about the process pointed to, or curproc. 1125.It Ic prom 1126Enter the OFW PROM. 1127.It Ic pv 1128Display the 1129.Dq struct pv_entry 1130pointed to. 1131.It Ic sir 1132Reset the machine and enter prom (do a Software Initiated Reset). 1133.It Ic stack 1134Dump the window stack. 1135Use the 1136.Dq u 1137modifier to get userland information. 1138.It Ic tf 1139Display full trap frame state. 1140This is most useful for inclusion with bug reports. 1141.It Ic ts 1142Display trap state. 1143.It Ic traptrace 1144Display or set trap trace information. 1145Use the 1146.Dq r 1147and 1148.Dq f 1149modifiers to get reversed and full information, respectively. 1150.It Ic uvmdump 1151Dumps the UVM histories. 1152.It Ic watch 1153Set or clear a physical or virtual hardware watchpoint. 1154Pass the address to be watched, or 1155.Dq 0 1156(or omit the address) to clear the watchpoint. 1157Optional modifiers are 1158.Dq p 1159for physical address, 1160.Dq r 1161for trap on read access (default: trap on write access only), 1162.Dq b 1163for 8 bit width, 1164.Dq h 1165for 16 bit, 1166.Dq l 1167for 32 bit or 1168.Dq L 1169for 64 bit. 1170.It Ic window 1171Print register window information. Argument is a stack frame number (0 is 1172top of stack, which is used when no index is given). 1173.El 1174.Ss SUN3 and SUN3X 1175.Bl -tag -width "traptrace" -compact 1176.It Ic abort 1177Drop into monitor via abort (allows continue). 1178.It Ic halt 1179Exit to Sun PROM monitor as in 1180.Xr halt 8 . 1181.It Ic reboot 1182Reboot the machine as in 1183.Xr reboot 8 . 1184.It Ic pgmap 1185Given an address, print the address, segment map, page map, and 1186Page Table Entry (PTE). 1187.El 1188.Sh VARIABLES 1189.Nm 1190accesses registers and variables as 1191.Cm $ Ns Ar name . 1192Register names are as per the 1193.Ic show registers 1194command. 1195Some variables are suffixed with numbers, and may have a modifier 1196following a colon immediately after the variable name. 1197For example, register variables may have a 1198.Sq u 1199modifier to indicate user register 1200(e.g., 1201.Li "$eax:u" ) . 1202.Pp 1203Built-in variables currently supported are: 1204.Bl -tag -offset indent -width "maxwidth" -compact 1205.It Va lines 1206The number of lines. 1207This is used by the 1208.Ic more 1209feature. 1210When this variable is set to zero the 1211.Ic more 1212feature is disabled. 1213.It Va maxoff 1214Addresses are printed as 1215.Li 'symbol'+offset 1216unless 1217.Li offset 1218is greater than 1219.Va maxoff . 1220.It Va maxwidth 1221The width of the displayed line. 1222.Nm 1223wraps the current line by printing new line when 1224.Va maxwidth 1225column is reached. 1226When this variable is set to zero 1227.Nm 1228doesn't perform any wrapping. 1229.It Va onpanic 1230If non-zero (the default), 1231.Nm 1232will be invoked when the kernel panics. 1233If the kernel configuration option 1234.D1 Cd options DDB_ONPANIC=0 1235is used, 1236.Va onpanic 1237will be initialized to off. 1238.It Va fromconsole 1239If non-zero (the default), 1240the kernel allows to enter 1241.Nm 1242from the console (by break signal or special key sequence). 1243If the kernel configuration option 1244.D1 Cd options DDB_FROMCONSOLE=0 1245is used, 1246.Va fromconsole 1247will be initialized to off. 1248.It Va radix 1249Input and output radix. 1250.It Va tabstops 1251Tab stop width. 1252.It Va tee_msgbuf 1253If explicitly set to non zero (zero is the default) all 1254.Nm 1255output will not only be displayed on screen but 1256also be fed to the msgbuf. 1257The default of the variable can be set using the kernel configuration option 1258.D1 Cd options DDB_TEE_MSGBUF=1 1259which will initialize 1260.Va tee_msgbuf 1261to be 1. 1262This option is especially handy for poor souls 1263who don't have a serial console but want to recall 1264.Nm 1265output from a crash investigation. 1266This option is more generic than the /l command modifier possible for 1267selected commands as discussed above to log the output. 1268Mixing both /l 1269and this setting can give double loggings. 1270.\" .It Va work Ns Sy xx 1271.\" Temporary work variable. 1272.\" .Sq Sy xx 1273.\" is between 0 and 31. 1274.El 1275.Pp 1276All built-in variables are accessible via 1277.Xr sysctl 3 . 1278.Sh EXPRESSIONS 1279Almost all expression operators in C are supported, except 1280.Sq \&~ , 1281.Sq \&^ , 1282and unary 1283.Sq \&\*[Am] . 1284Special rules in 1285.Nm 1286are: 1287.Bl -tag -offset indent -width "identifier" 1288.It Ar identifier 1289name of a symbol. 1290It is translated to the address (or value) of it. 1291.Sq \&. 1292and 1293.Sq \&: 1294can be used in the identifier. 1295If supported by an object format dependent routine, 1296.Sm off 1297.Xo 1298.Oo Ar filename : Oc 1299.Ar function 1300.Oo : Ar line\ number Oc , 1301.Xc 1302.Sm on 1303.Sm off 1304.Xo 1305.Oo Ar filename : Oc 1306.Ar variable , 1307.Xc 1308.Sm on 1309and 1310.Sm off 1311.Xo 1312.Ar filename 1313.Oo : Ar "line number" Oc , 1314.Xc 1315.Sm on 1316can be accepted as a symbol. 1317The symbol may be prefixed with 1318.Ar symbol_table_name\^ : : 1319(e.g., 1320.Li emulator::mach_msg_trap ) 1321to specify other than kernel symbols. 1322.It Ar number 1323number. 1324Radix is determined by the first two characters: 1325.Sq 0x 1326- hex, 1327.Sq 0o 1328- octal, 1329.Sq 0t 1330- decimal, 1331otherwise follow current radix. 1332.It Cm . 1333.Ar dot 1334.It Cm + 1335.Ar next 1336.It Cm .. 1337address of the start of the last line examined. 1338Unlike 1339.Ar dot 1340or 1341.Ar next , 1342this is only changed by the 1343.Ic examine 1344or 1345.Ic write 1346commands. 1347.It Cm \&" \"" XXX: emacs highlighting 1348last address explicitly specified. 1349.It Cm $ Ns Ar name 1350register name or variable. 1351It is translated to the value of it. 1352It may be followed by a 1353.Sq \&: 1354and modifiers as described above. 1355.It Cm # 1356a binary operator which rounds up the left hand side to the next 1357multiple of right hand side. 1358.It Cm * Ns Ar expr 1359expression indirection. 1360It may be followed by a 1361.Sq \&: 1362and modifiers as described above. 1363.El 1364.Sh SEE ALSO 1365.Xr reboot 2 , 1366.Xr options 4 , 1367.Xr reboot 8 , 1368.Xr sysctl 8 , 1369.Xr cnmagic 9 1370.Sh HISTORY 1371The 1372.Nm 1373kernel debugger was written as part of the MACH project at 1374Carnegie-Mellon University. 1375