2 .\" Copyright (c) 2007 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 "struct stack *src" "struct stack dst"
51 .Fn stack_zero "struct stack *st"
53 .Fn stack_print "struct stack *st"
55 .Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st"
57 .Fn stack_sbuf_print_ddb "struct sbuf sb*" "struct stack *st"
59 .Fn stack_save "struct stack *st"
63 KPI allows querying of kernel stack trace information and the automated
64 generation of kernel stack trace strings for the purposes of debugging and
66 To use the KPI, at least one of
70 must be compiled into the kernel.
72 Each stack trace is described by a
74 Before a trace may be created or otherwise manipulated, storage for the trace
75 must be allocated with
78 Memory associated with a trace is freed by calling
81 A trace of the current kernel thread's call stack may be captured using
85 may be used to print a stack trace using the kernel
87 and may sleep as a result of acquiring
89 locks in the kernel linker while looking up symbol names.
90 In locking-sensitive environments, the unsynchronized
92 variant may be invoked.
93 This function bypasses kernel linker locking, making it usable in
95 but not in a live system where linker data structures may change.
98 may be used to construct a human-readable string, including conversion (where
99 possible) from a simple kernel instruction pointer to a named symbol and
103 must be an initialized
107 This function may sleep if an auto-extending
109 is used, or due to kernel linker locking.
110 In locking-sensitive environments, such as
113 .Fn stack_sbuf_print_ddb
114 variant may be invoked to avoid kernel linker locking; it should be used with
117 The utility functions
122 may be used to manipulate stack data structures directly.
132 function suite was created by
137 for general-purpose use outside of