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