1// Copyright (c) 2016-2021 Apple Inc. All rights reserved.
2//
3// @APPLE_OSREFERENCE_LICENSE_HEADER_START@
4//
5// This file contains Original Code and/or Modifications of Original Code
6// as defined in and that are subject to the Apple Public Source License
7// Version 2.0 (the 'License'). You may not use this file except in
8// compliance with the License. The rights granted to you under the License
9// may not be used to create, or enable the creation or redistribution of,
10// unlawful or unlicensed copies of an Apple operating system, or to
11// circumvent, violate, or enable the circumvention or violation of, any
12// terms of an Apple operating system software license agreement.
13//
14// Please obtain a copy of the License at
15// http://www.opensource.apple.com/apsl/ and read it before using this file.
16//
17// The Original Code and all software distributed under the License are
18// distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
19// EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
20// INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
21// FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
22// Please see the License for the specific language governing rights and
23// limitations under the License.
24//
25// @APPLE_OSREFERENCE_LICENSE_HEADER_END@
26
27#ifndef KERN_BACKTRACE_H
28#define KERN_BACKTRACE_H
29
30// Kernel and user space backtracing (call stack walking) functions.
31//
32// For the current kernel stack, call backtrace from any context:
33//
34// ```c
35// #define MAX_STK_LEN (8)
36//
37// void *ret_addrs[MAX_STK_LEN] = { 0 };
38// backtrace_info_t info = BTI_NONE;
39// unsigned int stk_len = backtrace(ret_addrs, MAX_STK_LEN, NULL, &info);
40// for (unsigned int i = 0; i < stk_len; i++) {
41// printf("%p -> ", ret_addrs[i]);
42// }
43// printf("%s\n", (info & BTI_TRUNCATED) ? "TRUNC" : "NULL");
44// ```
45//
46// For user stacks, call backtrace_user from a faultable context:
47//
48// ```c
49// uintptr_t ret_addrs[MAX_STK_LEN] = { 0 };
50// struct backtrace_user_info info = BTUINFO_INIT;
51// unsigned int stk_len = backtrace_user(ret_addrs, MAX_STK_LEN, NULL, &info);
52// if (info.btui_error != 0) {
53// printf("user space%s stack is %u frames deep\n",
54// (info->btui_info & BTI_TRUNCATED) ? " truncated" : "", stk_len);
55// }
56// ```
57//
58// Refer to documentation in backtrace(9) for more information.
59
60#include <stdbool.h>
61#include <stddef.h>
62#include <stdint.h>
63#include <sys/cdefs.h>
64// XXX Surgically include just the errno_t definition, so this can still be used
65// by Mach.
66#include <sys/_types/_errno_t.h>
67
68__BEGIN_DECLS
69
70// backtrace_flags_t change how the backtraces are recorded.
71__options_decl(backtrace_flags_t, uint32_t, {
72 BTF_NONE = 0x0,
73 // BTF_KERN_INTERRUPTED backtraces the interrupted kernel stack.
74 BTF_KERN_INTERRUPTED = 0x1,
75});
76
77// The copy function is used to copy call stack frame and other information from
78// the target call stack. If an error is returned, the backtrace is aborted.
79typedef errno_t (*backtrace_user_copy_fn)(void *ctx, void *dst, user_addr_t src,
80 size_t size);
81
82// This copy function returns an error when a copy attempt is made, effectively
83// limiting the user backtrace to the PC.
84errno_t backtrace_user_copy_error(void *ctx, void *dst, user_addr_t src,
85 size_t size);
86
87// Parameters that control how the backtrace is taken.
88struct backtrace_control {
89 backtrace_flags_t btc_flags;
90 // The frame address to start backtracing from; set to 0 to start from the
91 // calling frame.
92 uintptr_t btc_frame_addr;
93 // A thread to backtrace user stacks of; must be either the current thread
94 // or one which has been suspended.
95 void *btc_user_thread;
96 // A functions to call instead of the default copyin routine for
97 // user space backtracing.
98 backtrace_user_copy_fn btc_user_copy;
99 // A context to pass to the user copy routine.
100 void *btc_user_copy_context;
101 // Apply an offset to each address stored by the backtracer.
102 int64_t btc_addr_offset;
103};
104
105// Use this offset when walking an async stack, so symbolicators that subtract 1
106// from each address to find the call site see valid symbols, instead of
107// whatever function is at a lower address than the function pointer.
108#define BTCTL_ASYNC_ADDR_OFFSET ((int64_t)1)
109
110#define BTCTL_INIT \
111 ((struct backtrace_control){ \
112 .btc_flags = BTF_NONE, \
113 .btc_frame_addr = 0, \
114 .btc_user_thread = NULL, \
115 .btc_user_copy = NULL, \
116 .btc_user_copy_context = NULL, \
117 .btc_addr_offset = 0, \
118 })
119
120// backtrace_info_t provides information about the backtrace.
121__options_decl(backtrace_info_t, uint32_t, {
122 BTI_NONE = 0x0,
123 // BTI_64_BIT is set when the backtrace is made up of 64-bit addresses.
124 BTI_64_BIT = 0x1,
125 // BTI_TRUNCATED is set when the backtrace has been truncated, either due
126 // to an error copying data, an invalid frame pointer, or running out of
127 // buffer space.
128 BTI_TRUNCATED = 0x2,
129});
130
131// Backtrace the current thread's kernel stack.
132unsigned int backtrace(uintptr_t *bt, unsigned int btlen,
133 struct backtrace_control *ctl, backtrace_info_t *info_out)
134__attribute__((noinline));
135
136// backtrace_pack_t changes the packing scheme for backtraces.
137__enum_decl(backtrace_pack_t, uint32_t, {
138 // Leave the addresses alone.
139 BTP_NONE = 0x0,
140 // Subtract the kernel base address and store each offset in 4 bytes.
141 BTP_KERN_OFFSET_32 = 0x01,
142});
143
144// Backtrace the current thread's kernel stack and store in a packed
145// representation.
146size_t backtrace_packed(backtrace_pack_t packing, uint8_t *bt, size_t btsize,
147 struct backtrace_control *ctl, backtrace_info_t *info_out)
148__attribute__((noinline));
149
150// Convert an array of addresses to a packed representation.
151size_t backtrace_pack(backtrace_pack_t packing, uint8_t *dst,
152 size_t dst_size, const uintptr_t *src, unsigned int src_len);
153
154// Convert a packed backtrace to an array of addresses.
155unsigned int backtrace_unpack(backtrace_pack_t packing, uintptr_t *dst,
156 unsigned int dst_len, const uint8_t *src, size_t src_size);
157
158// backtrace_user_info describes a user backtrace.
159struct backtrace_user_info {
160 backtrace_info_t btui_info;
161 errno_t btui_error;
162 // The index where the start of the async call stack was found.
163 unsigned int btui_async_start_index;
164 // The frame address that can be backtraced to follow the async call stack.
165 uintptr_t btui_async_frame_addr;
166 // The frame address to use to resume the backtrace when the call stack is
167 // truncated by the size of the passed-in buffer.
168 uintptr_t btui_next_frame_addr;
169};
170
171#define BTUINFO_INIT \
172 ((struct backtrace_user_info){ \
173 .btui_error = 0, \
174 .btui_info = BTI_NONE, \
175 .btui_async_start_index = 0, \
176 .btui_async_frame_addr = 0, \
177 .btui_next_frame_addr = 0, \
178 })
179
180// Backtrace a thread's user stack.
181unsigned int backtrace_user(uintptr_t *bt, unsigned int btlen,
182 const struct backtrace_control *ctl, struct backtrace_user_info *info_out);
183
184__END_DECLS
185
186#endif // !defined(KERN_BACKTRACE_H)
187