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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<table class="head">
<tr>
<td class="head-ltitle">STACK(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">STACK(9)</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">stack</code> — <span class="Nd">kernel
thread stack tracing routines</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/param.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/stack.h</a>></code></p>
<p class="Pp">In the kernel configuration file:
<br/>
<code class="Cd">options DDB</code>
<br/>
<code class="Cd">options STACK</code></p>
<p class="Pp">
<br/>
<var class="Ft">struct stack *</var>
<br/>
<code class="Fn">stack_create</code>(<var class="Fa" style="white-space: nowrap;">int
flags</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct
stack *st</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">stack_put</code>(<var class="Fa" style="white-space: nowrap;">struct
stack *st</var>, <var class="Fa" style="white-space: nowrap;">vm_offset_t
pc</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_copy</code>(<var class="Fa" style="white-space: nowrap;">const
struct stack *src</var>, <var class="Fa" style="white-space: nowrap;">struct
stack *dst</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_zero</code>(<var class="Fa" style="white-space: nowrap;">struct
stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_print</code>(<var class="Fa" style="white-space: nowrap;">const
struct stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_print_ddb</code>(<var class="Fa" style="white-space: nowrap;">const
struct stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_print_short</code>(<var class="Fa" style="white-space: nowrap;">const
struct stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_print_short_ddb</code>(<var class="Fa" style="white-space: nowrap;">const
struct stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_sbuf_print</code>(<var class="Fa" style="white-space: nowrap;">struct
sbuf *sb</var>, <var class="Fa" style="white-space: nowrap;">const struct
stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_sbuf_print_ddb</code>(<var class="Fa" style="white-space: nowrap;">struct
sbuf *sb</var>, <var class="Fa" style="white-space: nowrap;">const struct
stack *st</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">stack_save</code>(<var class="Fa" style="white-space: nowrap;">struct
stack *st</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">stack_save_td</code>(<var class="Fa" style="white-space: nowrap;">struct
stack *st</var>, <var class="Fa" style="white-space: nowrap;">struct thread
*td</var>);</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">stack</code> KPI allows querying of kernel
stack trace information and the automated generation of kernel stack trace
strings for the purposes of debugging and tracing. To use the KPI, at least
one of <code class="Cd">options DDB</code> and <code class="Cd">options
STACK</code> must be compiled into the kernel.</p>
<p class="Pp" id="stack_zero">Each stack trace is described by a
<var class="Vt">struct stack</var>. It can be declared in the usual ways,
including on the stack, and optionally initialized with
<a class="permalink" href="#stack_zero"><code class="Fn">stack_zero</code></a>(),
though this is not necessary before saving a trace. It can also be
dynamically allocated with
<a class="permalink" href="#stack_create"><code class="Fn" id="stack_create">stack_create</code></a>().
The <var class="Ar">flags</var> argument is passed to
<a class="Xr">malloc(9)</a>. This dynamic allocation must be freed with
<a class="permalink" href="#stack_destroy"><code class="Fn" id="stack_destroy">stack_destroy</code></a>().</p>
<p class="Pp" id="stack_save">A trace of the current thread's kernel call stack
may be captured using
<a class="permalink" href="#stack_save"><code class="Fn">stack_save</code></a>().
<a class="permalink" href="#stack_save_td"><code class="Fn" id="stack_save_td">stack_save_td</code></a>()
can be used to capture the kernel stack of a caller-specified thread.
Callers of <code class="Fn">stack_save_td</code>() must own the thread lock
of the specified thread, and the thread's stack must not be swapped out.
<code class="Fn">stack_save_td</code>() can capture the kernel stack of a
running thread, though note that this is not implemented on all platforms.
If the thread is running, the caller must also hold the process lock for the
target thread.</p>
<p class="Pp" id="stack_print"><a class="permalink" href="#stack_print"><code class="Fn">stack_print</code></a>()
and
<a class="permalink" href="#stack_print_short"><code class="Fn" id="stack_print_short">stack_print_short</code></a>()
may be used to print a stack trace using the kernel
<a class="Xr">printf(9)</a>, and may sleep as a result of acquiring
<a class="Xr">sx(9)</a> locks in the kernel linker while looking up symbol
names. In locking-sensitive environments, the unsynchronized
<a class="permalink" href="#stack_print_ddb"><code class="Fn" id="stack_print_ddb">stack_print_ddb</code></a>()
and
<a class="permalink" href="#stack_print_short_ddb"><code class="Fn" id="stack_print_short_ddb">stack_print_short_ddb</code></a>()
variants may be invoked. This function bypasses kernel linker locking,
making it usable in <a class="Xr">ddb(4)</a>, but not in a live system where
linker data structures may change.</p>
<p class="Pp" id="stack_sbuf_print"><a class="permalink" href="#stack_sbuf_print"><code class="Fn">stack_sbuf_print</code></a>()
may be used to construct a human-readable string, including conversion
(where possible) from a simple kernel instruction pointer to a named symbol
and offset. The argument <var class="Ar">sb</var> must be an initialized
<code class="Dv">struct sbuf</code> as described in
<a class="Xr">sbuf(9)</a>. This function may sleep if an auto-extending
<code class="Dv">struct sbuf</code> is used, or due to kernel linker
locking. In locking-sensitive environments, such as
<a class="Xr">ddb(4)</a>, the unsynchronized
<a class="permalink" href="#stack_sbuf_print_ddb"><code class="Fn" id="stack_sbuf_print_ddb">stack_sbuf_print_ddb</code></a>()
variant may be invoked to avoid kernel linker locking; it should be used
with a fixed-length sbuf.</p>
<p class="Pp">The utility functions <code class="Nm">stack_zero</code>,
<code class="Nm">stack_copy</code>, and <code class="Nm">stack_put</code>
may be used to manipulate stack data structures directly.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp"><code class="Fn">stack_put</code>() returns 0 on success.
Otherwise the <code class="Dv">struct stack</code> does not contain space to
record additional frames, and a non-zero value is returned.</p>
<p class="Pp"><code class="Fn">stack_save_td</code>() returns 0 when the stack
capture was successful and a non-zero error number otherwise. In particular,
<code class="Er">EBUSY</code> is returned if the thread was running in user
mode at the time that the capture was attempted, and
<code class="Er">EOPNOTSUPP</code> is returned if the operation is not
implemented.</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">ddb(4)</a>, <a class="Xr">printf(9)</a>,
<a class="Xr">sbuf(9)</a>, <a class="Xr">sx(9)</a></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">stack</code> function suite was created by
<span class="An">Antoine Brodin</span>. <code class="Nm">stack</code> was
extended by <span class="An">Robert Watson</span> for general-purpose use
outside of <a class="Xr">ddb(4)</a>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">March 6, 2022</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
