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