--- /usr/src/share/man/man4/ddb.4	Tue Dec 25 05:35:54 2007
+++ ddb.4	Wed Dec 26 12:13:40 2007
@@ -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
@@ -57,21 +58,44 @@
 .\" 	Created.
 .\" 	[90/08/30            dbg]
 .\"
-.\" $FreeBSD: src/share/man/man4/ddb.4,v 1.43 2007/12/25 23:25:04 rwatson Exp $
+.\" $FreeBSD: src/share/man/man4/ddb.4,v 1.46 2007/12/26 11:35:06 rwatson Exp $
 .\"
-.Dd December 25, 2007
+.Dd December 26, 2007
 .Dt DDB 4
 .Os
 .Sh NAME
 .Nm ddb
 .Nd interactive kernel debugger
 .Sh SYNOPSIS
+In order to enable kernel debugging facilities include:
+.Bd -ragged -offset indent
 .Cd options KDB
 .Cd options DDB
+.Ed
 .Pp
 To prevent activation of the debugger on kernel
 .Xr panic 9 :
+.Bd -ragged -offset indent
 .Cd options KDB_UNATTENDED
+.Ed
+.Pp
+In order to print a stack trace of the current thread on the console
+for a panic;
+.Bd -ragged -offset indent
+.Cd options KDB_TRACE
+.Ed
+.Pp
+To print the numerical value of symbols in addition to the symbolic
+representation, define:
+.Bd -ragged -offset indent
+.Cd options DDB_NUMSYM
+.Ed
+.Pp
+To enable gdb(1) backend, so that remote debugging with kgdb(1) possible,
+include:
+.Bd -ragged -offset indent
+.Cd options GDB
+.Ed
 .Sh DESCRIPTION
 The
 .Nm
@@ -497,6 +521,7 @@
 The optional
 .Ar count
 argument limits the search.
+.\"
 .Pp
 .It Ic show Cm all procs Ns Op Li / Ns Cm m
 .It Ic ps Ns Op Li / Ns Cm m
@@ -508,25 +533,77 @@
 .Cm m
 modifier will alter the display to show VM map
 addresses for the process and not show other info.
+.\"
 .Pp
-.It Ic show Cm registers Ns Op Li / Ns Cm u
-Display the register set.
-If the
-.Cm u
-modifier is specified, it displays user registers instead of
-kernel or currently saved one.
+.It Ic show Cm allchains
+Show the same information like "show lockchain" does, but
+for every thread in the system.
+.\"
 .Pp
-.Sy Warning :
-The support of the
-.Cm u
-modifier depends on the machine.
-If not supported, incorrect information will be displayed.
+.It Ic show Cm alllocks
+Show all locks that are currently held.
+.\"
 .Pp
-.It Ic show Cm sysregs
-Show system registers (e.g.,
-.Li cr0-4
-on i386.)
-Not present on some platforms.
+.It Ic show Cm allpcpu
+The same as "show pcpu", but for every CPU present in the system.
+.\"
+.Pp
+.It Ic show Cm allrman
+Show information related with resource management, including
+interrupt request lines, DMA request lines, I/O ports and I/O memory
+addresses.
+.\"
+.Pp
+.It Ic show Cm apic
+Dump data about APIC IDT vector mappings.
+.\"
+.Pp
+.It Ic show Cm breaks
+Show breakpoints set with "break" command.
+.\"
+.Pp
+.It Ic show Cm buffer
+Show buffer structure of
+.Vt struct buf
+type. Such structure is used within
+the FreeBSD kernel for I/O subsystem implementation. For exact
+interpretation of output, please visit
+.Pa buf.h
+header file.
+.\"
+.Pp
+.It Ic show Cm cbstat
+Show brief information about TTY subsystem.
+.\"
+.Pp
+.It Ic show Cm cyrixreg
+Show registers specific for the Cyrix processor.
+.\"
+.Pp
+.It Ic show Cm domain Ar addr
+Print protocol domain structure
+.Vt struct domain
+at address
+.Ar addr .
+See
+.Pa domain.h
+header file for more details on exact meaning of the structure fields.
+.\"
+.Pp
+.It Ic show Cm file Ar addr
+Show information about file structure
+.Vt struct file
+present at address
+.Ar addr .
+.\"
+.Pp
+.It Ic show Cm files
+Show information about every file structure in the system.
+.\"
+.Pp
+.It Ic show Cm freepages
+Show the number of physical pages in each of the free lists.
+.\"
 .Pp
 .It Ic show Cm geom Op Ar addr
 If the
