xref: /freebsd/share/man/man4/ddb.4 (revision 162ae9c834f6d9f9cb443bd62cceb23e0b5fef48)
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