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