@@ -536,6 +613,106 @@
 .Ar addr
 is given, displays details about the given GEOM object (class, geom, provider
 or consumer).
+.\"
+.Pp
+.It Ic show Cm idt
+Show IDT layout. First column specifies IDT vector. The second one is a
+name of the interrupt/trap handler. Those functions are machine dependent.
+.\"
+.Pp
+.It Ic show Cm inpcb Ar addr
+Show information on IP Control Block
+.Vt struct in_pcb
+present at
+.Ar addr .
+.\"
+.Pp
+.It Ic show Cm intr
+Dump information about interrupt handlers.
+.\"
+.Pp
+.It Ic show Cm intrcnt
+Dump the interrupt statistics.
+.\"
+.Pp
+.It Ic show Cm irqs
+Show interrupt lines and their respective kernel threads.
+.\"
+.Pp
+.It Ic show Cm lapic
+Show information from the local APIC registers for this CPU.
+.\"
+.Pp
+.It Ic show Cm lock Ar addr
+Show lock structure. Output format is as follows:
+.Bl -tag -offset 0 -width "flags"
+.It Ic class:
+Class of a lock. Possible types include
+.Xr mutex 9 ,
+.Xr rmlock 9 ,
+.Xr rwlock 9 ,
+.Xr sx 9 .
+.It Ic name:
+Name of the lock.
+.It Ic flags:
+Flags passed to the lock initialization function. For exact possibilities
+see manual pages of possible lock types.
+.It Ic state:
+Current state of a lock. As well as
+.Ic flags
+it's lock-specific.
+.It Ic owner:
+Lock owner.
+.El
+.\"
+.Pp
+.It Ic show Cm lockchain Ar addr
+Show all the threads a particular thread at address
+.Ar addr
+is waiting on based on non-sleepable and non-spin locks.
+.\"
+.Pp
+.It Ic show Cm lockedbufs
+Show the same information like "show buf", but for every locked
+.Vt struct buf
+object.
+.\"
+.Pp
+.It Ic show Cm lockedvnods
+List all of the locked vnodes in the system.
+.\"
+.Pp
+.It Ic show Cm locks
+Prints all locks that are currently acquired.
+.\"
+.Pp
+.It Ic show Cm locktree
+.\"
+.Pp
+.It Ic show Cm malloc
+Prints malloc(9) memory allocator statistics. The output format is as
+follows:
+.Pp
+.Bl -tag -compact -offset indent -width "Requests"
+.It Ic Type
+Specifies a type of memory. It's the same as a description
+string used while defining given memory type with
+.Xr MALLOC_DECLARE(9) .
+.It Ic InUse
+Number of memory allocations of given type, for which
+.Xr free 9
+hasn't been called yet.
+.It Ic MemUse
+Total memory consumed by given allocation type.
+.It Ic Requests
+Number of memory allocation requests for given
+memory type.
+.El
+.Pp
+The same information can be gathered in the userspace with
+.Dq Nm vmstat Fl m
+tool.
+.\"
 .Pp
 .It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr
 Prints the VM map at
@@ -544,6 +721,14 @@
 .Cm f
 modifier is specified the
 complete map is printed.
+.\"
+.Pp
+.It Ic show Cm msgbuf
+Print system's message buffer. It's the same output as in
+.Dq Nm dmesg
+case. It's useful if you got a kernel panic, attached serial cable
+to the machine and want to get boot messages before system hang.
+.\"
 .Pp
 .It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr
 Prints the VM object at
@@ -552,12 +737,244 @@
 .Cm f
 option is specified the
 complete object is printed.
