diff options
author | rwatson <rwatson@FreeBSD.org> | 2007-12-26 09:51:37 +0000 |
---|---|---|
committer | rwatson <rwatson@FreeBSD.org> | 2007-12-26 09:51:37 +0000 |
commit | 7dfa1b8f6b375b0f3502f02fdd160f605e00a208 (patch) | |
tree | a8c31d97c6ba8ae92f6c7c5482d09701195f2ff0 /share/man/man4/ddb.4 | |
parent | d70c7cc6e10dd446fdba622e73ff0f109a4a5311 (diff) | |
download | FreeBSD-src-7dfa1b8f6b375b0f3502f02fdd160f605e00a208.zip FreeBSD-src-7dfa1b8f6b375b0f3502f02fdd160f605e00a208.tar.gz |
Add SCRIPTING section to describe new DDB scripting facilities.
Update copyright.
Diffstat (limited to 'share/man/man4/ddb.4')
-rw-r--r-- | share/man/man4/ddb.4 | 149 |
1 files changed, 147 insertions, 2 deletions
diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4 index d6225e2..ea1d907 100644 --- a/share/man/man4/ddb.4 +++ b/share/man/man4/ddb.4 @@ -1,6 +1,7 @@ .\" .\" Mach Operating System .\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" Copyright (c) 2007 Robert N. M. Watson .\" All Rights Reserved. .\" .\" Permission to use, copy, modify and distribute this software and its @@ -59,7 +60,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 25, 2007 +.Dd December 26, 2007 .Dt DDB 4 .Os .Sh NAME @@ -630,6 +631,15 @@ buffer. .Dv debug.ddb.capture.data returns the contents of the buffer as a string to an appropriately privileged process. +.Pp +.It Ic run +.It Ic script +.It Ic scripts +.It Ic unscript +Run, define, list, and delete scripts. +See the +.Sx SCRIPTING +section for more information on the scripting facility. .El .Sh VARIABLES The debugger accesses registers and variables as @@ -732,6 +742,131 @@ It may be followed by a .Ql \&: and modifiers as described above. .El +.Sh SCRIPTING +.Nm +supports a basic scripting facility to allow automating tasks or responses to +specific events. +Each script consists of a list of DDB commands to be executed sequentially, +and is assigned a unique name. +Certain script names have special meaning, and will be automatically run on +various +.Nm +events if scripts by those names have been defined. +.Pp +The +.Ic script +command may be used to define a script by name. +Scripts consist of a series of +.Nm +commands separated with the +.Ic ; +character. +For example: +.Bd -literal -offset indent +script kdb.enter.panic=bt;show pcpu +script lockinfo=show alllocks;show lockedvnods +.Ed +.Pp +The +.Ic scripts +command lists currently defined scripts. +.Pp +The +.Ic run +command execute a script by name. +For example: +.Bd -literal -offset indent +run lockinfo +.Ed +.Pp +The +.Ic unscript +command may be used to delete a script by name. +For example: +.Bd -literal -offset indent +unscript kdb.enter.panic +.Ed +.Pp +These functions may also be performed from userspace using the +.Xr ddb 8 +command. +.Pp +Certain scripts are run automatically, if defined, for specific +.Nm +events. +The follow scripts are run when various events occur: +.Bl -tag -width kdb.enter.powerfail +.It Dv kdb.enter.acpi +The kernel debugger was entered as a result of an +.Xr acpi 4 +event. +.It Dv kdb.enter.bootflags +The kernel debugger was entered at boot as a result of the debugger boot +flag being set. +.It Dv kdb.enter.break +The kernel debugger was entered as a result of a serial or console break. +.It Dv kdb.enter.cam +The kernel debugger was entered as a result of a +.Xr CAM 4 +event. +.It Dv kdb.enter.mac +The kernel debugger was entered as a result of an assertion failure in the +.Xr mac_test 4 +module of the +TrustedBSD MAC Framework. +.It Dv kdb.enter.ndis +The kernel debugger was entered as a result of an +.Xr ndis 4 +breakpoint event. +.It Dv kdb.enter.netgraph +The kernel debugger was entered as a result of a +.Xr netgraph 4 +event. +.It Dv kdb.enter.panic +.Xr panic 9 +was called. +.It Dv kdb.enter.powerfail +The kernel debugger was entered as a result of a powerfail NMI on the sparc64 +platform. +.It Dv kdb.enter.powerpc +The kernel debugger was entered as a result of an unimplemented interrupt +type on the powerpc platform. +.It Dv kdb.enter.sysctl +The kernel debugger was entered as a result of the +.Dv debug.kdb.enter +sysctl being set. +.It Dv kdb.enter.trapsig +The kernel debugger was entered as a result of a trapsig event on the sparc64 +or sun4v platform. +.It Dv kdb.enter.unionfs +The kernel debugger was entered as a result of an assertion failure in the +union file system. +.It Dv kdb.enter.unknown +The kernel debugger was entered, but no reason has been set. +.It Dv kdb.enter.vfslock +The kernel debugger was entered as a result of a VFS lock violation. +.It Dv kdb.enter.watchdog +The kernel debugger was entered as a result of a watchdog firing. +.It Dv kdb.enter.witness +The kernel debugger was entered as a result of a +.Xr witness 4 +violation. +.El +.Pp +In the event that none of these scripts is found, +.Nm +will attempt to execute a default script: +.Bl -tag -width kdb.enter.powerfail +.It Dv kdb.enter.default +The kernel debugger was entered, but a script exactly matching the reason for +entering was not defined. +This can be used as a catch-all to handle cases not specifically of interest; +for example, +.Dv kdb.enter.witness +might be defined to have special handling, and +.Dv kdb.enter.default +might be defined to simply panic and reboot. +.El .Sh HINTS On machines with an ISA expansion bus, a simple NMI generation card can be constructed by connecting a push button between the A01 and B01 (CHCHK# and @@ -745,7 +880,17 @@ diagnose problems. Other bus' bridge chipsets may be able to generate NMI using bus specific methods. .Sh SEE ALSO -.Xr gdb 1 +.Xr gdb 1 , +.Xr acpi 4 , +.Xr CAM 4 , +.Xr mac_text 4 , +.Xr ndis 4 , +.Xr netgraph 4 , +.Xr textdump 4 , +.Xr witness 4 , +.Xr ddb 8 , +.Xr sysctl 8 , +.Xr panic 9 .Sh HISTORY The .Nm |