#include <kern/backtrace.h>
Kernel (KEXT) › kern/ primitives

kern/backtrace.h Kernel.framework

includes: Kernel/stdbool.h, Kernel/stddef.h, Kernel/stdint.h, sys/cdefs.h, Kernel/sys/_types/_errno_t.h
6 functions · 4 macros · 4 typedefs · 3 enums · 2 structs

macroKERN_BACKTRACE_H

#define KERN_BACKTRACE_H

enumbacktrace_flags_t

backtrace_flags_t change how the backtraces are recorded.
underlying type uint32_t
BTF_NONE0
BTF_KERN_INTERRUPTED1

typedefbacktrace_flags_t

typedef enum backtrace_flags_t backtrace_flags_t;

typedefbacktrace_user_copy_fn

The copy function is used to copy call stack frame and other information from the target call stack. If an error is returned, the backtrace is aborted.
typedef errno_t (*)(void *, void *, user_addr_t, size_t) backtrace_user_copy_fn;

functionbacktrace_user_copy_error

errno_t backtrace_user_copy_error(void *ctx, void *dst, user_addr_t src, size_t size)
This copy function returns an error when a copy attempt is made, effectively limiting the user backtrace to the PC.

structbacktrace_control

Parameters that control how the backtrace is taken.
size 48, align 8
backtrace_flags_tbtc_flags
uintptr_tbtc_frame_addrThe frame address to start backtracing from; set to 0 to start from the calling frame.
void *btc_user_threadA thread to backtrace user stacks of; must be either the current thread or one which has been suspended.
backtrace_user_copy_fnbtc_user_copyA functions to call instead of the default copyin routine for user space backtracing.
void *btc_user_copy_contextA context to pass to the user copy routine.
int64_tbtc_addr_offsetApply an offset to each address stored by the backtracer.

macroBTCTL_ASYNC_ADDR_OFFSET

Use this offset when walking an async stack, so symbolicators that subtract 1 from each address to find the call site see valid symbols, instead of whatever function is at a lower address than the function pointer.
#define BTCTL_ASYNC_ADDR_OFFSET ((int64_t)1)

macroBTCTL_INIT

#define BTCTL_INIT ((struct backtrace_control){
			.btc_flags = BTF_NONE,
			.btc_frame_addr = 0,
			.btc_user_thread = NULL,
			.btc_user_copy = NULL,
			.btc_user_copy_context = NULL,
			.btc_addr_offset = 0,
		})

enumbacktrace_info_t

backtrace_info_t provides information about the backtrace.
underlying type uint32_t
BTI_NONE0
BTI_64_BIT1
BTI_TRUNCATED2

typedefbacktrace_info_t

typedef enum backtrace_info_t backtrace_info_t;

functionbacktrace

__attribute__((noinline))
unsigned int backtrace(
	uintptr_t *bt,
	unsigned int btlen,
	struct backtrace_control *ctl,
	backtrace_info_t *info_out
)
Backtrace the current thread's kernel stack.

enumbacktrace_pack_t

backtrace_pack_t changes the packing scheme for backtraces.
underlying type uint32_t
BTP_NONE0
BTP_KERN_OFFSET_321

typedefbacktrace_pack_t

typedef enum backtrace_pack_t backtrace_pack_t;

functionbacktrace_packed

__attribute__((noinline))
size_t backtrace_packed(
	backtrace_pack_t packing,
	uint8_t *bt,
	size_t btsize,
	struct backtrace_control *ctl,
	backtrace_info_t *info_out
)
Backtrace the current thread's kernel stack and store in a packed representation.

functionbacktrace_pack

size_t backtrace_pack(
	backtrace_pack_t packing,
	uint8_t *dst,
	size_t dst_size,
	const uintptr_t *src,
	unsigned int src_len
)
Convert an array of addresses to a packed representation.

functionbacktrace_unpack

unsigned int backtrace_unpack(
	backtrace_pack_t packing,
	uintptr_t *dst,
	unsigned int dst_len,
	const uint8_t *src,
	size_t src_size
)
Convert a packed backtrace to an array of addresses.

structbacktrace_user_info

backtrace_user_info describes a user backtrace.
size 32, align 8
backtrace_info_tbtui_info
errno_tbtui_error
unsigned intbtui_async_start_indexThe index where the start of the async call stack was found.
uintptr_tbtui_async_frame_addrThe frame address that can be backtraced to follow the async call stack.
uintptr_tbtui_next_frame_addrThe frame address to use to resume the backtrace when the call stack is truncated by the size of the passed-in buffer.

macroBTUINFO_INIT

#define BTUINFO_INIT ((struct backtrace_user_info){
			.btui_error = 0,
			.btui_info = BTI_NONE,
			.btui_async_start_index = 0,
			.btui_async_frame_addr = 0,
			.btui_next_frame_addr = 0,
		})

functionbacktrace_user

unsigned int backtrace_user(
	uintptr_t *bt,
	unsigned int btlen,
	const struct backtrace_control *ctl,
	struct backtrace_user_info *info_out
)
Backtrace a thread's user stack.