2 .\" Copyright (c) 2007-2009 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
30 .Dd September 10, 2015
35 .Nd kernel thread stack tracing routines
40 In the kernel configuration file:
45 .Fn stack_create "void"
47 .Fn stack_destroy "struct stack *st"
49 .Fn stack_put "struct stack *st" "vm_offset_t pc"
51 .Fn stack_copy "const struct stack *src" "struct stack dst"
53 .Fn stack_zero "struct stack *st"
55 .Fn stack_print "const struct stack *st"
57 .Fn stack_print_ddb "const struct stack *st"
59 .Fn stack_print_short "const struct stack *st"
61 .Fn stack_print_short_ddb "const struct stack *st"
63 .Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
65 .Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st"
67 .Fn stack_save "struct stack *st"
69 .Fn stack_save_td "struct stack *st" "struct thread *td"
71 .Fn stack_save_td_running "struct stack *st" "struct thread *td"
75 KPI allows querying of kernel stack trace information and the automated
76 generation of kernel stack trace strings for the purposes of debugging and
78 To use the KPI, at least one of
82 must be compiled into the kernel.
84 Each stack trace is described by a
86 Before a trace may be created or otherwise manipulated, storage for the trace
87 must be allocated with
90 Memory associated with a trace is freed by calling
93 A trace of the current kernel thread's call stack may be captured using
97 .Fn stack_save_td_running
98 can also be used to capture the stack of a caller-specified thread.
99 Callers of these functions must own the thread lock of the specified thread.
101 can capture the stack of a kernel thread that is not running or
102 swapped out at the time of the call.
103 .Fn stack_save_td_running
104 can capture the stack of a running kernel thread.
108 .Fn stack_print_short
109 may be used to print a stack trace using the kernel
111 and may sleep as a result of acquiring
113 locks in the kernel linker while looking up symbol names.
114 In locking-sensitive environments, the unsynchronized
117 .Fn stack_print_short_ddb
118 variants may be invoked.
119 This function bypasses kernel linker locking, making it usable in
121 but not in a live system where linker data structures may change.
124 may be used to construct a human-readable string, including conversion (where
125 possible) from a simple kernel instruction pointer to a named symbol and
129 must be an initialized
133 This function may sleep if an auto-extending
135 is used, or due to kernel linker locking.
136 In locking-sensitive environments, such as
139 .Fn stack_sbuf_print_ddb
140 variant may be invoked to avoid kernel linker locking; it should be used with
143 The utility functions
148 may be used to manipulate stack data structures directly.
151 returns 0 on success.
154 does not contain space to record additional frames, and a non-zero value is
157 .Fn stack_save_td_running
158 returns 0 when the stack capture was successful and a non-zero error number
162 is returned if the thread was running in user mode at the time that the
163 capture was attempted, and
165 is returned if the operation is not implemented.
175 function suite was created by
180 for general-purpose use outside of