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