| stack.9 (a69a51149e0db4bf97222f4836de85a73a77042d) | stack.9 (12cef7aa96f202f70d5ad98aa2c814fc86159e63) |
|---|---|
| 1.\" | 1.\" |
| 2.\" Copyright (c) 2007-2009 Robert N. M. Watson | 2.\" Copyright (c) 2007 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 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.\" | 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 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 June 24, 2009 | 30.Dd February 27, 2007 |
| 31.Dt STACK 9 32.Os 33.Sh NAME 34.Nm stack 35.Nd kernel thread stack tracing routines 36.Sh SYNOPSIS | 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 | 37.In sys/param.h> |
| 38.In sys/stack.h | 38.In sys/stack.h |
| 39In the kernel configuration file: | 39.Pp 40In kernel configuration files: |
| 40.Cd "options DDB" | 41.Cd "options DDB" |
| 41.Cd "options STACK" | |
| 42.Ft struct stack * 43.Fn stack_create "void" 44.Ft void 45.Fn stack_destroy "struct stack *st" 46.Ft int 47.Fn stack_put "struct stack *st" "vm_offset_t pc" 48.Ft void 49.Fn stack_copy "struct stack *src" "struct stack dst" 50.Ft void 51.Fn stack_zero "struct stack *st" 52.Ft void | 42.Ft struct stack * 43.Fn stack_create "void" 44.Ft void 45.Fn stack_destroy "struct stack *st" 46.Ft int 47.Fn stack_put "struct stack *st" "vm_offset_t pc" 48.Ft void 49.Fn stack_copy "struct stack *src" "struct stack dst" 50.Ft void 51.Fn stack_zero "struct stack *st" 52.Ft void |
| 53.Fn stack_print "struct stack *st" 54.Ft void 55.Fn stack_print_ddb "struct stack *st" 56.Ft void 57.Fn stack_print_short "struct stack *st" 58.Ft void 59.Fn stack_print_short_ddb "struct stack *st" 60.Ft void | |
| 61.Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st" 62.Ft void | 53.Fn stack_sbuf_print "struct sbuf sb*" "struct stack *st" 54.Ft void |
| 63.Fn stack_sbuf_print_ddb "struct sbuf sb*" "struct stack *st" 64.Ft void | |
| 65.Fn stack_save "struct stack *st" 66.Sh DESCRIPTION 67The 68.Nm 69KPI allows querying of kernel stack trace information and the automated 70generation of kernel stack trace strings for the purposes of debugging and 71tracing. | 55.Fn stack_save "struct stack *st" 56.Sh DESCRIPTION 57The 58.Nm 59KPI allows querying of kernel stack trace information and the automated 60generation of kernel stack trace strings for the purposes of debugging and 61tracing. |
| 72To use the KPI, at least one of 73.Cd "options DDB" 74and 75.Cd "options STACK" 76must be compiled into the kernel. | 62.Nm 63relies on the presence of 64.Xr DDB 4 , 65and all use of these functions must be made conditional on 66.Nm DDB 67being compiled in the kernel. |
| 77.Pp 78Each stack trace is described by a 79.Vt "struct stack" . 80Before a trace may be created or otherwise manipulated, storage for the trace 81must be allocated with 82.Fn stack_create , 83which may sleep. | 68.Pp 69Each stack trace is described by a 70.Vt "struct stack" . 71Before a trace may be created or otherwise manipulated, storage for the trace 72must be allocated with 73.Fn stack_create , 74which may sleep. |
| 84Memory associated with a trace is freed by calling | 75Memory associated with a trace may be freed by calling |
| 85.Fn stack_destroy . 86.Pp 87A trace of the current kernel thread's call stack may be captured using | 76.Fn stack_destroy . 77.Pp 78A trace of the current kernel thread's call stack may be captured using |
| 88.Fn stack_save . | 79.Fn stack_capture . |
| 89.Pp | 80.Pp |
| 90.Fn stack_print 91and 92.Fn stack_print_short 93may be used to print a stack trace using the kernel 94.Xr printf 9 , 95and may sleep as a result of acquiring 96.Xr sx 9 97locks in the kernel linker while looking up symbol names. 98In locking-sensitive environments, the unsynchronized 99.Fn stack_print_ddb 100and 101.Fn stack_print_short_ddb 102variants may be invoked. 103This function bypasses kernel linker locking, making it usable in 104.Xr ddb 4 , 105but not in a live system where linker data structures may change. 106.Pp | |
| 107.Fn stack_sbuf_print 108may be used to construct a human-readable string, including conversion (where 109possible) from a simple kernel instruction pointer to a named symbol and 110offset. 111The argument 112.Ar sb 113must be an initialized 114.Dv struct sbuf 115as described in 116.Xr sbuf 9 . 117This function may sleep if an auto-extending 118.Dv struct sbuf | 81.Fn stack_sbuf_print 82may be used to construct a human-readable string, including conversion (where 83possible) from a simple kernel instruction pointer to a named symbol and 84offset. 85The argument 86.Ar sb 87must be an initialized 88.Dv struct sbuf 89as described in 90.Xr sbuf 9 . 91This function may sleep if an auto-extending 92.Dv struct sbuf |
| 119is used, or due to kernel linker locking. 120In locking-sensitive environments, such as 121.Xr ddb 4 , 122the unsynchronized 123.Fn stack_sbuf_print_ddb 124variant may be invoked to avoid kernel linker locking; it should be used with 125a fixed-length sbuf. | 93is used. |
| 126.Pp 127The utility functions 128.Nm stack_zero , 129.Nm stack_copy , 130and 131.Nm stack_put 132may be used to manipulate stack data structures directly. 133.Sh SEE ALSO | 94.Pp 95The utility functions 96.Nm stack_zero , 97.Nm stack_copy , 98and 99.Nm stack_put 100may be used to manipulate stack data structures directly. 101.Sh SEE ALSO |
| 134.Xr ddb 4 , 135.Xr printf 9 , 136.Xr sbuf 9 , 137.Xr sx 9 | 102.Xr DDB 4 |
| 138.Sh AUTHORS 139.An -nosplit 140The 141.Xr stack 9 142function suite was created by 143.An Antoine Brodin . | 103.Sh AUTHORS 104.An -nosplit 105The 106.Xr stack 9 107function suite was created by 108.An Antoine Brodin . |
| 144.Xr stack 9 145was extended by 146.An Robert Watson 147for general-purpose use outside of 148.Xr ddb 4 . | 109.Pp 110This manual page was written by 111.An Robert Watson . |