Break out stack(9) from ddb(4):

- Introduce per-architecture stack_machdep.c to hold stack_save(9).
- Introduce per-architecture machine/stack.h to capture any common
  definitions required between db_trace.c and stack_machdep.c.
- Add new kernel option "options STACK"; we will build in stack(9) if it is
  defined, or also if "options DDB" is defined to provide compatibility
  with existing users of stack(9).

Add new stack_save_td(9) function, which allows the capture of a stacktrace
of another thread rather than the current thread, which the existing
stack_save(9) was limited to.  It requires that the thread be neither
swapped out nor running, which is the responsibility of the consumer to
enforce.

Update stack(9) man page.

Build tested:	amd64, arm, i386, ia64, powerpc, sparc64, sun4v
Runtime tested:	amd64 (rwatson), arm (cognet), i386 (rwatson)

1 files changed, 28 insertions, 22 deletions

diff --git a/share/man/man9/stack.9 b/share/man/man9/stack.9
index 17cf509..d71af96 100644
--- a/share/man/man9/stack.9
+++ b/share/man/man9/stack.9
@@ -36,9 +36,9 @@
 .Sh SYNOPSIS
 .In sys/param.h>
 .In sys/stack.h
-.Pp
-In kernel configuration files:
+In the kernel configuration file:
 .Cd "options DDB"
+.Cd "options STACK"
 .Ft struct stack *
 .Fn stack_create "void"
 .Ft void
@@ -63,12 +63,11 @@ The
 KPI allows querying of kernel stack trace information and the automated
 generation of kernel stack trace strings for the purposes of debugging and
 tracing.
-.Nm
-relies on the presence of
-.Xr DDB 4 ,
-and all use of these functions must be made conditional on
-.Nm DDB
-being compiled in the kernel.
+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" .
@@ -76,7 +75,7 @@ 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 may be freed by calling
+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
@@ -84,7 +83,16 @@ A trace of the current kernel thread's call stack may be captured using
 .Pp
 .Fn stack_print
 may be used to print a stack trace using the kernel
-.Xr printf 9 .
+.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
+variant 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
@@ -98,17 +106,13 @@ as described in
 .Xr sbuf 9 .
 This function may sleep if an auto-extending
 .Dv struct sbuf
-is used, and because the kernel linker (used to look up symbol names) uses
-.Xr sx 9
-locks.
-.Pp
+is used, or due to kernel linker locking.
 In locking-sensitive environments, such as
-.Xr DDB 4 ,
+.Xr ddb 4 ,
 the unsynchronized
 .Fn stack_sbuf_print_ddb
-variant may be invoked; this makes use of kernel linker data structures to
-look up symbol names without following locking protocols, so is appropriate
-for use in the debugger but not while the system is live.
+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 ,
@@ -117,7 +121,7 @@ and
 .Nm stack_put
 may be used to manipulate stack data structures directly.
 .Sh SEE ALSO
-.Xr DDB 4 ,
+.Xr ddb 4 ,
 .Xr printf 9 ,
 .Xr sbuf 9 ,
 .Xr sx 9
@@ -127,6 +131,8 @@ The
 .Xr stack 9
 function suite was created by
 .An Antoine Brodin .
-.Pp
-This manual page was written by
-.An Robert Watson .
+.Xr stack 9
+was extended by
+.An Robert Watson
+for general-purpose use outside of
+.Xr ddb 4 .