1.\" 2.\" Copyright (c) 2007-2009 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 15.\" 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 26.\" DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd March 6, 2022 31.Dt STACK 9 32.Os 33.Sh NAME 34.Nm stack 35.Nd kernel thread stack tracing routines 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/stack.h 39.Pp 40In the kernel configuration file: 41.Cd "options DDB" 42.Cd "options STACK" 43.Pp 44.Ft struct stack * 45.Fn stack_create "int flags" 46.Ft void 47.Fn stack_destroy "struct stack *st" 48.Ft int 49.Fn stack_put "struct stack *st" "vm_offset_t pc" 50.Ft void 51.Fn stack_copy "const struct stack *src" "struct stack *dst" 52.Ft void 53.Fn stack_zero "struct stack *st" 54.Ft void 55.Fn stack_print "const struct stack *st" 56.Ft void 57.Fn stack_print_ddb "const struct stack *st" 58.Ft void 59.Fn stack_print_short "const struct stack *st" 60.Ft void 61.Fn stack_print_short_ddb "const struct stack *st" 62.Ft void 63.Fn stack_sbuf_print "struct sbuf *sb" "const struct stack *st" 64.Ft void 65.Fn stack_sbuf_print_ddb "struct sbuf *sb" "const struct stack *st" 66.Ft void 67.Fn stack_save "struct stack *st" 68.Ft int 69.Fn stack_save_td "struct stack *st" "struct thread *td" 70.Sh DESCRIPTION 71The 72.Nm 73KPI allows querying of kernel stack trace information and the automated 74generation of kernel stack trace strings for the purposes of debugging and 75tracing. 76To use the KPI, at least one of 77.Cd "options DDB" 78and 79.Cd "options STACK" 80must be compiled into the kernel. 81.Pp 82Each stack trace is described by a 83.Vt "struct stack" . 84It can be declared in the usual ways, including on the stack, and optionally 85initialized with 86.Fn stack_zero , 87though this is not necessary before saving a trace. 88It can also be dynamically allocated with 89.Fn stack_create . 90The 91.Ar flags 92argument is passed to 93.Xr malloc 9 . 94This dynamic allocation must be freed with 95.Fn stack_destroy . 96.Pp 97A trace of the current thread's kernel call stack may be captured using 98.Fn stack_save . 99.Fn stack_save_td 100can be used to capture the kernel stack of a caller-specified thread. 101Callers of 102.Fn stack_save_td 103must own the thread lock of the specified thread, 104and the thread's stack must not be swapped out. 105.Fn stack_save_td 106can capture the kernel stack of a running thread, though note that this is 107not implemented on all platforms. 108If the thread is running, the caller must also hold the process lock for the 109target thread. 110.Pp 111.Fn stack_print 112and 113.Fn stack_print_short 114may be used to print a stack trace using the kernel 115.Xr printf 9 , 116and may sleep as a result of acquiring 117.Xr sx 9 118locks in the kernel linker while looking up symbol names. 119In locking-sensitive environments, the unsynchronized 120.Fn stack_print_ddb 121and 122.Fn stack_print_short_ddb 123variants may be invoked. 124This function bypasses kernel linker locking, making it usable in 125.Xr ddb 4 , 126but not in a live system where linker data structures may change. 127.Pp 128.Fn stack_sbuf_print 129may be used to construct a human-readable string, including conversion (where 130possible) from a simple kernel instruction pointer to a named symbol and 131offset. 132The argument 133.Ar sb 134must be an initialized 135.Dv struct sbuf 136as described in 137.Xr sbuf 9 . 138This function may sleep if an auto-extending 139.Dv struct sbuf 140is used, or due to kernel linker locking. 141In locking-sensitive environments, such as 142.Xr ddb 4 , 143the unsynchronized 144.Fn stack_sbuf_print_ddb 145variant may be invoked to avoid kernel linker locking; it should be used with 146a fixed-length sbuf. 147.Pp 148The utility functions 149.Nm stack_zero , 150.Nm stack_copy , 151and 152.Nm stack_put 153may be used to manipulate stack data structures directly. 154.Sh RETURN VALUES 155.Fn stack_put 156returns 0 on success. 157Otherwise the 158.Dv struct stack 159does not contain space to record additional frames, and a non-zero value is 160returned. 161.Pp 162.Fn stack_save_td 163returns 0 when the stack capture was successful and a non-zero error number 164otherwise. 165In particular, 166.Er EBUSY 167is returned if the thread was running in user mode at the time that the 168capture was attempted, and 169.Er EOPNOTSUPP 170is returned if the operation is not implemented. 171.Sh SEE ALSO 172.Xr ddb 4 , 173.Xr printf 9 , 174.Xr sbuf 9 , 175.Xr sx 9 176.Sh AUTHORS 177.An -nosplit 178The 179.Nm 180function suite was created by 181.An Antoine Brodin . 182.Nm 183was extended by 184.An Robert Watson 185for general-purpose use outside of 186.Xr ddb 4 . 187