share/man/man9/stack.9

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