+.\"
+.Pp
+.It Ic show Cm page
+Show statistics on VM pages.
+.\"
+.Pp
+.It Ic show Cm pageq
+Show statistics on VM page queues.
+.\"
+.Pp
+.It Ic show Cm pciregs
+Print PCI bus registers. The same information can be gathered in the
+userspace by running
+.Dq Nm pciconf Fl lv .
+.\"
+.Pp
+.It Ic show Cm pcpu
+Print current processor state. Output format is as follows:
+.Pp
+.Bl -tag -compact -offset indent -width "spin locks held:"
+.It Ic cpuid
+Processor identifier.
+.It Ic curthread
+Thread pointer, process identifier and a name of the process.
+.It Ic curpcb
+Control block pointer.
+.It Ic fpcurthread
+FPU thread pointer.
+.It Ic idlethread
+Idle thread pointer.
+.It Ic APIC ID
+CPU identifier coming from APIC.
+.It Ic currentldt
+LDT pointer.
+.It Ic spin locks held
+Names of spin locks held.
+.El
+.\"
+.Pp
+.It Ic show Cm pgrpdump
+Dump process groups present within the system.
+.\"
+.Pp
+.It Ic show Cm proc Op Ar addr
+If no
+.Op Ar addr
+is specified, print information about the current process.
+Otherwise, show information about process at address
+.Ar addr .
+.\"
+.Pp
+.It Ic show Cm procvm
+Show process virtual memory layout.
+.\"
+.Pp
+.It Ic show Cm protosw Ar addr
+Print protocol switch structure
+.Vt struct protosw
+at address
+.Ar addr .
+.\"
+.Pp
+.It Ic show Cm registers Ns Op Li / Ns Cm u
+Display the register set.
+If the
+.Cm u
+modifier is specified, it displays user registers instead of
+kernel or currently saved one.
+.Pp
+.Sy Warning :
+The support of the
+.Cm u
+modifier depends on the machine.
+If not supported, incorrect information will be displayed.
+.\"
+.Pp
+.It Ic show Cm rman Ar addr
+Show resource manager object
+.Vt struct rman
+at address
+.Ar addr .
+Addresses of particular pointers can be gathered with "show allrman"
+command.
+.\"
+.Pp
+.It Ic show Cm rtc
+Show real time clock value. Useful for long debugging sessions.
+.\"
+.Pp
+.It Ic show Cm sleepchain
+Show all the threads a particular thread is waiting on based on
+sleepable locks.             
+.\"
+.Pp
+.It Ic show Cm sleepq
+.It Ic show Cm sleepqueue
+Both commands provide the same funcitonality. They show sleepqueue
+.Vt struct sleepqueue
+structure. Sleepqueues are used within the FreeBSD kernel to implement
+sleepable synchronization primitives (thread holding a lock might sleep or
+be contexted switched), which at the time of writing are:
+.Xr condvar 9 ,
+.Xr sx 9
+and standard
+.Xr msleep 9
+interface.
+.\"
+.Pp
+.It Ic show Cm sockbuf Ar addr
+.It Ic show Cm socket Ar addr
+Those commands print
+.Vt struct sockbuf
+and
+.Vt struct socket
+objects placed at
+.Ar addr .
+Output consist of all values present in structures mentioned.
+For exact interpretation and more details, visit
+.Pa socket.h
+header file.
+.\"
+.Pp
+.It Ic show Cm sysregs
+Show system registers (e.g.,
+.Li cr0-4
+on i386.)
+Not present on some platforms.
+.\"
+.Pp
+.It Ic show Cm tcpcb Ar addr
+Print TCP control block
+.Vt struct tcpcb
+lying at address
+.Ar addr .
+For exact interpretation of output, visit
+.Pa tcp.h
+header file.
+.\"
+.Pp
+.It Ic show Cm thread Op Ar addr
+If no
+.Ar addr
+is specified, show detailed information about current thread.
+Otherwise, information about thread at
+.Ar addr
+is printed.
+.\"
+.Pp
+.It Ic show Cm threads
+Show all threads within the system. Output format is as follows:
+.Pp
+.Bl -tag -width "PPID" -compact -offset indent -width "Second column"
+.It Ic First column
+Thread identifier (TID)
+.It Ic Second column
+Thread structure address
+.It Ic Third column
+Backtrace.
+.El
+.\"
+.Pp
+.It Ic show Cm turnstile Ar addr
+Show turnstile
+.Vt struct turnstile
+structure at address
+.Ar addr .
+Turnstiles are structures used within the FreeBSD kernel to implement
+synchronization primitives which, while holding specific type of lock, can't
+sleep or context switch to another thread. Currently, those are:
+.Xr mutex 9 ,
+.Xr rwlock 9 ,
+.Xr rmlock 9 .
+.\"
+.Pp
+.It Ic show Cm uma
+Show UMA allocator statistics. Output consists five columns:
+.Pp
+.Bl -tag -compact -offset indent -width "Requests"
+.It Cm "Zone"
+Name of the UMA zone. The same string that was passed
+to
+.Xr uma_zcreate 9
+as a first argument.
+.It Cm "Size"
+Size of a given memory object (slab).
+.It Cm "Used"
+Number of slabs being currently used.
+.It Cm "Free"
+Number of free slabs within the UMA zone.
+.It Cm "Requests"
+Number of allocations requests to the given zone.
+.El
+.Pp
+The very same information might be gathered in the userspace
+with the help of
+.Dq Nm vmstat Fl z
+.\"
+.Pp
+.It Ic show Cm unpcb Ar addr
+Shows UNIX domain socket private control block
+.Vt struct unpcb
+present at the address
+.Ar addr
+.\"
+.Pp
+.It Ic show Cm vmochk
+Prints, whether the internal VM objects are in a map somewhere
+and none have zero ref counts.
+.\"
+.Pp
+.It Ic show Cm vmopag
+This is supposed to show physical addresses consumed by a 
+VM object. Currently, it's not possible to use this command
+when
+.Xr witness 9
+is compiled in the kernel.
+.\"
 .Pp
