xref: /freebsd/share/man/man4/ddb.4 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\"
2.\" Mach Operating System
3.\" Copyright (c) 1991,1990 Carnegie Mellon University
4.\" Copyright (c) 2007 Robert N. M. Watson
5.\" All Rights Reserved.
6.\"
7.\" Permission to use, copy, modify and distribute this software and its
8.\" documentation is hereby granted, provided that both the copyright
9.\" notice and this permission notice appear in all copies of the
10.\" software, derivative works or modified versions, and any portions
11.\" thereof, and that both notices appear in supporting documentation.
12.\"
13.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
14.\" CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
15.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
16.\"
17.\" Carnegie Mellon requests users of this software to return to
18.\"
19.\"  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
20.\"  School of Computer Science
21.\"  Carnegie Mellon University
22.\"  Pittsburgh PA 15213-3890
23.\"
24.\" any improvements or extensions that they make and grant Carnegie Mellon
25.\" the rights to redistribute these changes.
26.\"
27.\" changed a \# to #, since groff choked on it.
28.\"
29.\" HISTORY
30.\" ddb.4,v
31.\" Revision 1.1  1993/07/15  18:41:02  brezak
32.\" Man page for DDB
33.\"
34.\" Revision 2.6  92/04/08  08:52:57  rpd
35.\" 	Changes from OSF.
36.\" 	[92/01/17  14:19:22  jsb]
37.\" 	Changes for OSF debugger modifications.
38.\" 	[91/12/12            tak]
39.\"
40.\" Revision 2.5  91/06/25  13:50:22  rpd
41.\" 	Added some watchpoint explanation.
42.\" 	[91/06/25            rpd]
43.\"
44.\" Revision 2.4  91/06/17  15:47:31  jsb
45.\" 	Added documentation for continue/c, match, search, and watchpoints.
46.\" 	I've not actually explained what a watchpoint is; maybe Rich can
47.\" 	do that (hint, hint).
48.\" 	[91/06/17  10:58:08  jsb]
49.\"
50.\" Revision 2.3  91/05/14  17:04:23  mrt
51.\" 	Correcting copyright
52.\"
53.\" Revision 2.2  91/02/14  14:10:06  mrt
54.\" 	Changed to new Mach copyright
55.\" 	[91/02/12  18:10:12  mrt]
56.\"
57.\" Revision 2.2  90/08/30  14:23:15  dbg
58.\" 	Created.
59.\" 	[90/08/30            dbg]
60.\"
61.\" $FreeBSD$
62.\"
63.Dd December 26, 2007
64.Dt DDB 4
65.Os
66.Sh NAME
67.Nm ddb
68.Nd interactive kernel debugger
69.Sh SYNOPSIS
70.Cd options KDB
71.Cd options DDB
72.Pp
73To prevent activation of the debugger on kernel
74.Xr panic 9 :
75.Cd options KDB_UNATTENDED
76.Sh DESCRIPTION
77The
78.Nm
79kernel debugger has most of the features of the old
80.Nm kdb ,
81but with a more rational syntax
82inspired by
83.Xr gdb 1 .
84If linked into the running kernel,
85it can be invoked locally with the
86.Ql debug
87.Xr keymap 5
88action.
89The debugger is also invoked on kernel
90.Xr panic 9
91if the
92.Va debug.debugger_on_panic
93.Xr sysctl 8
94MIB variable is set non-zero,
95which is the default
96unless the
97.Dv KDB_UNATTENDED
98option is specified.
99.Pp
100The current location is called
101.Va dot .
102The
103.Va dot
104is displayed with
105a hexadecimal format at a prompt.
106The commands
107.Ic examine
108and
109.Ic write
110update
111.Va dot
112to the address of the last line
113examined or the last location modified, and set
114.Va next
115to the address of
116the next location to be examined or changed.
117Other commands do not change
118.Va dot ,
119and set
120.Va next
121to be the same as
122.Va dot .
123.Pp
124The general command syntax is:
125.Ar command Ns Op Li / Ns Ar modifier
126.Ar address Ns Op Li , Ns Ar count
127.Pp
128A blank line repeats the previous command from the address
129.Va next
130with
131count 1 and no modifiers.
132Specifying
133.Ar address
134sets
135.Va dot
136to the address.
137Omitting
138.Ar address
139uses
140.Va dot .
141A missing
142.Ar count
143is taken
144to be 1 for printing commands or infinity for stack traces.
145.Pp
146The
147.Nm
148debugger has a pager feature (like the
149.Xr more 1
150command)
151for the output.
152If an output line exceeds the number set in the
153.Va lines
154variable, it displays
155.Dq Li --More--
156and waits for a response.
157The valid responses for it are:
158.Pp
159.Bl -tag -compact -width ".Li SPC"
160.It Li SPC
161one more page
162.It Li RET
163one more line
164.It Li q
165abort the current command, and return to the command input mode
166.El
167.Pp
168Finally,
169.Nm
170provides a small (currently 10 items) command history, and offers
171simple
172.Nm emacs Ns -style
173command line editing capabilities.
174In addition to
175the
176.Nm emacs
177control keys, the usual
178.Tn ANSI
179arrow keys might be used to
180browse through the history buffer, and move the cursor within the
181current line.
182.Sh COMMANDS
183.Bl -tag -width indent -compact
184.It Ic examine
185.It Ic x
186Display the addressed locations according to the formats in the modifier.
187Multiple modifier formats display multiple locations.
188If no format is specified, the last format specified for this command
189is used.
190.Pp
191The format characters are:
192.Bl -tag -compact -width indent
193.It Cm b
194look at by bytes (8 bits)
195.It Cm h
196look at by half words (16 bits)
197.It Cm l
198look at by long words (32 bits)
199.It Cm a
200print the location being displayed
201.It Cm A
202print the location with a line number if possible
203.It Cm x
204display in unsigned hex
205.It Cm z
206display in signed hex
207.It Cm o
208display in unsigned octal
209.It Cm d
210display in signed decimal
211.It Cm u
212display in unsigned decimal
213.It Cm r
214display in current radix, signed
215.It Cm c
216display low 8 bits as a character.
217Non-printing characters are displayed as an octal escape code (e.g.,
218.Ql \e000 ) .
219.It Cm s
220display the null-terminated string at the location.
221Non-printing characters are displayed as octal escapes.
222.It Cm m
223display in unsigned hex with character dump at the end of each line.
224The location is also displayed in hex at the beginning of each line.
225.It Cm i
226display as an instruction
227.It Cm I
228display as an instruction with possible alternate formats depending on the
229machine:
230.Bl -tag -width ".Tn powerpc" -compact
231.It Tn alpha
232Show the registers of the instruction.
233.It Tn amd64
234No alternate format.
235.It Tn i386
236No alternate format.
237.It Tn ia64
238No alternate format.
239.It Tn powerpc
240No alternate format.
241.It Tn sparc64
242No alternate format.
243.El
244.El
245.Pp
246.It Ic xf
247Examine forward:
248execute an
249.Ic examine
250command with the last specified parameters to it
251except that the next address displayed by it is used as the start address.
252.Pp
253.It Ic xb
254Examine backward:
255execute an
256.Ic examine
257command with the last specified parameters to it
258except that the last start address subtracted by the size displayed by it
259is used as the start address.
260.Pp
261.It Ic print Ns Op Li / Ns Cm acdoruxz
262.It Ic p Ns Op Li / Ns Cm acdoruxz
263Print
264.Ar addr Ns s
265according to the modifier character (as described above for
266.Cm examine ) .
267Valid formats are:
268.Cm a , x , z , o , d , u , r ,
269and
270.Cm c .
271If no modifier is specified, the last one specified to it is used.
272The argument
273.Ar addr
274can be a string, in which case it is printed as it is.
275For example:
276.Bd -literal -offset indent
277print/x "eax = " $eax "\enecx = " $ecx "\en"
278.Ed
279.Pp
280will print like:
281.Bd -literal -offset indent
282eax = xxxxxx
283ecx = yyyyyy
284.Ed
285.Pp
286.It Xo
287.Ic write Ns Op Li / Ns Cm bhl
288.Ar addr expr1 Op Ar expr2 ...
289.Xc
290.It Xo
291.Ic w Ns Op Li / Ns Cm bhl
292.Ar addr expr1 Op Ar expr2 ...
293.Xc
294Write the expressions specified after
295.Ar addr
296on the command line at succeeding locations starting with
297.Ar addr .
298The write unit size can be specified in the modifier with a letter
299.Cm b
300(byte),
301.Cm h
302(half word) or
303.Cm l
304(long word) respectively.
305If omitted,
306long word is assumed.
307.Pp
308.Sy Warning :
309since there is no delimiter between expressions, strange
310things may happen.
311It is best to enclose each expression in parentheses.
312.Pp
313.It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr
314Set the named variable or register with the value of
315.Ar expr .
316Valid variable names are described below.
317.Pp
318.It Ic break Ns Op Li / Ns Cm u
319.It Ic b Ns Op Li / Ns Cm u
320Set a break point at
321.Ar addr .
322If
323.Ar count
324is supplied, continues
325.Ar count
326\- 1 times before stopping at the
327break point.
328If the break point is set, a break point number is
329printed with
330.Ql # .
331This number can be used in deleting the break point
332or adding conditions to it.
333.Pp
334If the
335.Cm u
336modifier is specified, this command sets a break point in user space
337address.
338Without the
339.Cm u
340option, the address is considered in the kernel
341space, and wrong space address is rejected with an error message.
342This modifier can be used only if it is supported by machine dependent
343routines.
344.Pp
345.Sy Warning :
346If a user text is shadowed by a normal user space debugger,
347user space break points may not work correctly.
348Setting a break
349point at the low-level code paths may also cause strange behavior.
350.Pp
351.It Ic delete Ar addr
352.It Ic d Ar addr
353.It Ic delete Li # Ns Ar number
354.It Ic d Li # Ns Ar number
355Delete the break point.
356The target break point can be specified by a
357break point number with
358.Ql # ,
359or by using the same
360.Ar addr
361specified in the original
362.Ic break
363command.
364.Pp
365.It Ic watch Ar addr Ns Li , Ns Ar size
366Set a watchpoint for a region.
367Execution stops when an attempt to modify the region occurs.
368The
369.Ar size
370argument defaults to 4.
371If you specify a wrong space address, the request is rejected
372with an error message.
373.Pp
374.Sy Warning :
375Attempts to watch wired kernel memory
376may cause unrecoverable error in some systems such as i386.
377Watchpoints on user addresses work best.
378.Pp
379.It Ic hwatch Ar addr Ns Li , Ns Ar size
380Set a hardware watchpoint for a region if supported by the
381architecture.
382Execution stops when an attempt to modify the region occurs.
383The
384.Ar size
385argument defaults to 4.
386.Pp
387.Sy Warning :
388The hardware debug facilities do not have a concept of separate
389address spaces like the watch command does.
390Use
391.Ic hwatch
392for setting watchpoints on kernel address locations only, and avoid
393its use on user mode address spaces.
394.Pp
395.It Ic dhwatch Ar addr Ns Li , Ns Ar size
396Delete specified hardware watchpoint.
397.Pp
398.It Ic step Ns Op Li / Ns Cm p
399.It Ic s Ns Op Li / Ns Cm p
400Single step
401.Ar count
402times (the comma is a mandatory part of the syntax).
403If the
404.Cm p
405modifier is specified, print each instruction at each step.
406Otherwise, only print the last instruction.
407.Pp
408.Sy Warning :
409depending on machine type, it may not be possible to
410single-step through some low-level code paths or user space code.
411On machines with software-emulated single-stepping (e.g., pmax),
412stepping through code executed by interrupt handlers will probably
413do the wrong thing.
414.Pp
415.It Ic continue Ns Op Li / Ns Cm c
416.It Ic c Ns Op Li / Ns Cm c
417Continue execution until a breakpoint or watchpoint.
418If the
419.Cm c
420modifier is specified, count instructions while executing.
421Some machines (e.g., pmax) also count loads and stores.
422.Pp
423.Sy Warning :
424when counting, the debugger is really silently single-stepping.
425This means that single-stepping on low-level code may cause strange
426behavior.
427.Pp
428.It Ic until Ns Op Li / Ns Cm p
429Stop at the next call or return instruction.
430If the
431.Cm p
432modifier is specified, print the call nesting depth and the
433cumulative instruction count at each call or return.
434Otherwise,
435only print when the matching return is hit.
436.Pp
437.It Ic next Ns Op Li / Ns Cm p
438.It Ic match Ns Op Li / Ns Cm p
439Stop at the matching return instruction.
440If the
441.Cm p
442modifier is specified, print the call nesting depth and the
443cumulative instruction count at each call or return.
444Otherwise, only print when the matching return is hit.
445.Pp
446.It Xo
447.Ic trace Ns Op Li / Ns Cm u
448.Op Ar pid | tid
449.Op Li , Ns Ar count
450.Xc
451.It Xo
452.Ic t Ns Op Li / Ns Cm u
453.Op Ar pid | tid
454.Op Li , Ns Ar count
455.Xc
456.It Xo
457.Ic where Ns Op Li / Ns Cm u
458.Op Ar pid | tid
459.Op Li , Ns Ar count
460.Xc
461.It Xo
462.Ic bt Ns Op Li / Ns Cm u
463.Op Ar pid | tid
464.Op Li , Ns Ar count
465.Xc
466Stack trace.
467The
468.Cm u
469option traces user space; if omitted,
470.Ic trace
471only traces
472kernel space.
473The optional argument
474.Ar count
475is the number of frames to be traced.
476If
477.Ar count
478is omitted, all frames are printed.
479.Pp
480.Sy Warning :
481User space stack trace is valid
482only if the machine dependent code supports it.
483.Pp
484.It Xo
485.Ic search Ns Op Li / Ns Cm bhl
486.Ar addr
487.Ar value
488.Op Ar mask
489.Op Li , Ns Ar count
490.Xc
491Search memory for
492.Ar value .
493This command might fail in interesting
494ways if it does not find the searched-for value.
495This is because
496.Nm
497does not always recover from touching bad memory.
498The optional
499.Ar count
500argument limits the search.
501.Pp
502.It Ic show Cm all procs Ns Op Li / Ns Cm m
503.It Ic ps Ns Op Li / Ns Cm m
504Display all process information.
505The process information may not be shown if it is not
506supported in the machine, or the bottom of the stack of the
507target process is not in the main memory at that time.
508The
509.Cm m
510modifier will alter the display to show VM map
511addresses for the process and not show other info.
512.Pp
513.It Ic show Cm registers Ns Op Li / Ns Cm u
514Display the register set.
515If the
516.Cm u
517modifier is specified, it displays user registers instead of
518kernel or currently saved one.
519.Pp
520.Sy Warning :
521The support of the
522.Cm u
523modifier depends on the machine.
524If not supported, incorrect information will be displayed.
525.Pp
526.It Ic show Cm sysregs
527Show system registers (e.g.,
528.Li cr0-4
529on i386.)
530Not present on some platforms.
531.Pp
532.It Ic show Cm geom Op Ar addr
533If the
534.Ar addr
535argument is not given, displays the entire GEOM topology.
536If the
537.Ar addr
538is given, displays details about the given GEOM object (class, geom, provider
539or consumer).
540.Pp
541.It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr
542Prints the VM map at
543.Ar addr .
544If the
545.Cm f
546modifier is specified the
547complete map is printed.
548.Pp
549.It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr
550Prints the VM object at
551.Ar addr .
552If the
553.Cm f
554option is specified the
555complete object is printed.
556.Pp
557.It Ic show Cm vnode Ar addr
558Displays details about the given vnode.
559.Pp
560.It Ic show Cm watches
561Displays all watchpoints.
562.Pp
563.It Ic gdb
564Toggles between remote GDB and DDB mode.
565In remote GDB mode, another machine is required that runs
566.Xr gdb 1
567using the remote debug feature, with a connection to the serial
568console port on the target machine.
569Currently only available on the
570i386
571architecture.
572.Pp
573.It Ic halt
574Halt the system.
575.Pp
576.It Ic kill Ar sig pid
577Send signal
578.Ar sig
579to process
580.Ar pid .
581The signal is acted on upon returning from the debugger.
582This command can be used to kill a process causing resource contention
583in the case of a hung system.
584See
585.Xr signal 3
586for a list of signals.
587Note that the arguments are reversed relative to
588.Xr kill 2 .
589.Pp
590.It Ic reboot
591.It Ic reset
592Hard reset the system.
593.Pp
594.It Ic help
595Print a short summary of the available commands and command
596abbreviations.
597.Pp
598.It Ic capture on
599.It Ic capture off
600.It Ic capture reset
601.It Ic capture status
602.Nm
603supports a basic output capture facility, which can be used to retrieve the
604results of debugging commands from userpsace using
605.Xr sysctl 2 .
606.Ic capture on
607enables output capture;
608.Ic capture off
609disables capture.
610.Ic capture reset
611will clear the capture buffer and disable capture.
612.Ic capture status
613will report current buffer use, buffer size, and disposition of output
614capture.
615.Pp
616Userspace processes may inspect and manage
617.Nm
618capture state using
619.Xr sysctl 8 :
620.Pp
621.Dv debug.ddb.capture.bufsize
622may be used to query or set the current capture buffer size.
623.Pp
624.Dv debug.ddb.capture.maxbufsize
625may be used to query the compile-time limit on the capture buffer size.
626.Pp
627.Dv debug.ddb.capture.bytes
628may be used to query the number of bytes of output currently in the capture
629buffer.
630.Pp
631.Dv debug.ddb.capture.data
632returns the contents of the buffer as a string to an appropriately privileged
633process.
634.Pp
635This facility is particularly useful in concert with the scripting and
636.Xr textdump 4
637facilities, allowing scripted debugging output to be captured and
638committed to disk as part of a textdump for later analysis.
639The contents of the capture buffer may also be inspected in a kernel core dump
640using
641.Xr kgdb 1 .
642.Pp
643.It Ic run
644.It Ic script
645.It Ic scripts
646.It Ic unscript
647Run, define, list, and delete scripts.
648See the
649.Sx SCRIPTING
650section for more information on the scripting facility.
651.Pp
652.It Ic textdump set
653.It Ic textdump status
654.It Ic textdump unset
655The
656.Ic textdump set
657command may be used to force the next kernel core dump to be a textdump
658rather than a traditional memory dump or minidump.
659.Ic textdump status
660reports whether a textdump has been scheduled.
661.Ic textdump unset
662cancels a request to perform a textdump as the next kernel core dump.
663More information may be found in
664.Xr textdump 4 .
665.El
666.Sh VARIABLES
667The debugger accesses registers and variables as
668.Li $ Ns Ar name .
669Register names are as in the
670.Dq Ic show Cm registers
671command.
672Some variables are suffixed with numbers, and may have some modifier
673following a colon immediately after the variable name.
674For example, register variables can have a
675.Cm u
676modifier to indicate user register (e.g.,
677.Dq Li $eax:u ) .
678.Pp
679Built-in variables currently supported are:
680.Pp
681.Bl -tag -width ".Va tabstops" -compact
682.It Va radix
683Input and output radix.
684.It Va maxoff
685Addresses are printed as
686.Dq Ar symbol Ns Li + Ns Ar offset
687unless
688.Ar offset
689is greater than
690.Va maxoff .
691.It Va maxwidth
692The width of the displayed line.
693.It Va lines
694The number of lines.
695It is used by the built-in pager.
696.It Va tabstops
697Tab stop width.
698.It Va work Ns Ar xx
699Work variable;
700.Ar xx
701can take values from 0 to 31.
702.El
703.Sh EXPRESSIONS
704Most expression operators in C are supported except
705.Ql ~ ,
706.Ql ^ ,
707and unary
708.Ql & .
709Special rules in
710.Nm
711are:
712.Bl -tag -width ".No Identifiers"
713.It Identifiers
714The name of a symbol is translated to the value of the symbol, which
715is the address of the corresponding object.
716.Ql \&.
717and
718.Ql \&:
719can be used in the identifier.
720If supported by an object format dependent routine,
721.Sm off
722.Oo Ar filename : Oc Ar func : lineno ,
723.Sm on
724.Oo Ar filename : Oc Ns Ar variable ,
725and
726.Oo Ar filename : Oc Ns Ar lineno
727can be accepted as a symbol.
728.It Numbers
729Radix is determined by the first two letters:
730.Ql 0x :
731hex,
732.Ql 0o :
733octal,
734.Ql 0t :
735decimal; otherwise, follow current radix.
736.It Li \&.
737.Va dot
738.It Li +
739.Va next
740.It Li ..
741address of the start of the last line examined.
742Unlike
743.Va dot
744or
745.Va next ,
746this is only changed by
747.Ic examine
748or
749.Ic write
750command.
751.It Li '
752last address explicitly specified.
753.It Li $ Ns Ar variable
754Translated to the value of the specified variable.
755It may be followed by a
756.Ql \&:
757and modifiers as described above.
758.It Ar a Ns Li # Ns Ar b
759A binary operator which rounds up the left hand side to the next
760multiple of right hand side.
761.It Li * Ns Ar expr
762Indirection.
763It may be followed by a
764.Ql \&:
765and modifiers as described above.
766.El
767.Sh SCRIPTING
768.Nm
769supports a basic scripting facility to allow automating tasks or responses to
770specific events.
771Each script consists of a list of DDB commands to be executed sequentially,
772and is assigned a unique name.
773Certain script names have special meaning, and will be automatically run on
774various
775.Nm
776events if scripts by those names have been defined.
777.Pp
778The
779.Ic script
780command may be used to define a script by name.
781Scripts consist of a series of
782.Nm
783commands separated with the
784.Ic ;
785character.
786For example:
787.Bd -literal -offset indent
788script kdb.enter.panic=bt; show pcpu
789script lockinfo=show alllocks; show lockedvnods
790.Ed
791.Pp
792The
793.Ic scripts
794command lists currently defined scripts.
795.Pp
796The
797.Ic run
798command execute a script by name.
799For example:
800.Bd -literal -offset indent
801run lockinfo
802.Ed
803.Pp
804The
805.Ic unscript
806command may be used to delete a script by name.
807For example:
808.Bd -literal -offset indent
809unscript kdb.enter.panic
810.Ed
811.Pp
812These functions may also be performed from userspace using the
813.Xr ddb 8
814command.
815.Pp
816Certain scripts are run automatically, if defined, for specific
817.Nm
818events.
819The follow scripts are run when various events occur:
820.Bl -tag -width kdb.enter.powerfail
821.It Dv kdb.enter.acpi
822The kernel debugger was entered as a result of an
823.Xr acpi 4
824event.
825.It Dv kdb.enter.bootflags
826The kernel debugger was entered at boot as a result of the debugger boot
827flag being set.
828.It Dv kdb.enter.break
829The kernel debugger was entered as a result of a serial or console break.
830.It Dv kdb.enter.cam
831The kernel debugger was entered as a result of a
832.Xr CAM 4
833event.
834.It Dv kdb.enter.mac
835The kernel debugger was entered as a result of an assertion failure in the
836.Xr mac_test 4
837module of the
838TrustedBSD MAC Framework.
839.It Dv kdb.enter.ndis
840The kernel debugger was entered as a result of an
841.Xr ndis 4
842breakpoint event.
843.It Dv kdb.enter.netgraph
844The kernel debugger was entered as a result of a
845.Xr netgraph 4
846event.
847.It Dv kdb.enter.panic
848.Xr panic 9
849was called.
850.It Dv kdb.enter.powerfail
851The kernel debugger was entered as a result of a powerfail NMI on the sparc64
852platform.
853.It Dv kdb.enter.powerpc
854The kernel debugger was entered as a result of an unimplemented interrupt
855type on the powerpc platform.
856.It Dv kdb.enter.sysctl
857The kernel debugger was entered as a result of the
858.Dv debug.kdb.enter
859sysctl being set.
860.It Dv kdb.enter.trapsig
861The kernel debugger was entered as a result of a trapsig event on the sparc64
862or sun4v platform.
863.It Dv kdb.enter.unionfs
864The kernel debugger was entered as a result of an assertion failure in the
865union file system.
866.It Dv kdb.enter.unknown
867The kernel debugger was entered, but no reason has been set.
868.It Dv kdb.enter.vfslock
869The kernel debugger was entered as a result of a VFS lock violation.
870.It Dv kdb.enter.watchdog
871The kernel debugger was entered as a result of a watchdog firing.
872.It Dv kdb.enter.witness
873The kernel debugger was entered as a result of a
874.Xr witness 4
875violation.
876.El
877.Pp
878In the event that none of these scripts is found,
879.Nm
880will attempt to execute a default script:
881.Bl -tag -width kdb.enter.powerfail
882.It Dv kdb.enter.default
883The kernel debugger was entered, but a script exactly matching the reason for
884entering was not defined.
885This can be used as a catch-all to handle cases not specifically of interest;
886for example,
887.Dv kdb.enter.witness
888might be defined to have special handling, and
889.Dv kdb.enter.default
890might be defined to simply panic and reboot.
891.El
892.Sh HINTS
893On machines with an ISA expansion bus, a simple NMI generation card can be
894constructed by connecting a push button between the A01 and B01 (CHCHK# and
895GND) card fingers.
896Momentarily shorting these two fingers together may cause the bridge chipset to
897generate an NMI, which causes the kernel to pass control to
898.Nm .
899Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary.
900The NMI allows one to break into the debugger on a wedged machine to
901diagnose problems.
902Other bus' bridge chipsets may be able to generate NMI using bus specific
903methods.
904.Sh SEE ALSO
905.Xr gdb 1 ,
906.Xr kgdb 1 ,
907.Xr acpi 4 ,
908.Xr CAM 4 ,
909.Xr mac_text 4 ,
910.Xr ndis 4 ,
911.Xr netgraph 4 ,
912.Xr textdump 4 ,
913.Xr witness 4 ,
914.Xr ddb 8 ,
915.Xr sysctl 8 ,
916.Xr panic 9
917.Sh HISTORY
918The
919.Nm
920debugger was developed for Mach, and ported to
921.Bx 386 0.1 .
922This manual page translated from
923.Xr man 7
924macros by
925.An Garrett Wollman .
926.Pp
927.An Robert N. M. Watson
928added support for
929.Nm
930output capture,
931.Xr textdump 4
932and scripting in
933.Fx 8.0 .
934