1.\" $NetBSD: ddb.4,v 1.113 2008/05/02 18:11:05 martin 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 February 18, 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 kvtop 1049Print the physical address for a given kernel virtual address. 1050.It Ic tlb 1051Print out the Translation Lookaside Buffer (TLB). 1052Only works in 1053.Nx 1054kernels compiled with 1055.Dv DEBUG 1056option. 1057.El 1058.Ss SH3 1059.Bl -tag -width "traptrace" -compact 1060.It Ic tlb 1061Print TLB entries 1062.It Ic cache 1063Print cache entries 1064.It Ic frame 1065Print switch frame and trap frames. 1066.It Ic stack 1067Print kernel stack usage. 1068Only works in 1069.Nx 1070kernels compiled with the 1071.Dv KSTACK_DEBUG 1072option. 1073.El 1074.Ss SPARC 1075.Bl -tag -width "traptrace" -compact 1076.It Ic prom 1077Exit to the Sun PROM monitor. 1078.El 1079.Ss SPARC64 1080.Bl -tag -width "traptrace" -compact 1081.It Ic ctx 1082Print process context information. 1083.It Ic cpu 1084Switch to another cpu. 1085.It Ic dtlb 1086Print data translation look-aside buffer context information. 1087.It Ic dtsb 1088Display data translation storage buffer information. 1089.It Ic kmap 1090Display information about the listed mapping in the kernel pmap. 1091Use the 1092.Dq f 1093modifier to get a full listing. 1094.It Ic extract 1095Extract the physical address for a given virtual address from the kernel pmap. 1096.It Ic fpstate 1097Dump the FPU state. 1098.It Ic itlb 1099Print instruction translation look-aside buffer context information. 1100.It Ic itsb 1101Display instruction translation storage buffer information. 1102.It Ic lwp 1103Display a struct lwp 1104.It Ic pcb 1105Display information about the 1106.Dq struct pcb 1107listed. 1108.It Ic pctx 1109Attempt to change process context. 1110.It Ic page 1111Display the pointer to the 1112.Dq struct vm_page 1113for this physical address. 1114.It Ic phys 1115Display physical memory. 1116.It Ic pmap 1117Display the pmap. 1118Use the 1119.Dq f 1120modifier to get a fuller listing. 1121.It Ic proc 1122Display some information about the process pointed to, or curproc. 1123.It Ic prom 1124Enter the OFW PROM. 1125.It Ic pv 1126Display the 1127.Dq struct pv_entry 1128pointed to. 1129.It Ic sir 1130Reset the machine and enter prom (do a Software Initiated Reset). 1131.It Ic stack 1132Dump the window stack. 1133Use the 1134.Dq u 1135modifier to get userland information. 1136.It Ic tf 1137Display full trap frame state. 1138This is most useful for inclusion with bug reports. 1139.It Ic ts 1140Display trap state. 1141.It Ic traptrace 1142Display or set trap trace information. 1143Use the 1144.Dq r 1145and 1146.Dq f 1147modifiers to get reversed and full information, respectively. 1148.It Ic uvmdump 1149Dumps the UVM histories. 1150.It Ic watch 1151Set or clear a physical or virtual hardware watchpoint. 1152Pass the address to be watched, or 1153.Dq 0 1154(or omit the address) to clear the watchpoint. 1155Optional modifiers are 1156.Dq p 1157for physical address, 1158.Dq r 1159for trap on read access (default: trap on write access only), 1160.Dq b 1161for 8 bit width, 1162.Dq h 1163for 16 bit, 1164.Dq l 1165for 32 bit or 1166.Dq L 1167for 64 bit. 1168.It Ic window 1169Print register window information. Argument is a stack frame number (0 is 1170top of stack, which is used when no index is given). 1171.El 1172.Ss SUN3 and SUN3X 1173.Bl -tag -width "traptrace" -compact 1174.It Ic abort 1175Drop into monitor via abort (allows continue). 1176.It Ic halt 1177Exit to Sun PROM monitor as in 1178.Xr halt 8 . 1179.It Ic reboot 1180Reboot the machine as in 1181.Xr reboot 8 . 1182.It Ic pgmap 1183Given an address, print the address, segment map, page map, and 1184Page Table Entry (PTE). 1185.El 1186.Sh VARIABLES 1187.Nm 1188accesses registers and variables as 1189.Cm $ Ns Ar name . 1190Register names are as per the 1191.Ic show registers 1192command. 1193Some variables are suffixed with numbers, and may have a modifier 1194following a colon immediately after the variable name. 1195For example, register variables may have a 1196.Sq u 1197modifier to indicate user register 1198(e.g., 1199.Li "$eax:u" ) . 1200.Pp 1201Built-in variables currently supported are: 1202.Bl -tag -offset indent -width "maxwidth" -compact 1203.It Va lines 1204The number of lines. 1205This is used by the 1206.Ic more 1207feature. 1208When this variable is set to zero the 1209.Ic more 1210feature is disabled. 1211.It Va maxoff 1212Addresses are printed as 1213.Li 'symbol'+offset 1214unless 1215.Li offset 1216is greater than 1217.Va maxoff . 1218.It Va maxwidth 1219The width of the displayed line. 1220.Nm 1221wraps the current line by printing new line when 1222.Va maxwidth 1223column is reached. 1224When this variable is set to zero 1225.Nm 1226doesn't perform any wrapping. 1227.It Va onpanic 1228If non-zero (the default), 1229.Nm 1230will be invoked when the kernel panics. 1231If the kernel configuration option 1232.D1 Cd options DDB_ONPANIC=0 1233is used, 1234.Va onpanic 1235will be initialized to off. 1236.It Va fromconsole 1237If non-zero (the default), 1238the kernel allows to enter 1239.Nm 1240from the console (by break signal or special key sequence). 1241If the kernel configuration option 1242.D1 Cd options DDB_FROMCONSOLE=0 1243is used, 1244.Va fromconsole 1245will be initialized to off. 1246.It Va radix 1247Input and output radix. 1248.It Va tabstops 1249Tab stop width. 1250.It Va tee_msgbuf 1251If explicitly set to non zero (zero is the default) all 1252.Nm 1253output will not only be displayed on screen but 1254also be fed to the msgbuf. 1255The default of the variable can be set using the kernel configuration option 1256.D1 Cd options DDB_TEE_MSGBUF=1 1257which will initialize 1258.Va tee_msgbuf 1259to be 1. 1260This option is especially handy for poor souls 1261who don't have a serial console but want to recall 1262.Nm 1263output from a crash investigation. 1264This option is more generic than the /l command modifier possible for 1265selected commands as discussed above to log the output. 1266Mixing both /l 1267and this setting can give double loggings. 1268.\" .It Va work Ns Sy xx 1269.\" Temporary work variable. 1270.\" .Sq Sy xx 1271.\" is between 0 and 31. 1272.El 1273.Pp 1274All built-in variables are accessible via 1275.Xr sysctl 3 . 1276.Sh EXPRESSIONS 1277Almost all expression operators in C are supported, except 1278.Sq \&~ , 1279.Sq \&^ , 1280and unary 1281.Sq \&\*[Am] . 1282Special rules in 1283.Nm 1284are: 1285.Bl -tag -offset indent -width "identifier" 1286.It Ar identifier 1287name of a symbol. 1288It is translated to the address (or value) of it. 1289.Sq \&. 1290and 1291.Sq \&: 1292can be used in the identifier. 1293If supported by an object format dependent routine, 1294.Sm off 1295.Xo 1296.Oo Ar filename : Oc 1297.Ar function 1298.Oo : Ar line\ number Oc , 1299.Xc 1300.Sm on 1301.Sm off 1302.Xo 1303.Oo Ar filename : Oc 1304.Ar variable , 1305.Xc 1306.Sm on 1307and 1308.Sm off 1309.Xo 1310.Ar filename 1311.Oo : Ar "line number" Oc , 1312.Xc 1313.Sm on 1314can be accepted as a symbol. 1315The symbol may be prefixed with 1316.Ar symbol_table_name\^ : : 1317(e.g., 1318.Li emulator::mach_msg_trap ) 1319to specify other than kernel symbols. 1320.It Ar number 1321number. 1322Radix is determined by the first two characters: 1323.Sq 0x 1324- hex, 1325.Sq 0o 1326- octal, 1327.Sq 0t 1328- decimal, 1329otherwise follow current radix. 1330.It Cm . 1331.Ar dot 1332.It Cm + 1333.Ar next 1334.It Cm .. 1335address of the start of the last line examined. 1336Unlike 1337.Ar dot 1338or 1339.Ar next , 1340this is only changed by the 1341.Ic examine 1342or 1343.Ic write 1344commands. 1345.It Cm \&" \"" XXX: emacs highlighting 1346last address explicitly specified. 1347.It Cm $ Ns Ar name 1348register name or variable. 1349It is translated to the value of it. 1350It may be followed by a 1351.Sq \&: 1352and modifiers as described above. 1353.It Cm # 1354a binary operator which rounds up the left hand side to the next 1355multiple of right hand side. 1356.It Cm * Ns Ar expr 1357expression indirection. 1358It may be followed by a 1359.Sq \&: 1360and modifiers as described above. 1361.El 1362.Sh SEE ALSO 1363.Xr reboot 2 , 1364.Xr options 4 , 1365.Xr reboot 8 , 1366.Xr sysctl 8 , 1367.Xr cnmagic 9 1368.Sh HISTORY 1369The 1370.Nm 1371kernel debugger was written as part of the MACH project at 1372Carnegie-Mellon University. 1373