2 .\" Copyright (c) 2007 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice(s), this list of conditions and the following disclaimer as
10 .\" the first lines of this file unmodified other than the possible
11 .\" addition of one or more copyright notices.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice(s), this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
20 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
35 .Nd textdump kernel dumping facility
40 .Cd options TEXTDUMP_PREFERRED
41 .Cd options TEXTDUMP_VERBOSE
45 facility allows the capture of kernel debugging information to disk in a
46 human-readable rather than the machine-readable form normally used with
47 kernel memory dumps and minidumps.
48 This representation, while less complete in that it does not capture full
49 kernel state, can provide debugging information in a more compact, portable,
50 and persistent form than a traditional dump.
55 facilities, such as scripting and output capture, detailed bug information
56 can be captured in a fully automated manner.
59 data is stored in a dump partition in the same style as a regular memory
60 dump, and will be automatically extracted by
65 files are stored in the
67 format, and consist of one or more text files, each storing a particular type
69 The following parts may be present:
70 .Bl -tag -width version.txt
74 output, if the capture facility has been used.
75 May be disabled by clearing the
76 .Dv debug.ddb.textdump.do_ddb
79 Kernel configuration, if
80 .Cd options INCLUDE_CONFIG_FILE
81 has been compiled into the kernel.
82 May be disabled by clearing the
83 .Dv debug.ddb.textdump.do_config
86 Kernel message buffer, including recent console output if the capture
87 facility has been used.
88 May be disabled by clearing the
89 .Dv debug.ddb.textdump.do_msgbuf
92 Kernel panic string, if the kernel panicked before the dump was generated.
93 May be disabled by clearing the
94 .Dv debug.ddb.textdump.do_panic
97 Kernel version string.
98 My be disabled by clearing the
99 .Dv debug.ddb.textdump.do_version
103 Kernel textdumps may be extracted using
108 facility is enabled as part of the kernel debugger using
112 By default, kernel dumps generated on panic or via explicit requests for a
113 dump will be regular memory dumps; however, by using the
118 .Dv debug.ddb.textdump.pending
121 it is possible to request that the next dump be a textdump.
122 One may also directly trigger a textdump in
124 by running the command
129 command line, the commands
131 .Ic textdump status ,
134 may be used to set, query, and clear the textdump pending flag.
136 As with regular kernel dumps, a dump partition must be automatically or
137 manually configured using
143 .Bl -tag -width TEXTDUMP_PREFERRED
144 .It Cd TEXTDUMP_PREFERRED
145 sets textdumps to be the default manner of doing dumps.
146 This means there will be no need to
152 .It Cd TEXTDUMP_VERBOSE
153 will have the textdump facility be more verbose about each file it is emitting
154 as well as other diagnostics useful to debug the textdump facility itself.
157 In the following example, the script
159 will run when the kernel debugger is entered as a result of a panic, enable
160 output capture, dump several useful pieces of debugging information, and then
161 invoke panic in order to force a kernel dump to be written out followed by a
163 .Bd -literal -offset indent
164 script kdb.enter.panic=textdump set; capture on; show allpcpu; bt;
165 ps; alltrace; show alllocks; call doadump; reset
168 In the following example, the script
169 .Dv kdb.enter.witness
170 will run when the kernel debugger is entered as a result of a witness
171 violation, printing lock-related information for the user:
172 .Bd -literal -offset indent
173 script kdb.enter.witness=show locks
176 These scripts may also be configured using the
190 facility first appeared in
195 facility was created by
196 .An Robert N. M. Watson .