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 September 10, 2015 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 "void" 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 , 89which may sleep. 90Memory associated with a trace is freed by calling 91.Fn stack_destroy . 92.Pp 93A trace of the current kernel thread's call stack may be captured using 94.Fn stack_save . 95.Fn stack_save_td 96and 97.Fn stack_save_td_running 98can also be used to capture the stack of a caller-specified thread. 99Callers of these functions must own the thread lock of the specified thread. 100.Fn stack_save_td 101can capture the stack of a kernel thread that is not running or 102swapped out at the time of the call. 103.Fn stack_save_td_running 104can capture the stack of a running kernel 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_running 158returns 0 when the stack capture was successful and a non-zero error number 159otherwise. 160In particular, 161.Er EAGAIN 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