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
35 .Nd kernel thread stack tracing routines
40 In the kernel configuration file:
45 .Fn stack_create "int flags"
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
93 Memory associated with a trace is freed by calling
96 A trace of the current kernel thread's call stack may be captured using
100 .Fn stack_save_td_running
101 can also be used to capture the stack of a caller-specified thread.
102 Callers of these functions must own the thread lock of the specified thread.
104 can capture the stack of a kernel thread that is not running or
105 swapped out at the time of the call.
106 .Fn stack_save_td_running
107 can capture the stack of a running kernel thread.
111 .Fn stack_print_short
112 may be used to print a stack trace using the kernel
114 and may sleep as a result of acquiring
116 locks in the kernel linker while looking up symbol names.
117 In locking-sensitive environments, the unsynchronized
120 .Fn stack_print_short_ddb
121 variants may be invoked.
122 This function bypasses kernel linker locking, making it usable in
124 but not in a live system where linker data structures may change.
127 may be used to construct a human-readable string, including conversion (where
128 possible) from a simple kernel instruction pointer to a named symbol and
132 must be an initialized
136 This function may sleep if an auto-extending
138 is used, or due to kernel linker locking.
139 In locking-sensitive environments, such as
142 .Fn stack_sbuf_print_ddb
143 variant may be invoked to avoid kernel linker locking; it should be used with
146 The utility functions
151 may be used to manipulate stack data structures directly.
154 returns 0 on success.
157 does not contain space to record additional frames, and a non-zero value is
160 .Fn stack_save_td_running
161 returns 0 when the stack capture was successful and a non-zero error number
165 is returned if the thread was running in user mode at the time that the
166 capture was attempted, and
168 is returned if the operation is not implemented.
178 function suite was created by
183 for general-purpose use outside of