| stack.9 (59abbffacd1e61792097e0d467fa40e1749d27e8) | stack.9 (a65bee6705ac73bb334ee052bcf1e85bcc9efceb) |
|---|---|
| 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 --- 13 unchanged lines hidden (view full) --- 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.\" | 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 --- 13 unchanged lines hidden (view full) --- 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 | 30.Dd March 6, 2022 |
| 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 --- 4 unchanged lines hidden (view full) --- 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 | 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 --- 4 unchanged lines hidden (view full) --- 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" | 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 | 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" | 63.Fn stack_sbuf_print "struct sbuf *sb" "const struct stack *st" |
| 64.Ft void | 64.Ft void |
| 65.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st" | 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 71The 72.Nm 73KPI allows querying of kernel stack trace information and the automated 74generation of kernel stack trace strings for the purposes of debugging and 75tracing. 76To use the KPI, at least one of 77.Cd "options DDB" 78and 79.Cd "options STACK" 80must be compiled into the kernel. 81.Pp 82Each stack trace is described by a 83.Vt "struct stack" . | 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 71The 72.Nm 73KPI allows querying of kernel stack trace information and the automated 74generation of kernel stack trace strings for the purposes of debugging and 75tracing. 76To use the KPI, at least one of 77.Cd "options DDB" 78and 79.Cd "options STACK" 80must be compiled into the kernel. 81.Pp 82Each stack trace is described by a 83.Vt "struct stack" . |
| 84Before a trace may be created or otherwise manipulated, storage for the trace 85must be allocated with | 84It can be declared in the usual ways, including on the stack, and optionally 85initialized with 86.Fn stack_zero , 87though this is not necessary before saving a trace. 88It can also be dynamically allocated with |
| 86.Fn stack_create . 87The 88.Ar flags 89argument is passed to 90.Xr malloc 9 . | 89.Fn stack_create . 90The 91.Ar flags 92argument is passed to 93.Xr malloc 9 . |
| 91Memory associated with a trace is freed by calling | 94This dynamic allocation must be freed with |
| 92.Fn stack_destroy . 93.Pp 94A trace of the current thread's kernel call stack may be captured using 95.Fn stack_save . 96.Fn stack_save_td 97can be used to capture the kernel stack of a caller-specified thread. | 95.Fn stack_destroy . 96.Pp 97A trace of the current thread's kernel call stack may be captured using 98.Fn stack_save . 99.Fn stack_save_td 100can be used to capture the kernel stack of a caller-specified thread. |
| 98Callers of these functions must own the thread lock of the specified thread, | 101Callers of 102.Fn stack_save_td 103must own the thread lock of the specified thread, |
| 99and the thread's stack must not be swapped out. 100.Fn stack_save_td 101can capture the kernel stack of a running thread, though note that this is 102not implemented on all platforms. 103If the thread is running, the caller must also hold the process lock for the 104target thread. 105.Pp 106.Fn stack_print --- 75 unchanged lines hidden --- | 104and the thread's stack must not be swapped out. 105.Fn stack_save_td 106can capture the kernel stack of a running thread, though note that this is 107not implemented on all platforms. 108If the thread is running, the caller must also hold the process lock for the 109target thread. 110.Pp 111.Fn stack_print --- 75 unchanged lines hidden --- |