1.\" 2.\" Copyright (c) 2007 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 February 27, 2007 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 39In the kernel configuration file: 40.Cd "options DDB" 41.Cd "options STACK" 42.Ft struct stack * 43.Fn stack_create "void" 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 "struct stack *src" "struct stack dst" 50.Ft void 51.Fn stack_zero "struct stack *st" 52.Ft void 53.Fn stack_print "struct stack *st" 54.Ft void 55.Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st" 56.Ft void 57.Fn stack_sbuf_print_ddb "struct sbuf sb*" "struct stack *st" 58.Ft void 59.Fn stack_save "struct stack *st" 60.Sh DESCRIPTION 61The 62.Nm 63KPI allows querying of kernel stack trace information and the automated 64generation of kernel stack trace strings for the purposes of debugging and 65tracing. 66To use the KPI, at least one of 67.Cd "options DDB" 68and 69.Cd "options STACK" 70must be compiled into the kernel. 71.Pp 72Each stack trace is described by a 73.Vt "struct stack" . 74Before a trace may be created or otherwise manipulated, storage for the trace 75must be allocated with 76.Fn stack_create , 77which may sleep. 78Memory associated with a trace is freed by calling 79.Fn stack_destroy . 80.Pp 81A trace of the current kernel thread's call stack may be captured using 82.Fn stack_save . 83.Pp 84.Fn stack_print 85may be used to print a stack trace using the kernel 86.Xr printf 9 , 87and may sleep as a result of acquiring 88.Xr sx 9 89locks in the kernel linker while looking up symbol names. 90In locking-sensitive environments, the unsynchronized 91.Fn stack_print_ddb 92variant may be invoked. 93This function bypasses kernel linker locking, making it usable in 94.Xr ddb 4 , 95but not in a live system where linker data structures may change. 96.Pp 97.Fn stack_sbuf_print 98may be used to construct a human-readable string, including conversion (where 99possible) from a simple kernel instruction pointer to a named symbol and 100offset. 101The argument 102.Ar sb 103must be an initialized 104.Dv struct sbuf 105as described in 106.Xr sbuf 9 . 107This function may sleep if an auto-extending 108.Dv struct sbuf 109is used, or due to kernel linker locking. 110In locking-sensitive environments, such as 111.Xr ddb 4 , 112the unsynchronized 113.Fn stack_sbuf_print_ddb 114variant may be invoked to avoid kernel linker locking; it should be used with 115a fixed-length sbuf. 116.Pp 117The utility functions 118.Nm stack_zero , 119.Nm stack_copy , 120and 121.Nm stack_put 122may be used to manipulate stack data structures directly. 123.Sh SEE ALSO 124.Xr ddb 4 , 125.Xr printf 9 , 126.Xr sbuf 9 , 127.Xr sx 9 128.Sh AUTHORS 129.An -nosplit 130The 131.Xr stack 9 132function suite was created by 133.An Antoine Brodin . 134.Xr stack 9 135was extended by 136.An Robert Watson 137for general-purpose use outside of 138.Xr ddb 4 . 139