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
39 In the kernel configuration file:
43 .Fn stack_create "void"
45 .Fn stack_destroy "struct stack *st"
47 .Fn stack_put "struct stack *st" "vm_offset_t pc"
49 .Fn stack_copy "const struct stack *src" "struct stack dst"
51 .Fn stack_zero "struct stack *st"
53 .Fn stack_print "const struct stack *st"
55 .Fn stack_print_ddb "const struct stack *st"
57 .Fn stack_print_short "const struct stack *st"
59 .Fn stack_print_short_ddb "const struct stack *st"
61 .Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
63 .Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st"
65 .Fn stack_save "struct stack *st"
69 KPI allows querying of kernel stack trace information and the automated
70 generation of kernel stack trace strings for the purposes of debugging and
72 To use the KPI, at least one of
76 must be compiled into the kernel.
78 Each stack trace is described by a
80 Before a trace may be created or otherwise manipulated, storage for the trace
81 must be allocated with
84 Memory associated with a trace is freed by calling
87 A trace of the current kernel thread's call stack may be captured using
93 may be used to print a stack trace using the kernel
95 and may sleep as a result of acquiring
97 locks in the kernel linker while looking up symbol names.
98 In locking-sensitive environments, the unsynchronized
101 .Fn stack_print_short_ddb
102 variants may be invoked.
103 This function bypasses kernel linker locking, making it usable in
105 but not in a live system where linker data structures may change.
108 may be used to construct a human-readable string, including conversion (where
109 possible) from a simple kernel instruction pointer to a named symbol and
113 must be an initialized
117 This function may sleep if an auto-extending
119 is used, or due to kernel linker locking.
120 In locking-sensitive environments, such as
123 .Fn stack_sbuf_print_ddb
124 variant may be invoked to avoid kernel linker locking; it should be used with
127 The utility functions
132 may be used to manipulate stack data structures directly.
142 function suite was created by
147 for general-purpose use outside of