git.saurik.com Git - apple/xnu.git/blame_incremental

... / ...

Commit	Line	Data
	1	/*
	2	* Copyright (c) 2016-2019 Apple Inc. All rights reserved.
	3	*
	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
	14	*
	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
	25	*
	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	*/
	28
	29	#ifndef KERN_BACKTRACE_H
	30	#define KERN_BACKTRACE_H
	31
	32	#include <stdbool.h>
	33	#include <stdint.h>
	34	#include <sys/cdefs.h>
	35
	36	__BEGIN_DECLS
	37
	38	/*!
	39	* @function backtrace
	40	*
	41	* @abstract backtrace the current thread's kernel stack
	42	*
	43	* @discussion Backtrace the kernel stack of the current thread, storing up
	44	* to btlen return addresses in bt. Returns the number of return addresses
	45	* stored and sets was_truncated to true if it is non-NULL and the backtrace was
	46	* truncated to fit in the provided space. The backtrace starts at the calling
	47	* function. A zero will be stored after the return addresses in the buffer,
	48	* if space allows.
	49	*
	50	* @param bt Clients must provide a buffer in which to store the return
	51	* addresses.
	52	*
	53	* @param btlen Along with the buffer, its length (in terms of uintptr_t) must
	54	* also be provided.
	55	*
	56	* @param was_truncated Optionally, clients can provide a boolean out-parameter
	57	* that will be set to true if the backtrace was truncated due to a lack of
	58	* buffer space.
	59	*
	60	* @return The number of return addresses written to bt is returned. The
	61	* function cannot return an error.
	62	*/
	63	unsigned int backtrace(uintptr_t bt, unsigned int btlen, bool was_truncated)
	64	__attribute__((noinline));
	65
	66	/*!
	67	* @function backtrace_from
	68	*
	69	* @abstract backtrace the current thread's kernel stack from a frame pointer
	70	*
	71	* @discussion Backtrace the kernel stack of the current thread from the given
	72	* frame pointer startfp, storing up to btlen return addresses in bt. Returns
	73	* the number of return addresses written and sets trunc to true if trunc is
	74	* non-NULL and the backtrace was truncated to fit in the provided space. The
	75	* frame pointer provided must point to a valid frame on the current thread's
	76	* stack.
	77	*
	78	* @param startfp The frame pointer to start backtracing from is required, and
	79	* must be point to a valid frame on the current thread's stack.
	80	*
	81	* @seealso backtrace
	82	*/
	83	unsigned int backtrace_frame(uintptr_t bt, unsigned int btlen, void startfp,
	84	bool *was_truncated)
	85	__attribute__((noinline, not_tail_called));
	86
	87	/*!
	88	* @function backtrace_interrupted
	89	*
	90	* @abstract backtrace the interrupted context
	91	*
	92	* @discussion Backtrace the kernel stack of the interrupted thread, storing up
	93	* to btlen return addresses in bt. This function must be called from interrupt
	94	* context.
	95	*
	96	* @seealso backtrace
	97	*/
	98	unsigned int backtrace_interrupted(uintptr_t *bt, unsigned int btlen,
	99	bool *was_truncated);
	100
	101	/*!
	102	* @function backtrace_user
	103	*
	104	* @abstract backtrace the current thread's user space stack
	105	*
	106	* @discussion Backtrace the user stack of the current thread, storing up to
	107	* btlen return addresses in bt. This function cannot be called on a kernel
	108	* thread, nor can it be called from interrupt context or with interrupts
	109	* disabled.
	110	*
	111	* @param error The precise error code that occurred is stored here, or 0 if no
	112	* error occurred.
	113	*
	114	* @param user64 On success, true is stored here if user space was running in
	115	* 64-bit mode, and false is stored otherwise.
	116	*
	117	* @param was_truncated true is stored here if the full stack could not be written
	118	* to bt.
	119	*
	120	* @return Returns the number of frames written to bt.
	121	*
	122	* @seealso backtrace
	123	*/
	124	unsigned int backtrace_user(uintptr_t bt, unsigned int btlen, int error,
	125	bool user64, bool was_truncated);
	126
	127	/*
	128	* @function backtrace_thread_user
	129	*
	130	* @abstract backtrace a given thread's user space stack
	131	*
	132	* @discussion Backtrace the user stack of the given thread, storing up to btlen
	133	* return addresses in bt. This function cannot be called on a kernel thread,
	134	* nor can it be called from interrupt context or with interrupts disabled.
	135	*
	136	* @param thread The user thread to backtrace is required.
	137	*
	138	* @see backtrace_user
	139	*/
	140	unsigned int backtrace_thread_user(void thread, uintptr_t bt,
	141	unsigned int btlen, int error, bool user64, bool *was_truncated,
	142	bool faults_permitted);
	143
	144	__END_DECLS
	145
	146	#endif /* !defined(KERN_BACKTRACE_H) */