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