1.\" $NetBSD: ddb.4,v 1.204 2024/06/29 06:39:34 rin 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 June 29, 2024 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> followed by <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 m68k 455use Motorola syntax 456.It vax 457don't assume that each external label is a procedure entry mask 458.El 459.El 460.It Ic kill Ar pid Ns Op , Ns Ar signal_number 461Send a signal to the process specified by the 462.Ar pid . 463Note that 464.Ar pid 465is interpreted using the current radix (see 466.Cm trace/t 467command for details). 468If 469.Ar signal_number 470isn't specified, the SIGTERM signal is sent. 471.It Ic match Ns Op Cm /p 472A synonym for 473.Ic next . 474.It Ic next Ns Op Cm /p 475Stop at the matching return instruction. 476If 477.Cm /p 478is specified, print the call nesting depth and the 479cumulative instruction count at each call or return. 480Otherwise, only print when the matching return is hit. 481.It Ic print Ns Oo Cm /axzodurc Oc Ar address Op Ar address ... 482Print addresses 483.Ar address 484according to the modifier character, as per 485.Ic examine . 486Valid modifiers are: 487.Cm /a , 488.Cm /x , 489.Cm /z , 490.Cm /o , 491.Cm /d , 492.Cm /u , 493.Cm /r , 494and 495.Cm /c 496(as per 497.Ic examine ) . 498If no modifier is specified, the most recent one specified is used. 499.Ar address 500may be a string, and is printed 501.Dq as-is . 502For example: 503.Bd -literal -offset indent 504print/x "eax = " $eax "\enecx = " $ecx "\en" 505.Ed 506.Pp 507will produce: 508.Bd -literal -offset indent 509eax = xxxxxx 510ecx = yyyyyy 511.Ed 512.It Ic ps Ns Oo Cm /a Oc Ns Oo Cm /n Oc Ns Oo Cm /w Oc Ns Oo Cm /l Oc 513A synonym for 514.Ic show all procs . 515.It Ic reboot Op Ar flags 516Reboot, using the optionally supplied boot 517.Ar flags , 518which is a bitmask supporting the same values as for 519.Xr reboot 2 . 520Some of the more useful flags: 521.Bl -column "Value" "RB_POWERDOWN" "Description" 522.It Sy "Value" Ta Sy "Name" Ta Sy "Description" 523.It 0x1 Ta RB_ASKNAME Ta Ask for file name to reboot from 524.It 0x2 Ta RB_SINGLE Ta Reboot to single user mode 525.It 0x4 Ta RB_NOSYNC Ta Don't sync before reboot 526.It 0x8 Ta RB_HALT Ta Halt instead of reboot 527.It 0x40 Ta RB_KDB Ta Boot into kernel debugger 528.It 0x100 Ta RB_DUMP Ta Dump unconditionally before reboot 529.It 0x808 Ta RB_POWERDOWN Ta Power off (or at least halt) 530.El 531.Pp 532Note: Limitations of the command line interface preclude 533specification of a boot string. 534.It Ic search Ns Oo Cm /bhl Oc Ar address Ar value \ 535Oo Ar mask Oc Oo , Ns Ar count Oc 536Search memory from 537.Ar address 538for 539.Ar value . 540The unit size is specified with a modifier character, as per 541.Ic examine . 542Valid modifiers are: 543.Cm /b , 544.Cm /h , 545and 546.Cm /l . 547If no modifier is specified, 548.Cm /l 549is used. 550.Pp 551This command might fail in interesting ways if it doesn't find 552.Ar value . 553This is because 554.Nm 555doesn't always recover from touching bad memory. 556The optional 557.Ar count 558limits the search. 559.It Ic set Cm $ Ns Ar variable Oo Cm = Oc Ar expression 560Set the named variable or register to the value of 561.Ar expression . 562Valid variable names are described in 563.Sx VARIABLES . 564.It Ic show all callout 565Display information about callouts in the system. 566See 567.Xr callout 9 568for more information on callouts. 569.It Ic show all locks Ns Op Cm /t 570Display details information about all active locks. 571If 572.Cm /t 573is specified, stack traces of LWPs holding locks are also printed. 574This command is only useful if a kernel is compiled with 575.Cd options LOCKDEBUG . 576.It Ic show all mount Ns Op Cm /f 577Display all mount points. 578If 579.Cm /f 580is specified, the complete vnode list is printed. 581.It Ic show all pages 582Display basic information about all physical pages managed by the VM system. 583For more detailed information about a single page, use 584.Ic show page . 585.It Ic show all pools Ns Op Cm /clpsS 586Display all pool information. 587Modifiers are the same as 588.Ic show pool . 589.It Ic "show\ all\ procs" Ns Oo Cm /a Oc Ns Oo Cm /n Oc Ns Oo Cm /w Oc Ns \ 590Oo Cm /l Oc 591Display all process information. 592Valid modifiers: 593.Bl -tag -width 3n 594.It Cm /n 595show process information in a 596.Xr ps 1 597style format. 598Information printed includes: process ID, parent process ID, 599process group, UID, process status, process flags, number of LWPs, 600command name, and process wait channel message. 601.It Cm /a 602show each process ID, command name, kernel virtual addresses of 603each process' proc structure, u-area, and vmspace structure. 604The vmspace address is also the address of the process' 605vm_map structure, and can be used in the 606.Ic show map 607command. 608.It Cm /w 609show each LWP ID, process ID, command name, system call emulation, 610priority, wait channel message and wait channel address. 611LWPs currently running on a CPU are marked with the '\&>' sign. 612.It Cm /l 613show each LWP ID, process ID, process status, CPU ID the LWP runs on, 614process flags, kernel virtual address of LWP structure, 615LWP name and wait channel message. 616LWPs currently running on a CPU are marked with the '\&>' sign. 617This is the default. 618.El 619.It Ic show all tstiles Ns Oo Cm /t Oc 620Display all lwps that are currently waiting in turnstiles to acquire 621locks, which locks they are waiting for, and who currently holds them. 622Valid modifiers: 623.Bl -tag -width 3n 624.It Cm /t 625show a stack trace of the lwp that currently holds each lock 626.El 627.It Ic show routes 628Dump the entire 629.Dv AF_INET 630routing table. 631This command is available only on systems which support inet. 632.It Ic show breaks 633Display all breakpoints. 634.It Ic show buf Ns Oo Cm /f Oc Ar address 635Print the struct buf at 636.Ar address . 637The 638.Cm /f 639does nothing at this time. 640.It Ic show event Ns Oo Cm /f Oc Ns Oo Cm /i Oc Ns Oo Cm /m Oc Ns \ 641Oo Cm /t Oc 642Print all the non-zero 643.Xr evcnt 9 644event counters. 645Valid modifiers: 646.Bl -tag -width 3n 647.It Cm /f 648event counters with a count of zero are printed as well. 649.It Cm /i 650interrupted counters will be displayed. 651.It Cm /m 652misc counters will be displayed. 653.It Cm /t 654trap counters will be displayed. 655.El 656.Pp 657If none of 658.Cm /i , 659.Cm /m , 660or 661.Cm /t 662are specified, all are shown. 663You can combine any of these. 664For example, the modifier 665.Cm /itf 666will select both interrupt and trap events, including those that are non-zero. 667.It Ic show files Ar address 668Display information about the vnodes of the files that are currently 669open by the process associated with the proc structure at 670.Ar address . 671This address can be found using the 672.Ic show all procs /a 673command. 674If the kernel is compiled with 675.Cd options LOCKDEBUG 676then details about the locking of the underlying uvm object will also 677be displayed. 678.It Ic show lock Ar address 679Display information about a lock at 680.Ar address . 681This command is only useful if a kernel is compiled with 682.Cd options LOCKDEBUG . 683.It Ic show lockstats 684Display information about lock statistics. 685This command is only useful if a kernel is compiled with 686.Cd options LOCKDEBUG . 687.It Ic show map Ns Oo Cm /f Oc Ar address 688Print the vm_map at 689.Ar address . 690If 691.Cm /f 692is specified, the complete map is printed. 693.It Ic show mount Ns Oo Cm /f Oc Ar address 694Print the mount structure at 695.Ar address . 696If 697.Cm /f 698is specified, the complete vnode list is printed. 699.It Ic show mbuf Ns Oo Cm /cdv Oc Ar address 700Print the mbuf structure at 701.Ar address . 702Valid modifiers: 703.Bl -tag -width 4n -compact 704.It Cm /c 705The mbufs in the chain are NOT followed. 706.It Cm /d 707The data is dumped. 708.It Cm /v 709Decode the mbuf chain as a packet. 710It currently supports Ethernet, PPP, PPPoE, ARP, IPv4, ICMP, IPv6, ICMP6, TCP 711and UDP. 712.El 713.It Ic show ncache Ar address 714Dump the namecache list associated with vnode at 715.Ar address . 716.It Ic show object Ns Oo Cm /f Oc Ar address 717Print the vm_object at 718.Ar address . 719If 720.Cm /f 721is specified, the complete object is printed. 722.It Ic show page Ns Oo Cm /f Oc Ar address 723Print the vm_page at 724.Ar address . 725If 726.Cm /f 727is specified, the complete page is printed. 728.It Ic show panic 729Print the current "panic" string. 730.It Ic show pool Ns Oo Cm /clpsS Oc Ar address 731Print the pool at 732.Ar address . 733Valid modifiers: 734.Bl -tag -width 4n -compact 735.It Cm /c 736Print the cachelist and its statistics for this pool. 737.It Cm /l 738Print the log entries for this pool. 739.It Cm /p 740Print the pagelist for this pool. 741.It Cm /s 742Print a short (one line) list per pool, showing the wait channel, pool 743address, allocation size, alignment, allocated pages, allocated items, 744consumed items, allocation requests, allocation frees, pages allocated, 745pages freed, and currently idle pages, respectively. 746.It Cm /S 747Skip pools with zero allocations. 748.El 749.It Ic show proc Ns Oo Cm /ap Oc Ar address | pid 750Show information about a process and its LWPs. 751LWPs currently running on a CPU are marked with the '\&>' sign. 752.Bl -tag -width 4n -compact 753.It Cm /a 754The argument passed is the kernel virtual address 755of LWP structure. 756.It Cm /p 757The argument passed is a PID. 758Note that 759.Ar pid 760is interpreted using the current radix (see 761.Cm trace/t 762command for details). 763This is the default. 764.El 765.It Ic show registers Ns Op Cm /u 766Display the register set. 767If 768.Cm /u 769is specified, display user registers instead of kernel registers 770or the currently save one. 771.Pp 772Warning: support for 773.Cm /u 774is machine dependent. 775If not supported, incorrect information will be displayed. 776.It Ic show sched_qs 777Print the state of the scheduler's run queues. 778For each run queue that has an LWP, the run queue index and the list 779of LWPs will be shown. 780If the run queue has LWPs, but the sched_whichqs bit is not set for that 781queue, the queue index will be prefixed with a 782.Sq \&! . 783.It Ic show socket Ns Oo Cm /ampv Oc 784Print usage of system's socket buffers. 785By default, empty sockets aren't printed. 786.Bl -tag -width 4n -compact 787.It Cm /a 788Print all processes which use the socket. 789.It Cm /m 790Print mbuf chain in the socket buffer. 791.It Cm /p 792By default, a process which uses the socket is printed (only one socket). 793If 794.Cm /p 795is specified, the process isn't printed. 796.It Cm /v 797Verbose mode. 798If 799.Cm /v 800is specified, all sockets are printed. 801.El 802.It Ic show uvmexp 803Print a selection of UVM counters and statistics. 804.It Ic show kernhist Ns Oo Cm /i Oc Oo Ar addr Ns Oo , Ns Ar count Oc Oc 805Dumps all the kernel histories if no address is specified, or the history 806at the address. 807If 808.Cm /i 809is specified, display information about the named history or all histories, 810instead of history entries. 811If 812.Ar count 813is specified, only the last 814.Ar count 815entries will be displayed. 816Currently the 817.Ar count 818handling is only performed if a single history is requested. 819This command is available only if a kernel is compiled with one or more 820of the kernel history options 821.Cd KERNHIST , 822.Cd SYSCALL_DEBUG , 823.Cd USB_DEBUG , 824.Cd BIOHIST , 825or 826.Cd UVMHIST . 827.It Ic show vmem Ar address 828Print the vmem at 829.Ar address . 830.It Ic show vmems 831Display all vmems. 832.It Ic show vnode Ns Oo Cm /f Oc Ar address 833Print the vnode at 834.Ar address . 835If 836.Cm /f 837is specified, the complete vnode is printed. 838.It Ic show vnode_lock Ns Oo Cm /f Oc Ar address 839Print the vnode which has its lock at 840.Ar address . 841If 842.Cm /f 843is specified, the complete vnode is printed. 844.It Ic show watches 845Display all watchpoints. 846.It Ic sifting Ns Oo Cm /F Oc Ar string 847Search the symbol tables for all symbols of which 848.Ar string 849is a substring, and display them. 850If 851.Cm /F 852is specified, a character is displayed immediately after each symbol 853name indicating the type of symbol. 854.Pp 855Object symbols display 856.Sy + , 857function symbols display 858.Sy * , 859section symbols display 860.Sy & , 861and file symbols display 862.Sy / . 863.Pp 864To sift for a string beginning with a number, escape the first 865character with a backslash as: 866.Bd -literal -offset indent 867sifting \\386 868.Ed 869.It Ic step Ns Oo Cm /p Oc Op , Ns Ar count 870Single-step 871.Ar count 872times. 873If 874.Cm /p 875is specified, print each instruction at each step. 876Otherwise, only print the last instruction. 877.Pp 878Warning: depending on the machine type, it may not be possible 879to single-step through some low-level code paths or user-space 880code. 881On machines with software-emulated single-stepping (e.g., pmax), 882stepping through code executed by interrupt handlers will probably 883do the wrong thing. 884.It Ic sync 885Sync the disks, force a crash dump, and then reboot. 886.It Ic trace Ns Oo Cm /u Ns Oo Cm l Oc Oc Oo Ar frame-address Oc Ns \ 887Oo , Ns Ar count Oc 888Stack trace from 889.Ar frame-address . 890If 891.Cm /u 892is specified, trace user-space, otherwise trace kernel-space. 893.Ar count 894is the number of frames to be traced. 895If 896.Ar count 897is omitted, all frames are printed. 898If 899.Cm /l 900is specified, the trace is printed and also stored in the kernel 901message buffer. 902.Pp 903Warning: user-space stack trace is valid only if the machine dependent 904code supports it. 905.It Ic trace/t Ns Oo Cm l Oc Oo Ar pid Oc Ns Oo , Ns Ar count Oc 906Stack trace by 907.Dq thread 908(process, on 909.Nx ) 910rather than by stack frame address. 911Note that 912.Ar pid 913is interpreted using the current radix, whilst 914.Ic ps 915displays pids in decimal; prefix 916.Ar pid 917with 918.Sq 0t 919to force it to be interpreted as decimal (see 920.Sx VARIABLES 921section for radix). 922If 923.Cm /l 924is specified, the trace is printed and also stored in the kernel 925message buffer. 926.Pp 927Warning: trace by pid is valid only if the machine dependent code 928supports it. 929.It Ic trace/a Ns Oo Cm l Oc Oo Ar lwpaddr Oc Ns Oo , Ns Ar count Oc 930Stack trace by light weight process (LWP) address 931rather than by stack frame address. 932If 933.Cm /l 934is specified, the trace is printed and also stored in the kernel 935message buffer. 936.Pp 937Warning: trace by LWP address is valid only if the machine dependent 938code supports it. 939.It Ic until Ns Op Cm /p 940Stop at the next call or return instruction. 941If 942.Cm /p 943is specified, print the call nesting depth and the 944cumulative instruction count at each call or return. 945Otherwise, only print when the matching return is hit. 946.It Ic watch Ar address Ns Oo , Ns Ar size Oc 947Set a watchpoint for a region. 948Execution stops when an attempt to modify the region occurs. 949.Ar size 950defaults to 4. 951.Pp 952If you specify a wrong space address, the request is 953rejected with an error message. 954.Pp 955Warning: attempts to watch wired kernel memory may cause 956an unrecoverable error in some systems such as i386. 957Watchpoints on user addresses work the best. 958.It Ic whatis Ar address 959Describe what an address is. 960.It Ic write Ns Oo Cm /bhlqBHLQ Oc Ar address Ar expression Oo Ar expression ... Oc 961Write the 962.Ar expression Ns s 963at succeeding locations. 964The unit size is specified with a modifier character, as per 965.Ic examine . 966Valid modifiers are: 967.Cm /b , 968.Cm /h , 969.Cm /l , 970and 971.Cm /q . 972If no modifier is specified, 973.Cm /l 974is used. 975.Pp 976Specifying the modifiers in upper case, 977.Cm /B , 978.Cm /H , 979.Cm /L , 980.Cm /Q , 981will prevent 982.Nm 983from reading the memory location first, which is useful for avoiding 984side effects when writing to I/O memory regions. 985.Pp 986Warning: since there is no delimiter between 987.Ar expression Ns s , 988strange things may occur. 989It's best to enclose each 990.Ar expression 991in parentheses. 992.It Ic x Ns Oo Cm / Ns Ar modifier Oc Ar address Ns Op , Ns Ar count 993A synonym for 994.Ic examine . 995.\" XXX - these commands aren't implemented; jhawk 19 May 2000 996.\" .It Ic xf 997.\" Examine forward. 998.\" .Ic xf 999.\" re-executes the most recent 1000.\" .Ic execute 1001.\" command with the same parameters except that 1002.\" .Ar address 1003.\" is set to 1004.\" .Ar next . 1005.\" .It Ic xb 1006.\" Examine backward. 1007.\" .Ic xb 1008.\" re-executes the most recent 1009.\" .Ic execute 1010.\" command with the same parameters, except that 1011.\" .Ar address 1012.\" is set to the last start address minus its size. 1013.El 1014.Sh MACHINE-SPECIFIC COMMANDS 1015The "glue" code that hooks 1016.Nm 1017into the 1018.Nx 1019kernel for any given port can also add machine specific commands 1020to the 1021.Nm 1022command parser. 1023All of these commands are preceded by the command word 1024.Em machine 1025to indicate that they are part of the machine-specific command 1026set (e.g. 1027.Ic machine reboot ) . 1028Some of these commands are: 1029.Ss AARCH64 1030.Bl -tag -width "traptrace" -compact 1031.It Ic break 1032Set or clear a hardware breakpoint. 1033.It Ic cpu 1034Switch to another CPU. 1035.It Ic cpuinfo 1036Print CPU information about the ``struct cpuinfo''. 1037.It Ic frame 1038Given a trap frame address, print out the trap frame. 1039.It Ic lwp 1040Print lwp information about the ``struct lwp''. 1041.It Ic pte 1042Print PTE information. 1043.It Ic reset 1044Reset the system. 1045.It Ic sysreg 1046Print system registers. 1047.It Ic watch 1048Set or clear a hardware watchpoint. 1049Pass the address to be watched, or watchpoint number to clear the watchpoint. 1050Optional modifiers are 1051.Dq r 1052for read access, 1053.Dq w 1054for write access (default: trap on read or write access), 1055.Dq b 1056for 8 bit width, 1057.Dq h 1058for 16 bit, 1059.Dq l 1060for 32 bit or, 1061.Dq q 1062for 64 bit (default: 32 bit). 1063.El 1064.Ss ALPHA 1065.Bl -tag -width "traptrace" -compact 1066.It Ic cpu 1067Switch to another CPU. 1068.\" .It Ic halt 1069.\" Call the PROM monitor to halt the CPU. 1070.\" .It Ic reboot 1071.\" Call the PROM monitor to reboot the CPU. 1072.El 1073.Ss AMD64 1074.Bl -tag -width "traptrace" -compact 1075.It Ic cpu 1076Switch to another CPU. 1077.El 1078.Ss ARM32 1079.Bl -tag -width "traptrace" -compact 1080.It Ic frame 1081Given a trap frame address, print out the trap frame. 1082.It Ic reset 1083Reset the system. 1084.El 1085.Ss HPPA 1086.Bl -tag -width "traptrace" -compact 1087.It Ic frame 1088Without an address the default trap frame is printed. 1089Otherwise, the trap frame address can be given, or, when the 1090.Dq l 1091modifier is used, an LWP address. 1092.El 1093.Ss I386 1094.Bl -tag -width "traptrace" -compact 1095.It Ic cpu 1096Switch to another CPU. 1097.El 1098.Ss IA64 1099.Bl -tag -width "traptrace" -compact 1100.It Ic vector 1101Without a vector, information about all 256 vectors is shown. 1102Otherwise, the given vector is shown. 1103.El 1104.Ss MIPS 1105.Bl -tag -width "traptrace" -compact 1106.It Ic cp0 1107Dump CP0 (coprocessor 0) register values. 1108.It Ic cpu 1109Switch to another CPU. 1110.It Ic kvtop 1111Print the physical address for a given kernel virtual address. 1112.\" .It Ic mfcr -- document this! 1113.\" .It Ic mtcr -- document this! 1114.It Ic nmi 1115Send an NMI to a different CPU. 1116This DDB command is currently only implemented for Cavium 1117Octeon CPUs. 1118.It Ic reset 1119Reset the system. 1120Not implemented for many CPUs and/or systems. 1121.It Ic tlb 1122Print out the Translation Lookaside Buffer (TLB). 1123Use the 1124.Cm /v 1125modifier to show only valid TLB entries. 1126.It Ic watch 1127Set a hardware watchpoint on an address or a TLB ASID. 1128Pass the address to be watched. 1129If no address is specified, show a list of active watchpoints. 1130The modifiers are 1131.Cm /m 1132i for trap on an instruction fetch, 1133.Cm /r 1134for trap on a read, 1135.Cm /w 1136for trap on a write, 1137.Cm /m 1138for a mask on the address to match, 1139.Cm /a 1140for trap on a TLB ASID match. 1141The 1142.Cm /m 1143and 1144.Cm /a 1145modifiers require an extra argument for the mask and ASID respectively. 1146.It Ic unwatch 1147Clear a hardware watchpoint. 1148If an address is specified, clear watchpoints that match that address. 1149If no address is specified, clear all watchpoints. 1150.El 1151.Ss POWERPC 4xx 1152.Bl -tag -width "traptrace" -compact 1153.It Ic ctx 1154Print process MMU context information. 1155.It Ic pv 1156Print PA->VA mapping information. 1157.It Ic reset 1158Reset the system. 1159.It Ic tf 1160Display the contents of the trapframe. 1161.It Ic tlb 1162Display instruction translation storage buffer information. 1163.It Ic dcr 1164Set the DCR register. 1165Must be between 0x00 and 0x3ff. 1166.It Ic user 1167Display user memory. 1168Use the 1169.Dq i 1170modifier to get instruction decoding. 1171.El 1172.Ss POWERPC OEA 1173.Bl -tag -width "traptrace" -compact 1174.It Ic bat 1175Print BAT registers and translations. 1176.It Ic mmu 1177Print MMU registers. 1178.El 1179.Ss SH3 1180.Bl -tag -width "traptrace" -compact 1181.It Ic tlb 1182Print TLB entries. 1183.It Ic cache 1184Print cache entries. 1185.It Ic frame 1186Print switch frame and trap frames. 1187.It Ic stack 1188Print kernel stack usage. 1189Only works in 1190.Nx 1191kernels compiled with the 1192.Dv KSTACK_DEBUG 1193option. 1194.El 1195.Ss SPARC 1196.Bl -tag -width "traptrace" -compact 1197.It Ic cpu 1198Switch to another CPU. 1199.It Ic prom 1200Enter the Sun PROM monitor. 1201.It Ic proc 1202Display some information about the LWP pointed to, or curlwp. 1203.It Ic pcb 1204Display information about the 1205.Dq struct pcb 1206listed. 1207.It Ic page 1208Display the pointer to the 1209.Dq struct vm_page 1210for this physical address. 1211.El 1212.Ss SPARC64 1213.Bl -tag -width "traptrace" -compact 1214.It Ic ctx 1215Print process context information. 1216.It Ic cpu 1217Switch to another CPU. 1218.It Ic dtlb 1219Print data translation look-aside buffer context information. 1220.It Ic dtsb 1221Display data translation storage buffer information. 1222.It Ic kmap 1223Display information about the listed mapping in the kernel pmap. 1224Use the 1225.Dq f 1226modifier to get a full listing. 1227.It Ic extract 1228Extract the physical address for a given virtual address from the kernel pmap. 1229.It Ic fpstate 1230Dump the FPU state. 1231.It Ic itlb 1232Print instruction translation look-aside buffer context information. 1233.It Ic itsb 1234Display instruction translation storage buffer information. 1235.It Ic lwp 1236Display a struct lwp 1237.It Ic pcb 1238Display information about the 1239.Dq struct pcb 1240listed. 1241.It Ic pctx 1242Attempt to change process context. 1243.It Ic page 1244Display the pointer to the 1245.Dq struct vm_page 1246for this physical address. 1247.It Ic phys 1248Display physical memory. 1249.It Ic pmap 1250Display the pmap. 1251Use the 1252.Dq f 1253modifier to get a fuller listing. 1254.It Ic proc 1255Display some information about the process pointed to, or curproc. 1256.It Ic prom 1257Enter the OFW PROM. 1258.It Ic pv 1259Display the 1260.Dq struct pv_entry 1261pointed to. 1262.It Ic sir 1263Reset the machine and enter prom (do a Software Initiated Reset). 1264.It Ic stack 1265Dump the window stack. 1266Use the 1267.Dq u 1268modifier to get userland information. 1269.It Ic tf 1270Display full trap frame state. 1271This is most useful for inclusion with bug reports. 1272.It Ic ts 1273Display trap state. 1274.It Ic traptrace 1275Display or set trap trace information. 1276Use the 1277.Dq r 1278and 1279.Dq f 1280modifiers to get reversed and full information, respectively. 1281.It Ic watch 1282Set or clear a physical or virtual hardware watchpoint. 1283Pass the address to be watched, or 1284.Dq 0 1285(or omit the address) to clear the watchpoint. 1286Optional modifiers are 1287.Dq p 1288for physical address, 1289.Dq r 1290for trap on read access (default: trap on write access only), 1291.Dq b 1292for 8 bit width, 1293.Dq h 1294for 16 bit, 1295.Dq l 1296for 32 bit or 1297.Dq L 1298for 64 bit. 1299.It Ic window 1300Print register window information. 1301Argument is a stack frame number (0 is 1302top of stack, which is used when no index is given). 1303.El 1304.Ss SUN2, SUN3 and SUN3X 1305.Bl -tag -width "traptrace" -compact 1306.It Ic abort 1307Drop into monitor via abort (allows continue). 1308.It Ic halt 1309Exit to Sun PROM monitor as in 1310.Xr halt 8 . 1311.It Ic reboot 1312Reboot the machine as in 1313.Xr reboot 8 . 1314.It Ic pgmap 1315Given an address, print the address, segment map, page map, and 1316Page Table Entry (PTE). 1317.El 1318.Ss VAX 1319.Bl -tag -width "traptrace" -compact 1320.It Ic cpu 1321Switch to another CPU. 1322.El 1323.Sh VARIABLES 1324.Nm 1325accesses registers and variables as 1326.Cm $ Ns Ar name . 1327Register names are as per the 1328.Ic show registers 1329command. 1330Some variables are suffixed with numbers, and may have a modifier 1331following a colon immediately after the variable name. 1332For example, register variables may have a 1333.Sq u 1334modifier to indicate user register 1335(e.g., 1336.Li "$eax:u" ) . 1337.Pp 1338Built-in variables currently supported are: 1339.Bl -tag -offset indent -width "maxwidth" -compact 1340.It Va dumpstack 1341If non-zero (the default), 1342causes a stack trace to be printed when 1343.Nm 1344is entered on panic. 1345.It Va fromconsole 1346If non-zero (the default), 1347the kernel allows to enter 1348.Nm 1349from the console (by break signal or special key sequence). 1350If the kernel configuration option 1351.D1 Cd options DDB_FROMCONSOLE=0 1352is used, 1353.Va fromconsole 1354will be initialized to off. 1355.It Va lines 1356The number of lines. 1357This is used by the 1358.Ic more 1359feature. 1360When this variable is set to zero the 1361.Ic more 1362feature is disabled. 1363.It Va maxoff 1364Addresses are printed as 1365.Li 'symbol'+offset 1366unless 1367.Li offset 1368is greater than 1369.Va maxoff . 1370.It Va maxwidth 1371The width of the displayed line. 1372.Nm 1373wraps the current line by printing new line when 1374.Va maxwidth 1375column is reached. 1376When this variable is set to zero 1377.Nm 1378doesn't perform any wrapping. 1379.It Va onpanic 1380If greater than zero (the default is 1), 1381.Nm 1382will be invoked when the kernel panics. 1383If the kernel configuration option 1384.D1 Cd options DDB_ONPANIC=0 1385is used, 1386.Va onpanic 1387will be initialized to off, causing a stack trace to be printed and 1388the system to be rebooted instead of 1389.Nm 1390being entered. 1391Setting 1392.Va onpanic 1393to \-1 suppresses the stack trace before reboot. 1394.It Va radix 1395Input and output radix. 1396.It Va tabstops 1397Tab stop width. 1398.It Va tee_msgbuf 1399If explicitly set to non zero (zero is the default) all 1400.Nm 1401output will not only be displayed on screen but 1402also be fed to the msgbuf. 1403The default of the variable can be set using the kernel configuration option 1404.D1 Cd options DDB_TEE_MSGBUF=1 1405which will initialize 1406.Va tee_msgbuf 1407to be 1. 1408This option is especially handy for poor souls 1409who don't have a serial console but want to recall 1410.Nm 1411output from a crash investigation. 1412This option is more generic than the /l command modifier possible for 1413selected commands as discussed above to log the output. 1414Mixing both /l 1415and this setting can give double loggings. 1416.It Va panicstackframes 1417Number of stack frames to display on panic. 1418Useful to avoid scrolling away the interesting frames on a glass tty. 1419Default value is 1420.Dv 65535 1421(all frames), useful value around 1422.Dv 10 . 1423.\" .It Va work Ns Sy xx 1424.\" Temporary work variable. 1425.\" .Sq Sy xx 1426.\" is between 0 and 31. 1427.El 1428.Pp 1429All built-in variables are accessible via 1430.Xr sysctl 3 . 1431.Sh EXPRESSIONS 1432Almost all expression operators in C are supported, except 1433.Sq \&~ , 1434.Sq \&^ , 1435and unary 1436.Sq \&& . 1437Special rules in 1438.Nm 1439are: 1440.Bl -tag -offset indent -width "identifier" 1441.It Ar identifier 1442name of a symbol. 1443It is translated to the address (or value) of it. 1444.Sq \&. 1445and 1446.Sq \&: 1447can be used in the identifier. 1448If supported by an object format dependent routine, 1449.Sm off 1450.Xo 1451.Oo Ar filename : Oc 1452.Ar function 1453.Oo : Ar line\ number Oc , 1454.Xc 1455.Sm on 1456.Sm off 1457.Xo 1458.Oo Ar filename : Oc 1459.Ar variable , 1460.Xc 1461.Sm on 1462and 1463.Sm off 1464.Xo 1465.Ar filename 1466.Oo : Ar "line number" Oc , 1467.Xc 1468.Sm on 1469can be accepted as a symbol. 1470The symbol may be prefixed with 1471.Ar symbol_table_name\^ : : 1472(e.g., 1473.Li emulator::mach_msg_trap ) 1474to specify other than kernel symbols. 1475.It Ar number 1476number. 1477Radix is determined by the first two characters: 1478.Sq 0x 1479- hex, 1480.Sq 0o 1481- octal, 1482.Sq 0t 1483- decimal, 1484otherwise follow current radix. 1485.It Cm \&. 1486.Ar dot 1487.It Cm + 1488.Ar next 1489.It Cm .. 1490address of the start of the last line examined. 1491Unlike 1492.Ar dot 1493or 1494.Ar next , 1495this is only changed by the 1496.Ic examine 1497or 1498.Ic write 1499commands. 1500.It Cm \&" \"" XXX: emacs highlighting 1501last address explicitly specified. 1502.It Cm $ Ns Ar name 1503register name or variable. 1504It is translated to the value of it. 1505It may be followed by a 1506.Sq \&: 1507and modifiers as described above. 1508.It Cm # 1509a binary operator which rounds up the left hand side to the next 1510multiple of right hand side. 1511.It Cm * Ns Ar expr 1512expression indirection. 1513It may be followed by a 1514.Sq \&: 1515and modifiers as described above. 1516.El 1517.Sh SEE ALSO 1518.Xr reboot 2 , 1519.Xr options 4 , 1520.Xr crash 8 , 1521.Xr reboot 8 , 1522.Xr sysctl 8 , 1523.Xr cnmagic 9 , 1524.Xr ddb 9 1525.Sh HISTORY 1526The 1527.Nm 1528kernel debugger was written as part of the MACH project at 1529Carnegie-Mellon University. 1530