1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<table class="head">
<tr>
<td class="head-ltitle">TEXTDUMP(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">TEXTDUMP(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">textdump</code> —
<span class="Nd">textdump kernel dumping facility</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">options DDB</code>
<br/>
<code class="Cd">options KDB</code></p>
<p class="Pp">
<br/>
<code class="Cd">options TEXTDUMP_PREFERRED</code>
<br/>
<code class="Cd">options TEXTDUMP_VERBOSE</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">textdump</code> 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
<code class="Nm">textdump</code> with other <a class="Xr">ddb(4)</a>
facilities, such as scripting and output capture, detailed bug information
can be captured in a fully automated manner.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FORMAT"><a class="permalink" href="#FORMAT">FORMAT</a></h1>
<p class="Pp"><code class="Nm">textdump</code> data is stored in a dump
partition in the same style as a regular memory dump, and will be
automatically extracted by <a class="Xr">savecore(8)</a> if present on
boot.</p>
<p class="Pp"><code class="Nm">textdump</code> files are stored in the
<a class="Xr">tar(5)</a> format, and consist of one or more text files, each
storing a particular type of debugging output. The following parts may be
present:</p>
<dl class="Bl-tag">
<dt><span class="Pa">ddb.txt</span></dt>
<dd>Captured <a class="Xr">ddb(4)</a> output, if the capture facility has been
used. May be disabled by clearing the
<var class="Va">debug.ddb.textdump.do_ddb</var> sysctl.</dd>
<dt><span class="Pa">config.txt</span></dt>
<dd>Kernel configuration, if <code class="Cd">options
INCLUDE_CONFIG_FILE</code> has been compiled into the kernel. May be
disabled by clearing the
<var class="Va">debug.ddb.textdump.do_config</var> sysctl.</dd>
<dt><span class="Pa">msgbuf.txt</span></dt>
<dd>Kernel message buffer, including recent console output if the capture
facility has been used. May be disabled by clearing the
<var class="Va">debug.ddb.textdump.do_msgbuf</var> sysctl.</dd>
<dt><span class="Pa">panic.txt</span></dt>
<dd>Kernel panic string, if the kernel panicked before the dump was generated.
May be disabled by clearing the
<var class="Va">debug.ddb.textdump.do_panic</var> sysctl.</dd>
<dt><span class="Pa">version.txt</span></dt>
<dd>Kernel version string. My be disabled by clearing the
<var class="Va">debug.ddb.textdump.do_version</var> sysctl.</dd>
</dl>
<p class="Pp">Kernel textdumps may be extracted using
<a class="Xr">tar(1)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="CONFIGURATION"><a class="permalink" href="#CONFIGURATION">CONFIGURATION</a></h1>
<p class="Pp">The <code class="Nm">textdump</code> facility is enabled as part
of the kernel debugger using <code class="Cd">options KDB</code> and
<code class="Cd">options DDB</code>. By default, kernel dumps generated on
panic or via explicit requests for a dump will be regular memory dumps;
however, by using the <code class="Ic">textdump set</code> command in
<a class="Xr">ddb(4)</a>, or by setting the
<var class="Va">debug.ddb.textdump.pending</var> sysctl to 1 using
<a class="Xr">sysctl(8)</a>, it is possible to request that the next dump be
a textdump. One may also directly trigger a textdump in
<a class="Xr">ddb(4)</a> by running the command <code class="Ic">textdump
dump</code>.</p>
<p class="Pp">If at the <a class="Xr">ddb(4)</a> command line, the commands
<code class="Ic">textdump set</code>, <code class="Ic">textdump
status</code>, and <code class="Ic">textdump unset</code> may be used to
set, query, and clear the textdump pending flag.</p>
<p class="Pp">As with regular kernel dumps, a dump partition must be
automatically or manually configured using <a class="Xr">dumpon(8)</a>.</p>
<p class="Pp">Additional kernel <a class="Xr">config(8)</a> options:</p>
<dl class="Bl-tag">
<dt><code class="Cd">TEXTDUMP_PREFERRED</code></dt>
<dd>sets textdumps to be the default manner of doing dumps. This means there
will be no need to <a class="Xr">sysctl(8)</a> or use the
<code class="Ic">textdump set</code> <a class="Xr">ddb(8)</a>
commands.</dd>
<dt><code class="Cd">TEXTDUMP_VERBOSE</code></dt>
<dd>will have the textdump facility be more verbose about each file it is
emitting as well as other diagnostics useful to debug the textdump
facility itself.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">In the following example, the script
<var class="Va">kdb.enter.panic</var> 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:</p>
<div class="Bd Pp Bd-indent Li">
<pre>script kdb.enter.panic=textdump set; capture on; show allpcpu; bt;
ps; alltrace; show alllocks; textdump dump; reset</pre>
</div>
<p class="Pp">In the following example, the script
<var class="Va">kdb.enter.witness</var> will run when the kernel debugger is
entered as a result of a witness violation, printing lock-related
information for the user:</p>
<div class="Bd Pp Bd-indent Li">
<pre>script kdb.enter.witness=show locks</pre>
</div>
<p class="Pp">These scripts may also be configured using the
<a class="Xr">ddb(8)</a> utility.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">tar(1)</a>, <a class="Xr">ddb(4)</a>,
<a class="Xr">tar(5)</a>, <a class="Xr">ddb(8)</a>,
<a class="Xr">dumpon(8)</a>, <a class="Xr">savecore(8)</a>,
<a class="Xr">sysctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">textdump</code> facility first appeared in
<span class="Ux">FreeBSD 7.1</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">textdump</code> facility was created by
<span class="An">Robert N. M. Watson</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 18, 2019</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
