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