1.\" 2.\" Mach Operating System 3.\" Copyright (c) 1991,1990 Carnegie Mellon University 4.\" Copyright (c) 2007 Robert N. M. Watson 5.\" All Rights Reserved. 6.\" 7.\" Permission to use, copy, modify and distribute this software and its 8.\" documentation is hereby granted, provided that both the copyright 9.\" notice and this permission notice appear in all copies of the 10.\" software, derivative works or modified versions, and any portions 11.\" thereof, and that both notices appear in supporting documentation. 12.\" 13.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 14.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR 15.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 16.\" 17.\" Carnegie Mellon requests users of this software to return to 18.\" 19.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 20.\" School of Computer Science 21.\" Carnegie Mellon University 22.\" Pittsburgh PA 15213-3890 23.\" 24.\" any improvements or extensions that they make and grant Carnegie Mellon 25.\" the rights to redistribute these changes. 26.\" 27.\" changed a \# to #, since groff choked on it. 28.\" 29.\" HISTORY 30.\" ddb.4,v 31.\" Revision 1.1 1993/07/15 18:41:02 brezak 32.\" Man page for DDB 33.\" 34.\" Revision 2.6 92/04/08 08:52:57 rpd 35.\" Changes from OSF. 36.\" [92/01/17 14:19:22 jsb] 37.\" Changes for OSF debugger modifications. 38.\" [91/12/12 tak] 39.\" 40.\" Revision 2.5 91/06/25 13:50:22 rpd 41.\" Added some watchpoint explanation. 42.\" [91/06/25 rpd] 43.\" 44.\" Revision 2.4 91/06/17 15:47:31 jsb 45.\" Added documentation for continue/c, match, search, and watchpoints. 46.\" I've not actually explained what a watchpoint is; maybe Rich can 47.\" do that (hint, hint). 48.\" [91/06/17 10:58:08 jsb] 49.\" 50.\" Revision 2.3 91/05/14 17:04:23 mrt 51.\" Correcting copyright 52.\" 53.\" Revision 2.2 91/02/14 14:10:06 mrt 54.\" Changed to new Mach copyright 55.\" [91/02/12 18:10:12 mrt] 56.\" 57.\" Revision 2.2 90/08/30 14:23:15 dbg 58.\" Created. 59.\" [90/08/30 dbg] 60.\" 61.\" $FreeBSD$ 62.\" 63.Dd March 16, 2015 64.Dt DDB 4 65.Os 66.Sh NAME 67.Nm ddb 68.Nd interactive kernel debugger 69.Sh SYNOPSIS 70In order to enable kernel debugging facilities include: 71.Bd -ragged -offset indent 72.Cd options KDB 73.Cd options DDB 74.Ed 75.Pp 76To prevent activation of the debugger on kernel 77.Xr panic 9 : 78.Bd -ragged -offset indent 79.Cd options KDB_UNATTENDED 80.Ed 81.Pp 82In order to print a stack trace of the current thread on the console 83for a panic: 84.Bd -ragged -offset indent 85.Cd options KDB_TRACE 86.Ed 87.Pp 88To print the numerical value of symbols in addition to the symbolic 89representation, define: 90.Bd -ragged -offset indent 91.Cd options DDB_NUMSYM 92.Ed 93.Pp 94To enable the 95.Xr gdb 1 96backend, so that remote debugging with 97.Xr kgdb 1 98is possible, include: 99.Bd -ragged -offset indent 100.Cd options GDB 101.Ed 102.Sh DESCRIPTION 103The 104.Nm 105kernel debugger is an interactive debugger with a syntax inspired by 106.Xr gdb 1 . 107If linked into the running kernel, 108it can be invoked locally with the 109.Ql debug 110.Xr keymap 5 111action. 112The debugger is also invoked on kernel 113.Xr panic 9 114if the 115.Va debug.debugger_on_panic 116.Xr sysctl 8 117MIB variable is set non-zero, 118which is the default 119unless the 120.Dv KDB_UNATTENDED 121option is specified. 122.Pp 123The current location is called 124.Va dot . 125The 126.Va dot 127is displayed with 128a hexadecimal format at a prompt. 129The commands 130.Ic examine 131and 132.Ic write 133update 134.Va dot 135to the address of the last line 136examined or the last location modified, and set 137.Va next 138to the address of 139the next location to be examined or changed. 140Other commands do not change 141.Va dot , 142and set 143.Va next 144to be the same as 145.Va dot . 146.Pp 147The general command syntax is: 148.Ar command Ns Op Li / Ns Ar modifier 149.Ar address Ns Op Li , Ns Ar count 150.Pp 151A blank line repeats the previous command from the address 152.Va next 153with 154count 1 and no modifiers. 155Specifying 156.Ar address 157sets 158.Va dot 159to the address. 160Omitting 161.Ar address 162uses 163.Va dot . 164A missing 165.Ar count 166is taken 167to be 1 for printing commands or infinity for stack traces. 168.Pp 169The 170.Nm 171debugger has a pager feature (like the 172.Xr more 1 173command) 174for the output. 175If an output line exceeds the number set in the 176.Va lines 177variable, it displays 178.Dq Li --More-- 179and waits for a response. 180The valid responses for it are: 181.Pp 182.Bl -tag -compact -width ".Li SPC" 183.It Li SPC 184one more page 185.It Li RET 186one more line 187.It Li q 188abort the current command, and return to the command input mode 189.El 190.Pp 191Finally, 192.Nm 193provides a small (currently 10 items) command history, and offers 194simple 195.Nm emacs Ns -style 196command line editing capabilities. 197In addition to 198the 199.Nm emacs 200control keys, the usual 201.Tn ANSI 202arrow keys may be used to 203browse through the history buffer, and move the cursor within the 204current line. 205.Sh COMMANDS 206.Bl -tag -width indent -compact 207.It Ic examine 208.It Ic x 209Display the addressed locations according to the formats in the modifier. 210Multiple modifier formats display multiple locations. 211If no format is specified, the last format specified for this command 212is used. 213.Pp 214The format characters are: 215.Bl -tag -compact -width indent 216.It Cm b 217look at by bytes (8 bits) 218.It Cm h 219look at by half words (16 bits) 220.It Cm l 221look at by long words (32 bits) 222.It Cm g 223look at by quad words (64 bits) 224.It Cm a 225print the location being displayed 226.It Cm A 227print the location with a line number if possible 228.It Cm x 229display in unsigned hex 230.It Cm z 231display in signed hex 232.It Cm o 233display in unsigned octal 234.It Cm d 235display in signed decimal 236.It Cm u 237display in unsigned decimal 238.It Cm r 239display in current radix, signed 240.It Cm c 241display low 8 bits as a character. 242Non-printing characters are displayed as an octal escape code (e.g., 243.Ql \e000 ) . 244.It Cm s 245display the null-terminated string at the location. 246Non-printing characters are displayed as octal escapes. 247.It Cm m 248display in unsigned hex with character dump at the end of each line. 249The location is also displayed in hex at the beginning of each line. 250.It Cm i 251display as an instruction 252.It Cm I 253display as an instruction with possible alternate formats depending on the 254machine, but none of the supported architectures have an alternate format. 255.It Cm S 256display a symbol name for the pointer stored at the address 257.El 258.Pp 259.It Ic xf 260Examine forward: 261execute an 262.Ic examine 263command with the last specified parameters to it 264except that the next address displayed by it is used as the start address. 265.Pp 266.It Ic xb 267Examine backward: 268execute an 269.Ic examine 270command with the last specified parameters to it 271except that the last start address subtracted by the size displayed by it 272is used as the start address. 273.Pp 274.It Ic print Ns Op Li / Ns Cm acdoruxz 275.It Ic p Ns Op Li / Ns Cm acdoruxz 276Print 277.Ar addr Ns s 278according to the modifier character (as described above for 279.Cm examine ) . 280Valid formats are: 281.Cm a , x , z , o , d , u , r , 282and 283.Cm c . 284If no modifier is specified, the last one specified to it is used. 285The argument 286.Ar addr 287can be a string, in which case it is printed as it is. 288For example: 289.Bd -literal -offset indent 290print/x "eax = " $eax "\enecx = " $ecx "\en" 291.Ed 292.Pp 293will print like: 294.Bd -literal -offset indent 295eax = xxxxxx 296ecx = yyyyyy 297.Ed 298.Pp 299.It Xo 300.Ic write Ns Op Li / Ns Cm bhl 301.Ar addr expr1 Op Ar expr2 ... 302.Xc 303.It Xo 304.Ic w Ns Op Li / Ns Cm bhl 305.Ar addr expr1 Op Ar expr2 ... 306.Xc 307Write the expressions specified after 308.Ar addr 309on the command line at succeeding locations starting with 310.Ar addr . 311The write unit size can be specified in the modifier with a letter 312.Cm b 313(byte), 314.Cm h 315(half word) or 316.Cm l 317(long word) respectively. 318If omitted, 319long word is assumed. 320.Pp 321.Sy Warning : 322since there is no delimiter between expressions, strange 323things may happen. 324It is best to enclose each expression in parentheses. 325.Pp 326.It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr 327Set the named variable or register with the value of 328.Ar expr . 329Valid variable names are described below. 330.Pp 331.It Ic break Ns Op Li / Ns Cm u 332.It Ic b Ns Op Li / Ns Cm u 333Set a break point at 334.Ar addr . 335If 336.Ar count 337is supplied, continues 338.Ar count 339\- 1 times before stopping at the 340break point. 341If the break point is set, a break point number is 342printed with 343.Ql # . 344This number can be used in deleting the break point 345or adding conditions to it. 346.Pp 347If the 348.Cm u 349modifier is specified, this command sets a break point in user 350address space. 351Without the 352.Cm u 353option, the address is considered to be in the kernel 354space, and a wrong space address is rejected with an error message. 355This modifier can be used only if it is supported by machine dependent 356routines. 357.Pp 358.Sy Warning : 359If a user text is shadowed by a normal user space debugger, 360user space break points may not work correctly. 361Setting a break 362point at the low-level code paths may also cause strange behavior. 363.Pp 364.It Ic delete Ar addr 365.It Ic d Ar addr 366.It Ic delete Li # Ns Ar number 367.It Ic d Li # Ns Ar number 368Delete the break point. 369The target break point can be specified by a 370break point number with 371.Ql # , 372or by using the same 373.Ar addr 374specified in the original 375.Ic break 376command. 377.Pp 378.It Ic watch Ar addr Ns Li , Ns Ar size 379Set a watchpoint for a region. 380Execution stops when an attempt to modify the region occurs. 381The 382.Ar size 383argument defaults to 4. 384If you specify a wrong space address, the request is rejected 385with an error message. 386.Pp 387.Sy Warning : 388Attempts to watch wired kernel memory 389may cause unrecoverable error in some systems such as i386. 390Watchpoints on user addresses work best. 391.Pp 392.It Ic hwatch Ar addr Ns Li , Ns Ar size 393Set a hardware watchpoint for a region if supported by the 394architecture. 395Execution stops when an attempt to modify the region occurs. 396The 397.Ar size 398argument defaults to 4. 399.Pp 400.Sy Warning : 401The hardware debug facilities do not have a concept of separate 402address spaces like the watch command does. 403Use 404.Ic hwatch 405for setting watchpoints on kernel address locations only, and avoid 406its use on user mode address spaces. 407.Pp 408.It Ic dhwatch Ar addr Ns Li , Ns Ar size 409Delete specified hardware watchpoint. 410.Pp 411.It Ic step Ns Op Li / Ns Cm p 412.It Ic s Ns Op Li / Ns Cm p 413Single step 414.Ar count 415times (the comma is a mandatory part of the syntax). 416If the 417.Cm p 418modifier is specified, print each instruction at each step. 419Otherwise, only print the last instruction. 420.Pp 421.Sy Warning : 422depending on machine type, it may not be possible to 423single-step through some low-level code paths or user space code. 424On machines with software-emulated single-stepping (e.g., pmax), 425stepping through code executed by interrupt handlers will probably 426do the wrong thing. 427.Pp 428.It Ic continue Ns Op Li / Ns Cm c 429.It Ic c Ns Op Li / Ns Cm c 430Continue execution until a breakpoint or watchpoint. 431If the 432.Cm c 433modifier is specified, count instructions while executing. 434Some machines (e.g., pmax) also count loads and stores. 435.Pp 436.Sy Warning : 437when counting, the debugger is really silently single-stepping. 438This means that single-stepping on low-level code may cause strange 439behavior. 440.Pp 441.It Ic until Ns Op Li / Ns Cm p 442Stop at the next call or return instruction. 443If the 444.Cm p 445modifier is specified, print the call nesting depth and the 446cumulative instruction count at each call or return. 447Otherwise, 448only print when the matching return is hit. 449.Pp 450.It Ic next Ns Op Li / Ns Cm p 451.It Ic match Ns Op Li / Ns Cm p 452Stop at the matching return instruction. 453If the 454.Cm p 455modifier is specified, print the call nesting depth and the 456cumulative instruction count at each call or return. 457Otherwise, only print when the matching return is hit. 458.Pp 459.It Xo 460.Ic trace Ns Op Li / Ns Cm u 461.Op Ar pid | tid 462.Op Li , Ns Ar count 463.Xc 464.It Xo 465.Ic t Ns Op Li / Ns Cm u 466.Op Ar pid | tid 467.Op Li , Ns Ar count 468.Xc 469.It Xo 470.Ic where Ns Op Li / Ns Cm u 471.Op Ar pid | tid 472.Op Li , Ns Ar count 473.Xc 474.It Xo 475.Ic bt Ns Op Li / Ns Cm u 476.Op Ar pid | tid 477.Op Li , Ns Ar count 478.Xc 479Stack trace. 480The 481.Cm u 482option traces user space; if omitted, 483.Ic trace 484only traces 485kernel space. 486The optional argument 487.Ar count 488is the number of frames to be traced. 489If 490.Ar count 491is omitted, all frames are printed. 492.Pp 493.Sy Warning : 494User space stack trace is valid 495only if the machine dependent code supports it. 496.Pp 497.It Xo 498.Ic search Ns Op Li / Ns Cm bhl 499.Ar addr 500.Ar value 501.Op Ar mask 502.Op Li , Ns Ar count 503.Xc 504Search memory for 505.Ar value . 506This command might fail in interesting 507ways if it does not find the searched-for value. 508This is because 509.Nm 510does not always recover from touching bad memory. 511The optional 512.Ar count 513argument limits the search. 514.\" 515.Pp 516.It Xo 517.Ic findstack 518.Ar addr 519.Xc 520Prints the thread address for a thread kernel-mode stack of which contains the 521specified address. 522If the thread is not found, search the thread stack cache and prints the 523cached stack address. 524Otherwise, prints nothing. 525.Pp 526.It Ic show Cm all procs Ns Op Li / Ns Cm m 527.It Ic ps Ns Op Li / Ns Cm m 528Display all process information. 529The process information may not be shown if it is not 530supported in the machine, or the bottom of the stack of the 531target process is not in the main memory at that time. 532The 533.Cm m 534modifier will alter the display to show VM map 535addresses for the process and not show other information. 536.\" 537.Pp 538.It Ic show Cm all ttys 539Show all TTY's within the system. 540Output is similar to 541.Xr pstat 8 , 542but also includes the address of the TTY structure. 543.\" 544.Pp 545.It Ic show Cm allchains 546Show the same information like "show lockchain" does, but 547for every thread in the system. 548.\" 549.Pp 550.It Ic show Cm alllocks 551Show all locks that are currently held. 552This command is only available if 553.Xr witness 4 554is included in the kernel. 555.\" 556.Pp 557.It Ic show Cm allpcpu 558The same as "show pcpu", but for every CPU present in the system. 559.\" 560.Pp 561.It Ic show Cm allrman 562Show information related with resource management, including 563interrupt request lines, DMA request lines, I/O ports and I/O memory 564addresses. 565.\" 566.Pp 567.It Ic show Cm apic 568Dump data about APIC IDT vector mappings. 569.\" 570.Pp 571.It Ic show Cm breaks 572Show breakpoints set with the "break" command. 573.\" 574.Pp 575.It Ic show Cm bio Ar addr 576Show information about the bio structure 577.Vt struct bio 578present at 579.Ar addr . 580See the 581.Pa sys/bio.h 582header file and 583.Xr g_bio 9 584for more details on the exact meaning of the structure fields. 585.\" 586.Pp 587.It Ic show Cm buffer Ar addr 588Show information about the buf structure 589.Vt struct buf 590present at 591.Ar addr . 592See the 593.Pa sys/buf.h 594header file for more details on the exact meaning of the structure fields. 595.\" 596.Pp 597.It Ic show Cm cbstat 598Show brief information about the TTY subsystem. 599.\" 600.Pp 601.It Ic show Cm cdev 602Without argument, show the list of all created cdev's, consisting of devfs 603node name and struct cdev address. 604When address of cdev is supplied, show some internal devfs state of the cdev. 605.\" 606.Pp 607.It Ic show Cm conifhk 608Lists hooks currently waiting for completion in 609run_interrupt_driven_config_hooks(). 610.\" 611.Pp 612.It Ic show Cm cpusets 613Print numbered root and assigned CPU affinity sets. 614See 615.Xr cpuset 2 616for more details. 617.\" 618.Pp 619.It Ic show Cm cyrixreg 620Show registers specific to the Cyrix processor. 621.\" 622.Pp 623.It Ic show Cm devmap 624Prints the contents of the static device mapping table. 625Currently only available on the 626ARM 627architecture. 628.\" 629.Pp 630.It Ic show Cm domain Ar addr 631Print protocol domain structure 632.Vt struct domain 633at address 634.Ar addr . 635See the 636.Pa sys/domain.h 637header file for more details on the exact meaning of the structure fields. 638.\" 639.Pp 640.It Ic show Cm ffs Op Ar addr 641Show brief information about ffs mount at the address 642.Ar addr , 643if argument is given. 644Otherwise, provides the summary about each ffs mount. 645.\" 646.Pp 647.It Ic show Cm file Ar addr 648Show information about the file structure 649.Vt struct file 650present at address 651.Ar addr . 652.\" 653.Pp 654.It Ic show Cm files 655Show information about every file structure in the system. 656.\" 657.Pp 658.It Ic show Cm freepages 659Show the number of physical pages in each of the free lists. 660.\" 661.Pp 662.It Ic show Cm geom Op Ar addr 663If the 664.Ar addr 665argument is not given, displays the entire GEOM topology. 666If 667.Ar addr 668is given, displays details about the given GEOM object (class, geom, 669provider or consumer). 670.\" 671.Pp 672.It Ic show Cm idt 673Show IDT layout. 674The first column specifies the IDT vector. 675The second one is the name of the interrupt/trap handler. 676Those functions are machine dependent. 677.\" 678.Pp 679.It Ic show Cm inodedeps Op Ar addr 680Show brief information about each inodedep structure. 681If 682.Ar addr 683is given, only inodedeps belonging to the fs located at the 684supplied address are shown. 685.\" 686.Pp 687.It Ic show Cm inpcb Ar addr 688Show information on IP Control Block 689.Vt struct in_pcb 690present at 691.Ar addr . 692.\" 693.Pp 694.It Ic show Cm intr 695Dump information about interrupt handlers. 696.\" 697.Pp 698.It Ic show Cm intrcnt 699Dump the interrupt statistics. 700.\" 701.Pp 702.It Ic show Cm irqs 703Show interrupt lines and their respective kernel threads. 704.\" 705.Pp 706.It Ic show Cm jails 707Show the list of 708.Xr jail 8 709instances. 710In addition to what 711.Xr jls 8 712shows, also list kernel internal details. 713.\" 714.Pp 715.It Ic show Cm lapic 716Show information from the local APIC registers for this CPU. 717.\" 718.Pp 719.It Ic show Cm lock Ar addr 720Show lock structure. 721The output format is as follows: 722.Bl -tag -width "flags" 723.It Ic class: 724Class of the lock. 725Possible types include 726.Xr mutex 9 , 727.Xr rmlock 9 , 728.Xr rwlock 9 , 729.Xr sx 9 . 730.It Ic name: 731Name of the lock. 732.It Ic flags: 733Flags passed to the lock initialization function. 734For exact possibilities see manual pages of possible lock types. 735.It Ic state: 736Current state of a lock. 737As well as 738.Ic flags 739it's lock-specific. 740.It Ic owner: 741Lock owner. 742.El 743.\" 744.Pp 745.It Ic show Cm lockchain Ar addr 746Show all threads a particular thread at address 747.Ar addr 748is waiting on based on non-sleepable and non-spin locks. 749.\" 750.Pp 751.It Ic show Cm lockedbufs 752Show the same information as "show buf", but for every locked 753.Vt struct buf 754object. 755.\" 756.Pp 757.It Ic show Cm lockedvnods 758List all locked vnodes in the system. 759.\" 760.Pp 761.It Ic show Cm locks 762Prints all locks that are currently acquired. 763This command is only available if 764.Xr witness 4 765is included in the kernel. 766.\" 767.Pp 768.It Ic show Cm locktree 769.\" 770.Pp 771.It Ic show Cm malloc 772Prints 773.Xr malloc 9 774memory allocator statistics. 775The output format is as follows: 776.Pp 777.Bl -tag -compact -offset indent -width "Requests" 778.It Ic Type 779Specifies a type of memory. 780It is the same as a description string used while defining the 781given memory type with 782.Xr MALLOC_DECLARE 9 . 783.It Ic InUse 784Number of memory allocations of the given type, for which 785.Xr free 9 786has not been called yet. 787.It Ic MemUse 788Total memory consumed by the given allocation type. 789.It Ic Requests 790Number of memory allocation requests for the given 791memory type. 792.El 793.Pp 794The same information can be gathered in userspace with 795.Dq Nm vmstat Fl m . 796.\" 797.Pp 798.It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr 799Prints the VM map at 800.Ar addr . 801If the 802.Cm f 803modifier is specified the 804complete map is printed. 805.\" 806.Pp 807.It Ic show Cm msgbuf 808Print the system's message buffer. 809It is the same output as in the 810.Dq Nm dmesg 811case. 812It is useful if you got a kernel panic, attached a serial cable 813to the machine and want to get the boot messages from before the 814system hang. 815.\" 816.It Ic show Cm mount 817Displays short info about all currently mounted file systems. 818.Pp 819.It Ic show Cm mount Ar addr 820Displays details about the given mount point. 821.\" 822.Pp 823.It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr 824Prints the VM object at 825.Ar addr . 826If the 827.Cm f 828option is specified the 829complete object is printed. 830.\" 831.Pp 832.It Ic show Cm page 833Show statistics on VM pages. 834.\" 835.Pp 836.It Ic show Cm pageq 837Show statistics on VM page queues. 838.\" 839.Pp 840.It Ic show Cm pciregs 841Print PCI bus registers. 842The same information can be gathered in userspace by running 843.Dq Nm pciconf Fl lv . 844.\" 845.Pp 846.It Ic show Cm pcpu 847Print current processor state. 848The output format is as follows: 849.Pp 850.Bl -tag -compact -offset indent -width "spin locks held:" 851.It Ic cpuid 852Processor identifier. 853.It Ic curthread 854Thread pointer, process identifier and the name of the process. 855.It Ic curpcb 856Control block pointer. 857.It Ic fpcurthread 858FPU thread pointer. 859.It Ic idlethread 860Idle thread pointer. 861.It Ic APIC ID 862CPU identifier coming from APIC. 863.It Ic currentldt 864LDT pointer. 865.It Ic spin locks held 866Names of spin locks held. 867.El 868.\" 869.Pp 870.It Ic show Cm pgrpdump 871Dump process groups present within the system. 872.\" 873.Pp 874.It Ic show Cm proc Op Ar addr 875If no 876.Op Ar addr 877is specified, print information about the current process. 878Otherwise, show information about the process at address 879.Ar addr . 880.\" 881.Pp 882.It Ic show Cm procvm 883Show process virtual memory layout. 884.\" 885.Pp 886.It Ic show Cm protosw Ar addr 887Print protocol switch structure 888.Vt struct protosw 889at address 890.Ar addr . 891.\" 892.Pp 893.It Ic show Cm registers Ns Op Li / Ns Cm u 894Display the register set. 895If the 896.Cm u 897modifier is specified, it displays user registers instead of 898kernel registers or the currently saved one. 899.Pp 900.Sy Warning : 901The support of the 902.Cm u 903modifier depends on the machine. 904If not supported, incorrect information will be displayed. 905.\" 906.Pp 907.It Ic show Cm rman Ar addr 908Show resource manager object 909.Vt struct rman 910at address 911.Ar addr . 912Addresses of particular pointers can be gathered with "show allrman" 913command. 914.\" 915.Pp 916.It Ic show Cm rtc 917Show real time clock value. 918Useful for long debugging sessions. 919.\" 920.Pp 921.It Ic show Cm sleepchain 922Show all the threads a particular thread is waiting on based on 923sleepable locks. 924.\" 925.Pp 926.It Ic show Cm sleepq 927.It Ic show Cm sleepqueue 928Both commands provide the same functionality. 929They show sleepqueue 930.Vt struct sleepqueue 931structure. 932Sleepqueues are used within the 933.Fx 934kernel to implement sleepable 935synchronization primitives (thread holding a lock might sleep or 936be context switched), which at the time of writing are: 937.Xr condvar 9 , 938.Xr sx 9 939and standard 940.Xr msleep 9 941interface. 942.\" 943.Pp 944.It Ic show Cm sockbuf Ar addr 945.It Ic show Cm socket Ar addr 946Those commands print 947.Vt struct sockbuf 948and 949.Vt struct socket 950objects placed at 951.Ar addr . 952Output consists of all values present in structures mentioned. 953For exact interpretation and more details, visit 954.Pa sys/socket.h 955header file. 956.\" 957.Pp 958.It Ic show Cm sysregs 959Show system registers (e.g., 960.Li cr0-4 961on i386.) 962Not present on some platforms. 963.\" 964.Pp 965.It Ic show Cm tcpcb Ar addr 966Print TCP control block 967.Vt struct tcpcb 968lying at address 969.Ar addr . 970For exact interpretation of output, visit 971.Pa netinet/tcp.h 972header file. 973.\" 974.Pp 975.It Ic show Cm thread Op Ar addr 976If no 977.Ar addr 978is specified, show detailed information about current thread. 979Otherwise, information about thread at 980.Ar addr 981is printed. 982.\" 983.Pp 984.It Ic show Cm threads 985Show all threads within the system. 986Output format is as follows: 987.Pp 988.Bl -tag -compact -offset indent -width "Second column" 989.It Ic First column 990Thread identifier (TID) 991.It Ic Second column 992Thread structure address 993.It Ic Third column 994Backtrace. 995.El 996.\" 997.Pp 998.It Ic show Cm tty Ar addr 999Display the contents of a TTY structure in a readable form. 1000.\" 1001.Pp 1002.It Ic show Cm turnstile Ar addr 1003Show turnstile 1004.Vt struct turnstile 1005structure at address 1006.Ar addr . 1007Turnstiles are structures used within the 1008.Fx 1009kernel to implement 1010synchronization primitives which, while holding a specific type of lock, cannot 1011sleep or context switch to another thread. 1012Currently, those are: 1013.Xr mutex 9 , 1014.Xr rwlock 9 , 1015.Xr rmlock 9 . 1016.\" 1017.Pp 1018.It Ic show Cm uma 1019Show UMA allocator statistics. 1020Output consists five columns: 1021.Pp 1022.Bl -tag -compact -offset indent -width "Requests" 1023.It Cm "Zone" 1024Name of the UMA zone. 1025The same string that was passed to 1026.Xr uma_zcreate 9 1027as a first argument. 1028.It Cm "Size" 1029Size of a given memory object (slab). 1030.It Cm "Used" 1031Number of slabs being currently used. 1032.It Cm "Free" 1033Number of free slabs within the UMA zone. 1034.It Cm "Requests" 1035Number of allocations requests to the given zone. 1036.El 1037.Pp 1038The very same information might be gathered in the userspace 1039with the help of 1040.Dq Nm vmstat Fl z . 1041.\" 1042.Pp 1043.It Ic show Cm unpcb Ar addr 1044Shows UNIX domain socket private control block 1045.Vt struct unpcb 1046present at the address 1047.Ar addr . 1048.\" 1049.Pp 1050.It Ic show Cm vmochk 1051Prints, whether the internal VM objects are in a map somewhere 1052and none have zero ref counts. 1053.\" 1054.Pp 1055.It Ic show Cm vmopag 1056This is supposed to show physical addresses consumed by a 1057VM object. 1058Currently, it is not possible to use this command when 1059.Xr witness 4 1060is compiled in the kernel. 1061.\" 1062.Pp 1063.It Ic show Cm vnode Op Ar addr 1064Prints vnode 1065.Vt struct vnode 1066structure lying at 1067.Op Ar addr . 1068For the exact interpretation of the output, look at the 1069.Pa sys/vnode.h 1070header file. 1071.\" 1072.Pp 1073.It Ic show Cm vnodebufs Ar addr 1074Shows clean/dirty buffer lists of the vnode located at 1075.Ar addr . 1076.\" 1077.Pp 1078.It Ic show Cm watches 1079Displays all watchpoints. 1080Shows watchpoints set with "watch" command. 1081.\" 1082.Pp 1083.It Ic show Cm witness 1084Shows information about lock acquisition coming from the 1085.Xr witness 4 1086subsystem. 1087.\" 1088.Pp 1089.It Ic gdb 1090Toggles between remote GDB and DDB mode. 1091In remote GDB mode, another machine is required that runs 1092.Xr gdb 1 1093using the remote debug feature, with a connection to the serial 1094console port on the target machine. 1095Currently only available on the 1096i386 1097architecture. 1098.Pp 1099.It Ic halt 1100Halt the system. 1101.Pp 1102.It Ic kill Ar sig pid 1103Send signal 1104.Ar sig 1105to process 1106.Ar pid . 1107The signal is acted on upon returning from the debugger. 1108This command can be used to kill a process causing resource contention 1109in the case of a hung system. 1110See 1111.Xr signal 3 1112for a list of signals. 1113Note that the arguments are reversed relative to 1114.Xr kill 2 . 1115.Pp 1116.It Ic reboot Op Ar seconds 1117.It Ic reset Op Ar seconds 1118Hard reset the system. 1119If the optional argument 1120.Ar seconds 1121is given, the debugger will wait for this long, at most a week, 1122before rebooting. 1123.Pp 1124.It Ic help 1125Print a short summary of the available commands and command 1126abbreviations. 1127.Pp 1128.It Ic capture on 1129.It Ic capture off 1130.It Ic capture reset 1131.It Ic capture status 1132.Nm 1133supports a basic output capture facility, which can be used to retrieve the 1134results of debugging commands from userspace using 1135.Xr sysctl 2 . 1136.Ic capture on 1137enables output capture; 1138.Ic capture off 1139disables capture. 1140.Ic capture reset 1141will clear the capture buffer and disable capture. 1142.Ic capture status 1143will report current buffer use, buffer size, and disposition of output 1144capture. 1145.Pp 1146Userspace processes may inspect and manage 1147.Nm 1148capture state using 1149.Xr sysctl 8 : 1150.Pp 1151.Dv debug.ddb.capture.bufsize 1152may be used to query or set the current capture buffer size. 1153.Pp 1154.Dv debug.ddb.capture.maxbufsize 1155may be used to query the compile-time limit on the capture buffer size. 1156.Pp 1157.Dv debug.ddb.capture.bytes 1158may be used to query the number of bytes of output currently in the capture 1159buffer. 1160.Pp 1161.Dv debug.ddb.capture.data 1162returns the contents of the buffer as a string to an appropriately privileged 1163process. 1164.Pp 1165This facility is particularly useful in concert with the scripting and 1166.Xr textdump 4 1167facilities, allowing scripted debugging output to be captured and 1168committed to disk as part of a textdump for later analysis. 1169The contents of the capture buffer may also be inspected in a kernel core dump 1170using 1171.Xr kgdb 1 . 1172.Pp 1173.It Ic run 1174.It Ic script 1175.It Ic scripts 1176.It Ic unscript 1177Run, define, list, and delete scripts. 1178See the 1179.Sx SCRIPTING 1180section for more information on the scripting facility. 1181.Pp 1182.It Ic textdump dump 1183.It Ic textdump set 1184.It Ic textdump status 1185.It Ic textdump unset 1186Use the 1187.Ic textdump dump 1188command to immediately perform a textdump. 1189More information may be found in 1190.Xr textdump 4 . 1191The 1192.Ic textdump set 1193command may be used to force the next kernel core dump to be a textdump 1194rather than a traditional memory dump or minidump. 1195.Ic textdump status 1196reports whether a textdump has been scheduled. 1197.Ic textdump unset 1198cancels a request to perform a textdump as the next kernel core dump. 1199.El 1200.Sh VARIABLES 1201The debugger accesses registers and variables as 1202.Li $ Ns Ar name . 1203Register names are as in the 1204.Dq Ic show Cm registers 1205command. 1206Some variables are suffixed with numbers, and may have some modifier 1207following a colon immediately after the variable name. 1208For example, register variables can have a 1209.Cm u 1210modifier to indicate user register (e.g., 1211.Dq Li $eax:u ) . 1212.Pp 1213Built-in variables currently supported are: 1214.Pp 1215.Bl -tag -width ".Va tabstops" -compact 1216.It Va radix 1217Input and output radix. 1218.It Va maxoff 1219Addresses are printed as 1220.Dq Ar symbol Ns Li + Ns Ar offset 1221unless 1222.Ar offset 1223is greater than 1224.Va maxoff . 1225.It Va maxwidth 1226The width of the displayed line. 1227.It Va lines 1228The number of lines. 1229It is used by the built-in pager. 1230.It Va tabstops 1231Tab stop width. 1232.It Va work Ns Ar xx 1233Work variable; 1234.Ar xx 1235can take values from 0 to 31. 1236.El 1237.Sh EXPRESSIONS 1238Most expression operators in C are supported except 1239.Ql ~ , 1240.Ql ^ , 1241and unary 1242.Ql & . 1243Special rules in 1244.Nm 1245are: 1246.Bl -tag -width ".No Identifiers" 1247.It Identifiers 1248The name of a symbol is translated to the value of the symbol, which 1249is the address of the corresponding object. 1250.Ql \&. 1251and 1252.Ql \&: 1253can be used in the identifier. 1254If supported by an object format dependent routine, 1255.Sm off 1256.Oo Ar filename : Oc Ar func : lineno , 1257.Sm on 1258.Oo Ar filename : Oc Ns Ar variable , 1259and 1260.Oo Ar filename : Oc Ns Ar lineno 1261can be accepted as a symbol. 1262.It Numbers 1263Radix is determined by the first two letters: 1264.Ql 0x : 1265hex, 1266.Ql 0o : 1267octal, 1268.Ql 0t : 1269decimal; otherwise, follow current radix. 1270.It Li \&. 1271.Va dot 1272.It Li + 1273.Va next 1274.It Li .. 1275address of the start of the last line examined. 1276Unlike 1277.Va dot 1278or 1279.Va next , 1280this is only changed by 1281.Ic examine 1282or 1283.Ic write 1284command. 1285.It Li ' 1286last address explicitly specified. 1287.It Li $ Ns Ar variable 1288Translated to the value of the specified variable. 1289It may be followed by a 1290.Ql \&: 1291and modifiers as described above. 1292.It Ar a Ns Li # Ns Ar b 1293A binary operator which rounds up the left hand side to the next 1294multiple of right hand side. 1295.It Li * Ns Ar expr 1296Indirection. 1297It may be followed by a 1298.Ql \&: 1299and modifiers as described above. 1300.El 1301.Sh SCRIPTING 1302.Nm 1303supports a basic scripting facility to allow automating tasks or responses to 1304specific events. 1305Each script consists of a list of DDB commands to be executed sequentially, 1306and is assigned a unique name. 1307Certain script names have special meaning, and will be automatically run on 1308various 1309.Nm 1310events if scripts by those names have been defined. 1311.Pp 1312The 1313.Ic script 1314command may be used to define a script by name. 1315Scripts consist of a series of 1316.Nm 1317commands separated with the 1318.Ql \&; 1319character. 1320For example: 1321.Bd -literal -offset indent 1322script kdb.enter.panic=bt; show pcpu 1323script lockinfo=show alllocks; show lockedvnods 1324.Ed 1325.Pp 1326The 1327.Ic scripts 1328command lists currently defined scripts. 1329.Pp 1330The 1331.Ic run 1332command execute a script by name. 1333For example: 1334.Bd -literal -offset indent 1335run lockinfo 1336.Ed 1337.Pp 1338The 1339.Ic unscript 1340command may be used to delete a script by name. 1341For example: 1342.Bd -literal -offset indent 1343unscript kdb.enter.panic 1344.Ed 1345.Pp 1346These functions may also be performed from userspace using the 1347.Xr ddb 8 1348command. 1349.Pp 1350Certain scripts are run automatically, if defined, for specific 1351.Nm 1352events. 1353The follow scripts are run when various events occur: 1354.Bl -tag -width kdb.enter.powerfail 1355.It Dv kdb.enter.acpi 1356The kernel debugger was entered as a result of an 1357.Xr acpi 4 1358event. 1359.It Dv kdb.enter.bootflags 1360The kernel debugger was entered at boot as a result of the debugger boot 1361flag being set. 1362.It Dv kdb.enter.break 1363The kernel debugger was entered as a result of a serial or console break. 1364.It Dv kdb.enter.cam 1365The kernel debugger was entered as a result of a 1366.Xr CAM 4 1367event. 1368.It Dv kdb.enter.mac 1369The kernel debugger was entered as a result of an assertion failure in the 1370.Xr mac_test 4 1371module of the 1372TrustedBSD MAC Framework. 1373.It Dv kdb.enter.ndis 1374The kernel debugger was entered as a result of an 1375.Xr ndis 4 1376breakpoint event. 1377.It Dv kdb.enter.netgraph 1378The kernel debugger was entered as a result of a 1379.Xr netgraph 4 1380event. 1381.It Dv kdb.enter.panic 1382.Xr panic 9 1383was called. 1384.It Dv kdb.enter.powerfail 1385The kernel debugger was entered as a result of a powerfail NMI on the sparc64 1386platform. 1387.It Dv kdb.enter.powerpc 1388The kernel debugger was entered as a result of an unimplemented interrupt 1389type on the powerpc platform. 1390.It Dv kdb.enter.sysctl 1391The kernel debugger was entered as a result of the 1392.Dv debug.kdb.enter 1393sysctl being set. 1394.It Dv kdb.enter.trapsig 1395The kernel debugger was entered as a result of a trapsig event on the sparc64 1396platform. 1397.It Dv kdb.enter.unionfs 1398The kernel debugger was entered as a result of an assertion failure in the 1399union file system. 1400.It Dv kdb.enter.unknown 1401The kernel debugger was entered, but no reason has been set. 1402.It Dv kdb.enter.vfslock 1403The kernel debugger was entered as a result of a VFS lock violation. 1404.It Dv kdb.enter.watchdog 1405The kernel debugger was entered as a result of a watchdog firing. 1406.It Dv kdb.enter.witness 1407The kernel debugger was entered as a result of a 1408.Xr witness 4 1409violation. 1410.El 1411.Pp 1412In the event that none of these scripts is found, 1413.Nm 1414will attempt to execute a default script: 1415.Bl -tag -width kdb.enter.powerfail 1416.It Dv kdb.enter.default 1417The kernel debugger was entered, but a script exactly matching the reason for 1418entering was not defined. 1419This can be used as a catch-all to handle cases not specifically of interest; 1420for example, 1421.Dv kdb.enter.witness 1422might be defined to have special handling, and 1423.Dv kdb.enter.default 1424might be defined to simply panic and reboot. 1425.El 1426.Sh HINTS 1427On machines with an ISA expansion bus, a simple NMI generation card can be 1428constructed by connecting a push button between the A01 and B01 (CHCHK# and 1429GND) card fingers. 1430Momentarily shorting these two fingers together may cause the bridge chipset to 1431generate an NMI, which causes the kernel to pass control to 1432.Nm . 1433Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary. 1434The NMI allows one to break into the debugger on a wedged machine to 1435diagnose problems. 1436Other bus' bridge chipsets may be able to generate NMI using bus specific 1437methods. 1438.Sh FILES 1439Header files mentioned in this manual page can be found below 1440.Pa /usr/include 1441directory. 1442.Pp 1443.Bl -dash -compact 1444.It 1445.Pa sys/buf.h 1446.It 1447.Pa sys/domain.h 1448.It 1449.Pa netinet/in_pcb.h 1450.It 1451.Pa sys/socket.h 1452.It 1453.Pa sys/vnode.h 1454.El 1455.Sh SEE ALSO 1456.Xr gdb 1 , 1457.Xr kgdb 1 , 1458.Xr acpi 4 , 1459.Xr CAM 4 , 1460.Xr mac_test 4 , 1461.Xr ndis 4 , 1462.Xr netgraph 4 , 1463.Xr textdump 4 , 1464.Xr witness 4 , 1465.Xr ddb 8 , 1466.Xr sysctl 8 , 1467.Xr panic 9 1468.Sh HISTORY 1469The 1470.Nm 1471debugger was developed for Mach, and ported to 1472.Bx 386 0.1 . 1473This manual page translated from 1474.Xr man 7 1475macros by 1476.An Garrett Wollman . 1477.Pp 1478.An Robert N. M. Watson 1479added support for 1480.Nm 1481output capture, 1482.Xr textdump 4 1483and scripting in 1484.Fx 7.1 . 1485