d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add textdump(4) man page to describe the textdump facility and provide

Browse Source 
some stock formulas for use.

Update ddb(4) to reference the textdump(4) page, list the textdump
commands, and suggest using them with scripts and output capture.
Update HISTORY section.

Hook up textdump(4) to build.

MFC after:	3 months
This commit is contained in:
rwatson 2007-12-26 11:35:07 +00:00
parent 956e2983ba
commit be34549aa9
3 changed files with 194 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
share/man/man4/Makefile
View File

@ -355,6 +355,7 @@ MAN= aac.4 \
tcp.4 \
tdfx.4 \
termios.4 \
textdump.4 \
ti.4 \
tl.4 \
trm.4 \

31
share/man/man4/ddb.4
View File

@ -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 .

162
share/man/man4/textdump.4 Normal file
View File

@ -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 .