10ff94fb6SRobert Watson.\" 20ff94fb6SRobert Watson.\" Copyright (c) 2007 Robert N. M. Watson 30ff94fb6SRobert Watson.\" All rights reserved. 40ff94fb6SRobert Watson.\" 50ff94fb6SRobert Watson.\" Redistribution and use in source and binary forms, with or without 60ff94fb6SRobert Watson.\" modification, are permitted provided that the following conditions 70ff94fb6SRobert Watson.\" are met: 80ff94fb6SRobert Watson.\" 1. Redistributions of source code must retain the above copyright 90ff94fb6SRobert Watson.\" notice(s), this list of conditions and the following disclaimer as 100ff94fb6SRobert Watson.\" the first lines of this file unmodified other than the possible 110ff94fb6SRobert Watson.\" addition of one or more copyright notices. 120ff94fb6SRobert Watson.\" 2. Redistributions in binary form must reproduce the above copyright 130ff94fb6SRobert Watson.\" notice(s), this list of conditions and the following disclaimer in the 140ff94fb6SRobert Watson.\" documentation and/or other materials provided with the distribution. 150ff94fb6SRobert Watson.\" 160ff94fb6SRobert Watson.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 170ff94fb6SRobert Watson.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 180ff94fb6SRobert Watson.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 190ff94fb6SRobert Watson.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 200ff94fb6SRobert Watson.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 210ff94fb6SRobert Watson.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 220ff94fb6SRobert Watson.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 230ff94fb6SRobert Watson.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 240ff94fb6SRobert Watson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 250ff94fb6SRobert Watson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 260ff94fb6SRobert Watson.\" DAMAGE. 270ff94fb6SRobert Watson.\" 280ff94fb6SRobert Watson.\" $FreeBSD$ 290ff94fb6SRobert Watson.\" 30138f7e4bSTom Rhodes.Dd December 24, 2008 31134d45e8SUlrich Spörlein.Dt TEXTDUMP 4 320ff94fb6SRobert Watson.Os 330ff94fb6SRobert Watson.Sh NAME 340ff94fb6SRobert Watson.Nm textdump 350ff94fb6SRobert Watson.Nd textdump kernel dumping facility 360ff94fb6SRobert Watson.Sh SYNOPSIS 370ff94fb6SRobert Watson.Cd options KDB 380ff94fb6SRobert Watson.Cd options DDB 39*956cbd11SAlfred Perlstein.Pp 4021d748a9SAlfred Perlstein.Cd options TEXTDUMP_VERBOSE 4121d748a9SAlfred Perlstein.Cd options TEXTDUMP_PREFERRED 420ff94fb6SRobert Watson.Sh DESCRIPTION 430ff94fb6SRobert WatsonThe 440ff94fb6SRobert Watson.Nm 450ff94fb6SRobert Watsonfacility allows the capture of kernel debugging information to disk in a 460ff94fb6SRobert Watsonhuman-readable rather than the machine-readable form normally used with 470ff94fb6SRobert Watsonkernel memory dumps and minidumps. 480ff94fb6SRobert WatsonThis representation, while less complete in that it does not capture full 490ff94fb6SRobert Watsonkernel state, can provide debugging information in a more compact, portable, 500ff94fb6SRobert Watsonand persistent form than a traditional dump. 510ff94fb6SRobert WatsonBy combining 520ff94fb6SRobert Watson.Nm 530ff94fb6SRobert Watsonwith other 54070356d1SRobert Watson.Xr ddb 4 550ff94fb6SRobert Watsonfacilities, such as scripting and output capture, detailed bug information 560ff94fb6SRobert Watsoncan be captured in a fully automated manner. 570ff94fb6SRobert Watson.Sh FORMAT 580ff94fb6SRobert Watson.Nm 590ff94fb6SRobert Watsondata is stored in a dump partition in the same style as a regular memory 600ff94fb6SRobert Watsondump, and will be automatically extracted by 610ff94fb6SRobert Watson.Xr savecore 8 620ff94fb6SRobert Watsonif present on boot. 630ff94fb6SRobert Watson.Pp 640ff94fb6SRobert Watson.Nm 650ff94fb6SRobert Watsonfiles are stored in the 660ff94fb6SRobert Watson.Xr tar 5 670ff94fb6SRobert Watsonformat, and consist of one or more text files, each storing a particular type 680ff94fb6SRobert Watsonof debugging output. 690ff94fb6SRobert WatsonThe following parts may be present: 700ff94fb6SRobert Watson.Bl -tag -width version.txt 710ff94fb6SRobert Watson.It Pa ddb.txt 720ff94fb6SRobert WatsonCaptured 73070356d1SRobert Watson.Xr ddb 4 740ff94fb6SRobert Watsonoutput, if the capture facility has been used. 750ff94fb6SRobert WatsonMay be disabled by clearing the 760ff94fb6SRobert Watson.Dv debug.ddb.textdump.do_ddb 770ff94fb6SRobert Watsonsysctl. 780ff94fb6SRobert Watson.It Pa config.txt 790ff94fb6SRobert WatsonKernel configuration, if 8063d46d1dSUlrich Spörlein.Cd options INCLUDE_CONFIG_FILE 810ff94fb6SRobert Watsonhas been compiled into the kernel. 820ff94fb6SRobert WatsonMay be disabled by clearing the 830ff94fb6SRobert Watson.Dv debug.ddb.textdump.do_config 840ff94fb6SRobert Watsonsysctl. 850ff94fb6SRobert Watson.It Pa msgbuf.txt 860ff94fb6SRobert WatsonKernel message buffer, including recent console output if the capture 870ff94fb6SRobert Watsonfacility has been used. 880ff94fb6SRobert WatsonMay be disabled by clearing the 890ff94fb6SRobert Watson.Dv debug.ddb.textdump.do_msgbuf 900ff94fb6SRobert Watsonsysctl. 910ff94fb6SRobert Watson.It Pa panic.txt 920ff94fb6SRobert WatsonKernel panic string, if the kernel panicked before the dump was generated. 930ff94fb6SRobert WatsonMay be disabled by clearing the 940ff94fb6SRobert Watson.Dv debug.ddb.textdump.do_panic 950ff94fb6SRobert Watsonsysctl. 960ff94fb6SRobert Watson.It Pa version.txt 970ff94fb6SRobert WatsonKernel version string. 980ff94fb6SRobert WatsonMy be disabled by clearing the 99ca8464dfSChristian Brueffer.Dv debug.ddb.textdump.do_version 1000ff94fb6SRobert Watsonsysctl. 1010ff94fb6SRobert Watson.El 1020ff94fb6SRobert Watson.Pp 1030ff94fb6SRobert WatsonKernel textdumps may be extracted using 1047970a637STim Kientzle.Xr tar 1 . 1050ff94fb6SRobert Watson.Sh CONFIGURATION 1060ff94fb6SRobert WatsonThe 1070ff94fb6SRobert Watson.Nm 1080ff94fb6SRobert Watsonfacility is enabled as part of the kernel debugger using 1090ff94fb6SRobert Watson.Cd options KDB 1100ff94fb6SRobert Watsonand 1110ff94fb6SRobert Watson.Cd options DDB . 1120ff94fb6SRobert WatsonBy default, kernel dumps generated on panic or via explicit requests for a 1130ff94fb6SRobert Watsondump will be regular memory dumps; however, by using the 1140ff94fb6SRobert Watson.Ic textdump set 1150ff94fb6SRobert Watsoncommand in 116070356d1SRobert Watson.Xr ddb 4 , 1170ff94fb6SRobert Watsonor by setting the 1180ff94fb6SRobert Watson.Dv debug.ddb.textdump.pending 1190ff94fb6SRobert Watsonsysctl to 1 using 1200ff94fb6SRobert Watson.Xr sysctl 8 , 12121d748a9SAlfred Perlsteinit is possible to request that the next dump be a textdump. One can 12221d748a9SAlfred Perlsteinalso directly trigger a textdump in 12321d748a9SAlfred Perlstein.Xr ddb 4 12421d748a9SAlfred Perlsteinby running the command 12521d748a9SAlfred Perlstein.Ic textdump dump . 1260ff94fb6SRobert Watson.Pp 1270ff94fb6SRobert WatsonIf at the 128070356d1SRobert Watson.Xr ddb 4 1290ff94fb6SRobert Watsoncommand line, the commands 1300ff94fb6SRobert Watson.Ic textdump set , 1310ff94fb6SRobert Watson.Ic textdump status , 1320ff94fb6SRobert Watsonand 1330ff94fb6SRobert Watson.Ic textdump unset 1340ff94fb6SRobert Watsonmay be used to set, query, and clear the textdump pending flag. 13521d748a9SAlfred PerlsteinThe command 13621d748a9SAlfred Perlstein.Ic textdump dump 13721d748a9SAlfred Perlsteincan be used to immediately trigger a textdump. 1380ff94fb6SRobert Watson.Pp 1390ff94fb6SRobert WatsonAs with regular kernel dumps, a dump partition must be automatically or 1400ff94fb6SRobert Watsonmanually configured using 1410ff94fb6SRobert Watson.Xr dumpon 8 . 14221d748a9SAlfred Perlstein.Pp 14321d748a9SAlfred PerlsteinAdditional kernel 14421d748a9SAlfred Perlstein.Xr config 8 14521d748a9SAlfred Perlsteinoptions: 14621d748a9SAlfred Perlstein.Bl -tag -width TEXTDUMP_PREFERRED 14721d748a9SAlfred Perlstein.It Cd TEXTDUMP_PREFERRED 14821d748a9SAlfred Perlsteinsets textdumps to be the default manner of doing dumps. This means there 14921d748a9SAlfred Perlsteinwill be no need to 15021d748a9SAlfred Perlstein.Xr sysctl 8 15121d748a9SAlfred Perlsteinor use the 15247df4db7SJoel Dahl.Ic textdump set 15321d748a9SAlfred Perlstein.Xr ddb 8 15421d748a9SAlfred Perlsteincommands. 15521d748a9SAlfred Perlstein.It Cd TEXTDUMP_VERBOSE 15621d748a9SAlfred Perlsteinwill have the textdump facility be more verbose about each file it is emitting 15721d748a9SAlfred Perlsteinas well as other diagnostics useful to debug the textdump facility itself. 15821d748a9SAlfred Perlstein.El 1590ff94fb6SRobert Watson.Sh EXAMPLES 1600ff94fb6SRobert WatsonIn the following example, the script 1610ff94fb6SRobert Watson.Dv kdb.enter.panic 1620ff94fb6SRobert Watsonwill run when the kernel debugger is entered as a result of a panic, enable 1630ff94fb6SRobert Watsonoutput capture, dump several useful pieces of debugging information, and then 1640ff94fb6SRobert Watsoninvoke panic in order to force a kernel dump to be written out followed by a 1650ff94fb6SRobert Watsonreboot: 1660ff94fb6SRobert Watson.Bd -literal -offset indent 167f5ccc067SRobert Watsonscript kdb.enter.panic=textdump set; capture on; show allpcpu; bt; 1687b2924cbSDag-Erling Smørgrav ps; alltrace; show alllocks; call doadump; reset 1690ff94fb6SRobert Watson.Ed 1700ff94fb6SRobert Watson.Pp 1710ff94fb6SRobert WatsonIn the following example, the script 1720ff94fb6SRobert Watson.Dv kdb.enter.witness 1730ff94fb6SRobert Watsonwill run when the kernel debugger is entered as a result of a witness 1740ff94fb6SRobert Watsonviolation, printing lock-related information for the user: 1750ff94fb6SRobert Watson.Bd -literal -offset indent 1760ff94fb6SRobert Watsonscript kdb.enter.witness=show locks 1770ff94fb6SRobert Watson.Ed 178138f7e4bSTom Rhodes.Pp 179138f7e4bSTom RhodesThese scripts may also be configured using the 180138f7e4bSTom Rhodes.Xr ddb 8 181138f7e4bSTom Rhodesutility. 1820ff94fb6SRobert Watson.Sh SEE ALSO 1837970a637STim Kientzle.Xr tar 1 , 1840ff94fb6SRobert Watson.Xr ddb 4 , 1850ff94fb6SRobert Watson.Xr tar 5 , 186138f7e4bSTom Rhodes.Xr ddb 8 , 1870ff94fb6SRobert Watson.Xr dumpon 8 , 1880ff94fb6SRobert Watson.Xr savecore 8 , 1890ff94fb6SRobert Watson.Xr sysctl 8 1900dda506cSRobert Watson.Sh HISTORY 1910dda506cSRobert WatsonThe 1920dda506cSRobert Watson.Nm 1930dda506cSRobert Watsonfacility first appeared in 1940dda506cSRobert Watson.Fx 7.1 . 1950ff94fb6SRobert Watson.Sh AUTHORS 1960ff94fb6SRobert WatsonThe 1970ff94fb6SRobert Watson.Nm 1980ff94fb6SRobert Watsonfacility was created by 1990ff94fb6SRobert Watson.An Robert N. M. Watson . 200