-.It Ic show Cm vnode Ar addr
-Displays details about the given vnode.
+.It Ic show Cm vnode Op Ar addr
+Prints vnode 
+.Vt struct vnode
+structure lying at
+.Op Ar addr .
+For exact interpretation of output, visit
+.Pa vnode.h
+header file.
+.\"
 .Pp
 .It Ic show Cm watches
 Displays all watchpoints.
+Shows watchpoints set with "watch" command.
+.\"
+.Pp
+.It Ic show Cm witness
+Shows information about lock acquisition coming from
+.Xr witness 9
+subsystem.
+.\"
 .Pp
 .It Ic gdb
 Toggles between remote GDB and DDB mode.
@@ -626,6 +1043,41 @@
 .Dv debug.ddb.capture.bytes
 may be used to query the number of bytes of output currently in the capture
 buffer.
+.Pp
+.Dv debug.ddb.capture.data
+returns the contents of the buffer as a string to an appropriately privileged
+process.
+.Pp
+This facility is particularly useful in concert with the scripting and
+.Xr textdump 4
+facilities, allowing scripted debugging output to be captured and
+committed to disk as part of a textdump for later analysis.
+The contents of the capture buffer may also be inspected in a kernel core dump
+using
+.Xr kgdb 1 .
+.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.
+.Pp
+.It Ic textdump set
+.It Ic textdump status
+.It Ic textdump unset
+The
+.Ic textdump set
+command may be used to force the next kernel core dump to be a textdump
+rather than a traditional memory dump or minidump.
+.Ic textdump status
+reports whether a textdump has been scheduled.
+.Ic textdump unset
+cancels a request to perform a textdump as the next kernel core dump.
+More information may be found in
+.Xr textdump 4 .
 .El
 .Sh VARIABLES
 The debugger accesses registers and variables as
@@ -728,6 +1180,131 @@
 .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
@@ -740,8 +1317,36 @@
 diagnose problems.
 Other bus' bridge chipsets may be able to generate NMI using bus specific
 methods.
+.Sh FILES
+Header files mention in this manual page can be found below
+.Pa /usr/include
+directory.
+.Pp
+.Bl -dash -compact
+.It
+.Pa buf.h
+.It
+.Pa domain.h
+.It
+.Pa in_pcb.h
+.It
+.Pa socket
+.It
+.Pa vnode.h
+.El
 .Sh SEE ALSO
-.Xr gdb 1
+.Xr CAM 4 ,
+.Xr acpi 4 ,
+.Xr ddb 8 ,
+.Xr gdb 1 ,
+.Xr kgdb 1 ,
+.Xr mac_text 4 ,
+.Xr ndis 4 ,
+.Xr netgraph 4 ,
+.Xr panic 9 ,
+.Xr sysctl 8 ,
+.Xr textdump 4 ,
+.Xr witness 4 ,
 .Sh HISTORY
 The
 .Nm
@@ -751,3 +1356,11 @@
 .Xr man 7
 macros by
 .An Garrett Wollman .
+.Pp
+.An Robert N. M. Watson
+added support for
+.Nm
+output capture,
+.Xr textdump 4
+and scripting in
+.Fx 8.0 .