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 January 31, 2020 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" . 84Before a trace may be created or otherwise manipulated, storage for the trace 85must be allocated with 86.Fn stack_create . 87The 88.Ar flags 89argument is passed to 90.Xr malloc 9 . 91Memory associated with a trace is freed by calling 92.Fn stack_destroy . 93.Pp 94A trace of the current thread's kernel call stack may be captured using 95.Fn stack_save . 96.Fn stack_save_td 97can be used to capture the kernel stack of a caller-specified thread. 98Callers of these functions must own the thread lock of the specified thread, 99and the thread's stack must not be swapped out. 100.Fn stack_save_td 101can capture the kernel stack of a running thread, though note that this is 102not implemented on all platforms. 103If the thread is running, the caller must also hold the process lock for the 104target thread. 105.Pp 106.Fn stack_print 107and 108.Fn stack_print_short 109may be used to print a stack trace using the kernel 110.Xr printf 9 , 111and may sleep as a result of acquiring 112.Xr sx 9 113locks in the kernel linker while looking up symbol names. 114In locking-sensitive environments, the unsynchronized 115.Fn stack_print_ddb 116and 117.Fn stack_print_short_ddb 118variants may be invoked. 119This function bypasses kernel linker locking, making it usable in 120.Xr ddb 4 , 121but not in a live system where linker data structures may change. 122.Pp 123.Fn stack_sbuf_print 124may be used to construct a human-readable string, including conversion (where 125possible) from a simple kernel instruction pointer to a named symbol and 126offset. 127The argument 128.Ar sb 129must be an initialized 130.Dv struct sbuf 131as described in 132.Xr sbuf 9 . 133This function may sleep if an auto-extending 134.Dv struct sbuf 135is used, or due to kernel linker locking. 136In locking-sensitive environments, such as 137.Xr ddb 4 , 138the unsynchronized 139.Fn stack_sbuf_print_ddb 140variant may be invoked to avoid kernel linker locking; it should be used with 141a fixed-length sbuf. 142.Pp 143The utility functions 144.Nm stack_zero , 145.Nm stack_copy , 146and 147.Nm stack_put 148may be used to manipulate stack data structures directly. 149.Sh RETURN VALUES 150.Fn stack_put 151returns 0 on success. 152Otherwise the 153.Dv struct stack 154does not contain space to record additional frames, and a non-zero value is 155returned. 156.Pp 157.Fn stack_save_td 158returns 0 when the stack capture was successful and a non-zero error number 159otherwise. 160In particular, 161.Er EBUSY 162is returned if the thread was running in user mode at the time that the 163capture was attempted, and 164.Er EOPNOTSUPP 165is returned if the operation is not implemented. 166.Sh SEE ALSO 167.Xr ddb 4 , 168.Xr printf 9 , 169.Xr sbuf 9 , 170.Xr sx 9 171.Sh AUTHORS 172.An -nosplit 173The 174.Nm 175function suite was created by 176.An Antoine Brodin . 177.Nm 178was extended by 179.An Robert Watson 180for general-purpose use outside of 181.Xr ddb 4 . 182