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