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