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 October 6, 2017 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 void 69.Fn stack_save_td "struct stack *st" "struct thread *td" 70.Ft int 71.Fn stack_save_td_running "struct stack *st" "struct thread *td" 72.Sh DESCRIPTION 73The 74.Nm 75KPI allows querying of kernel stack trace information and the automated 76generation of kernel stack trace strings for the purposes of debugging and 77tracing. 78To use the KPI, at least one of 79.Cd "options DDB" 80and 81.Cd "options STACK" 82must be compiled into the kernel. 83.Pp 84Each stack trace is described by a 85.Vt "struct stack" . 86Before a trace may be created or otherwise manipulated, storage for the trace 87must be allocated with 88.Fn stack_create . 89The 90.Ar flags 91argument is passed to 92.Xr malloc 9 . 93Memory associated with a trace is freed by calling 94.Fn stack_destroy . 95.Pp 96A trace of the current kernel thread's call stack may be captured using 97.Fn stack_save . 98.Fn stack_save_td 99and 100.Fn stack_save_td_running 101can also be used to capture the stack of a caller-specified thread. 102Callers of these functions must own the thread lock of the specified thread. 103.Fn stack_save_td 104can capture the stack of a kernel thread that is not running or 105swapped out at the time of the call. 106.Fn stack_save_td_running 107can capture the stack of a running kernel 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_running 161returns 0 when the stack capture was successful and a non-zero error number 162otherwise. 163In particular, 164.Er EAGAIN 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