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