d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

stack(9): dynamic allocation is not necessary

Browse Source 
The man page said dynamic allocation was required, but struct stack
can be allocated in any way, including on the stack.  Make this clear,
and explain how to initialize the struct.

While I'm here, stack_save does not require any lock.

Reviewed by:	markj, Pau Amma <pauamma_gundo.com>
MFC after:	1 week
Sponsored by:	Dell EMC Isilon
Differential Revision:	https://reviews.freebsd.org/D34461
This commit is contained in:
Eric van Gyzen 2022-03-06 19:12:28 -06:00
parent a8cbb835bf
commit a65bee6705
1 changed files with 13 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
share/man/man9/stack.9
View File

@ -27,7 +27,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd January 31, 2020
.Dd March 6, 2022
.Dt STACK 9
.Os
.Sh NAME
@ -48,7 +48,7 @@ In the kernel configuration file:
.Ft int
.Fn stack_put "struct stack *st" "vm_offset_t pc"
.Ft void
.Fn stack_copy "const struct stack *src" "struct stack dst"
.Fn stack_copy "const struct stack *src" "struct stack *dst"
.Ft void
.Fn stack_zero "struct stack *st"
.Ft void
@ -60,9 +60,9 @@ In the kernel configuration file:
.Ft void
.Fn stack_print_short_ddb "const struct stack *st"
.Ft void
.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st"
.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"
.Fn stack_sbuf_print_ddb "struct sbuf *sb" "const struct stack *st"
.Ft void
.Fn stack_save "struct stack *st"
.Ft int
@ -81,21 +81,26 @@ 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
It can be declared in the usual ways, including on the stack, and optionally
initialized with
.Fn stack_zero ,
though this is not necessary before saving a trace.
It can also be dynamically allocated with
.Fn stack_create .
The
.Ar flags
argument is passed to
.Xr malloc 9 .
Memory associated with a trace is freed by calling
This dynamic allocation must be freed with
.Fn stack_destroy .
.Pp
A trace of the current thread's kernel call stack may be captured using
.Fn stack_save .
.Fn stack_save_td
can be used to capture the kernel stack of a caller-specified thread.
Callers of these functions must own the thread lock of the specified thread,
Callers of
.Fn stack_save_td
must own the thread lock of the specified thread,
and the thread's stack must not be swapped out.
.Fn stack_save_td
can capture the kernel stack of a running thread, though note that this is