1 files changed, 172 insertions, 0 deletions
diff --git a/share/man/man4/textdump.4 b/share/man/man4/textdump.4
new file mode 100644
index 000000000000..65c04edfd00c
--- /dev/null
+++ b/share/man/man4/textdump.4
@@ -0,0 +1,172 @@
+.\"
+.\" Copyright (c) 2007 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 24, 2008
+.Dt textdump 4
+.Os
+.Sh NAME
+.Nm textdump
+.Nd textdump kernel dumping facility
+.Sh SYNOPSIS
+.Cd options KDB
+.Cd options DDB
+.Sh DESCRIPTION
+The
+.Nm
+facility allows the capture of kernel debugging information to disk in a
+human-readable rather than the machine-readable form normally used with
+kernel memory dumps and minidumps.
+This representation, while less complete in that it does not capture full
+kernel state, can provide debugging information in a more compact, portable,
+and persistent form than a traditional dump.
+By combining
+.Nm
+with other
+.Xr ddb 4
+facilities, such as scripting and output capture, detailed bug information
+can be captured in a fully automated manner.
+.Sh FORMAT
+.Nm
+data is stored in a dump partition in the same style as a regular memory
+dump, and will be automatically extracted by
+.Xr savecore 8
+if present on boot.
+.Pp
+.Nm
+files are stored in the
+.Xr tar 5
+format, and consist of one or more text files, each storing a particular type
+of debugging output.
+The following parts may be present:
+.Bl -tag -width version.txt
+.It Pa ddb.txt
+Captured
+.Xr ddb 4
+output, if the capture facility has been used.
+May be disabled by clearing the
+.Dv debug.ddb.textdump.do_ddb
+sysctl.
+.It Pa config.txt
+Kernel configuration, if
+.Od options INCLUDE_CONFIG_FILE
+has been compiled into the kernel.
+May be disabled by clearing the
+.Dv debug.ddb.textdump.do_config
+sysctl.
+.It Pa msgbuf.txt
+Kernel message buffer, including recent console output if the capture
+facility has been used.
+May be disabled by clearing the
+.Dv debug.ddb.textdump.do_msgbuf
+sysctl.
+.It Pa panic.txt
+Kernel panic string, if the kernel panicked before the dump was generated.
+May be disabled by clearing the
+.Dv debug.ddb.textdump.do_panic
+sysctl.
+.It Pa version.txt
+Kernel version string.
+My be disabled by clearing the
+.Dv debug.ddb.textdump.do_version
+sysctl.
+.El
+.Pp
+Kernel textdumps may be extracted using
+.Xr tar 1 .
+.Sh CONFIGURATION
+The
+.Nm
+facility is enabled as part of the kernel debugger using
+.Cd options KDB
+and
+.Cd options DDB .
+By default, kernel dumps generated on panic or via explicit requests for a
+dump will be regular memory dumps; however, by using the
+.Ic textdump set
+command in
+.Xr ddb 4 ,
+or by setting the
+.Dv debug.ddb.textdump.pending
+sysctl to 1 using
+.Xr sysctl 8 ,
+it is possible to request that the next dump be a textdump.
+.Pp
+If at the
+.Xr ddb 4
+command line, the commands
+.Ic textdump set ,
+.Ic textdump status ,
+and
+.Ic textdump unset
+may be used to set, query, and clear the textdump pending flag.
+.Pp
+As with regular kernel dumps, a dump partition must be automatically or
+manually configured using
+.Xr dumpon 8 .
+.Sh EXAMPLES
+In the following example, the script
+.Dv kdb.enter.panic
+will run when the kernel debugger is entered as a result of a panic, enable
+output capture, dump several useful pieces of debugging information, and then
+invoke panic in order to force a kernel dump to be written out followed by a
+reboot:
+.Bd -literal -offset indent
+script kdb.enter.panic=textdump set; capture on; show allpcpu; bt;
+  ps; alltrace; show alllock; call doadump; reset
+.Ed
+.Pp
+In the following example, the script
+.Dv kdb.enter.witness
+will run when the kernel debugger is entered as a result of a witness
+violation, printing lock-related information for the user:
+.Bd -literal -offset indent
+script kdb.enter.witness=show locks
+.Ed
+.Pp
+These scripts may also be configured using the
+.Xr ddb 8
+utility.
+.Sh SEE ALSO
+.Xr tar 1 ,
+.Xr ddb 4 ,
+.Xr tar 5 ,
+.Xr ddb 8 ,
+.Xr dumpon 8 ,
+.Xr savecore 8 ,
+.Xr sysctl 8
+.Sh HISTORY
+The
+.Nm
+facility first appeared in
+.Fx 7.1 .
+.Sh AUTHORS
+The
+.Nm
+facility was created by
+.An Robert N. M. Watson .