From d3a8a8e0759460ce1a0140a767e456c07e01a676 Mon Sep 17 00:00:00 2001 From: rwatson Date: Sun, 30 Mar 2008 17:10:35 +0000 Subject: [PATCH] Merge ddb.4:1.45 from HEAD to RELENG_7: Add SCRIPTING section to describe new DDB scripting facilities. Update copyright. --- share/man/man4/ddb.4 | 149 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 147 insertions(+), 2 deletions(-) diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4 index d6225e2129d..ea1d907eb17 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 -- 2.45.2