1 files changed, 148 insertions, 0 deletions
diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9
new file mode 100644
index 0000000..fee6b8f
--- /dev/null
+++ b/share/man/man9/stack.9
@@ -0,0 +1,148 @@
+.\"
+.\" Copyright (c) 2007-2009 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer as
+.\"    the first lines of this file unmodified other than the possible
+.\"    addition of one or more copyright notices.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice(s), this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+.\" DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd November 16, 2011
+.Dt STACK 9
+.Os
+.Sh NAME
+.Nm stack
+.Nd kernel thread stack tracing routines
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/stack.h
+In the kernel configuration file:
+.Cd "options DDB"
+.Cd "options STACK"
+.Ft struct stack *
+.Fn stack_create "void"
+.Ft void
+.Fn stack_destroy "struct stack *st"
+.Ft int
+.Fn stack_put "struct stack *st" "vm_offset_t pc"
+.Ft void
+.Fn stack_copy "const struct stack *src" "struct stack dst"
+.Ft void
+.Fn stack_zero "struct stack *st"
+.Ft void
+.Fn stack_print "const struct stack *st"
+.Ft void
+.Fn stack_print_ddb "const struct stack *st"
+.Ft void
+.Fn stack_print_short "const struct stack *st"
+.Ft void
+.Fn stack_print_short_ddb "const struct stack *st"
+.Ft void
+.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
+.Ft void
+.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st"
+.Ft void
+.Fn stack_save "struct stack *st"
+.Sh DESCRIPTION
+The
+.Nm
+KPI allows querying of kernel stack trace information and the automated
+generation of kernel stack trace strings for the purposes of debugging and
+tracing.
+To use the KPI, at least one of
+.Cd "options DDB"
+and
+.Cd "options STACK"
+must be compiled into the kernel.
+.Pp
+Each stack trace is described by a
+.Vt "struct stack" .
+Before a trace may be created or otherwise manipulated, storage for the trace
+must be allocated with
+.Fn stack_create ,
+which may sleep.
+Memory associated with a trace is freed by calling
+.Fn stack_destroy .
+.Pp
+A trace of the current kernel thread's call stack may be captured using
+.Fn stack_save .
+.Pp
+.Fn stack_print
+and
+.Fn stack_print_short
+may be used to print a stack trace using the kernel
+.Xr printf 9 ,
+and may sleep as a result of acquiring
+.Xr sx 9
+locks in the kernel linker while looking up symbol names.
+In locking-sensitive environments, the unsynchronized
+.Fn stack_print_ddb
+and
+.Fn stack_print_short_ddb
+variants may be invoked.
+This function bypasses kernel linker locking, making it usable in
+.Xr ddb 4 ,
+but not in a live system where linker data structures may change.
+.Pp
+.Fn stack_sbuf_print
+may be used to construct a human-readable string, including conversion (where
+possible) from a simple kernel instruction pointer to a named symbol and
+offset.
+The argument
+.Ar sb
+must be an initialized
+.Dv struct sbuf
+as described in
+.Xr sbuf 9 .
+This function may sleep if an auto-extending
+.Dv struct sbuf
+is used, or due to kernel linker locking.
+In locking-sensitive environments, such as
+.Xr ddb 4 ,
+the unsynchronized
+.Fn stack_sbuf_print_ddb
+variant may be invoked to avoid kernel linker locking; it should be used with
+a fixed-length sbuf.
+.Pp
+The utility functions
+.Nm stack_zero ,
+.Nm stack_copy ,
+and
+.Nm stack_put
+may be used to manipulate stack data structures directly.
+.Sh SEE ALSO
+.Xr ddb 4 ,
+.Xr printf 9 ,
+.Xr sbuf 9 ,
+.Xr sx 9
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr stack 9
+function suite was created by
+.An Antoine Brodin .
+.Xr stack 9
+was extended by
+.An Robert Watson
+for general-purpose use outside of
+.Xr ddb 4 .