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