diff options
| -rw-r--r-- | share/man/man4/Makefile | 1 | ||||
| -rw-r--r-- | share/man/man4/ddb.4 | 31 | ||||
| -rw-r--r-- | share/man/man4/textdump.4 | 162 |
3 files changed, 194 insertions, 0 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 2241502..7e3abb7 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -355,6 +355,7 @@ MAN= aac.4 \ tcp.4 \ tdfx.4 \ termios.4 \ + textdump.4 \ ti.4 \ tl.4 \ trm.4 \ diff --git a/share/man/man4/ddb.4 b/share/man/man4/ddb.4 index ea1d907..2caae2d 100644 --- a/share/man/man4/ddb.4 +++ b/share/man/man4/ddb.4 @@ -632,6 +632,14 @@ buffer. 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 @@ -640,6 +648,20 @@ 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 @@ -881,6 +903,7 @@ Other bus' bridge chipsets may be able to generate NMI using bus specific methods. .Sh SEE ALSO .Xr gdb 1 , +.Xr kgdb 1 , .Xr acpi 4 , .Xr CAM 4 , .Xr mac_text 4 , @@ -900,3 +923,11 @@ This manual page translated from .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 . diff --git a/share/man/man4/textdump.4 b/share/man/man4/textdump.4 new file mode 100644 index 0000000..15fe517 --- /dev/null +++ b/share/man/man4/textdump.4 @@ -0,0 +1,162 @@ +.\" +.\" 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 16 December, 2007 +.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 dbeug.ddb.textdump.do_panic +sysctl. +.El +.Pp +Kernel textdumps may be extracted using +.Xr bsdtar 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=capture on;textdump set;bt;show allpcpu; + ps;alltrace;show alllock;panic +.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 +.Sh SEE ALSO +.Xr bsdtar 1 , +.Xr ddb 4 , +.Xr tar 5 , +.Xr dumpon 8 , +.Xr savecore 8 , +.Xr sysctl 8 +.Sh AUTHORS +The +.Nm +facility was created by +.An Robert N. M. Watson . |
