/*
- * Copyright (c) 2016 Apple Inc. All rights reserved.
+ * Copyright (c) 2016-2019 Apple Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
-#ifndef BACKTRACE_H
-#define BACKTRACE_H
+#ifndef KERN_BACKTRACE_H
+#define KERN_BACKTRACE_H
#include <stdbool.h>
#include <stdint.h>
__BEGIN_DECLS
-/*
- * Backtrace the current thread, storing up to max_frames return addresses in
- * bt. Returns the number of return addresses stored.
+/*!
+ * @function backtrace
+ *
+ * @abstract backtrace the current thread's kernel stack
+ *
+ * @discussion Backtrace the kernel stack of the current thread, storing up
+ * to btlen return addresses in bt. Returns the number of return addresses
+ * stored and sets was_truncated to true if it is non-NULL and the backtrace was
+ * truncated to fit in the provided space. The backtrace starts at the calling
+ * function. A zero will be stored after the return addresses in the buffer,
+ * if space allows.
+ *
+ * @param bt Clients must provide a buffer in which to store the return
+ * addresses.
+ *
+ * @param btlen Along with the buffer, its length (in terms of uintptr_t) must
+ * also be provided.
+ *
+ * @param was_truncated Optionally, clients can provide a boolean out-parameter
+ * that will be set to true if the backtrace was truncated due to a lack of
+ * buffer space.
+ *
+ * @return The number of return addresses written to bt is returned. The
+ * function cannot return an error.
*/
-uint32_t backtrace(uintptr_t *bt, uint32_t max_frames)
+unsigned int backtrace(uintptr_t *bt, unsigned int btlen, bool *was_truncated)
__attribute__((noinline));
-/*
- * Backtrace the current thread starting at the frame pointer start_fp, storing
- * up to max_frames return addresses in bt. Returns the number of return
- * addresses stored.
+/*!
+ * @function backtrace_from
+ *
+ * @abstract backtrace the current thread's kernel stack from a frame pointer
+ *
+ * @discussion Backtrace the kernel stack of the current thread from the given
+ * frame pointer startfp, storing up to btlen return addresses in bt. Returns
+ * the number of return addresses written and sets trunc to true if trunc is
+ * non-NULL and the backtrace was truncated to fit in the provided space. The
+ * frame pointer provided must point to a valid frame on the current thread's
+ * stack.
+ *
+ * @param startfp The frame pointer to start backtracing from is required, and
+ * must be point to a valid frame on the current thread's stack.
+ *
+ * @seealso backtrace
*/
-uint32_t backtrace_frame(uintptr_t *bt, uint32_t max_frames, void *start_frame)
+unsigned int backtrace_frame(uintptr_t *bt, unsigned int btlen, void *startfp,
+ bool *was_truncated)
__attribute__((noinline, not_tail_called));
-/*
- * Backtrace the kernel stack of the context that was interrupted, storing up
- * to max_frames return addresses in bt. Returns 0 on success, and non-zero
- * otherwise. On success, the number of frames written is stored at the value
- * pointed to by frames_out.
+/*!
+ * @function backtrace_interrupted
*
- * Must be called from interrupt context.
+ * @abstract backtrace the interrupted context
+ *
+ * @discussion Backtrace the kernel stack of the interrupted thread, storing up
+ * to btlen return addresses in bt. This function must be called from interrupt
+ * context.
+ *
+ * @seealso backtrace
*/
-uint32_t backtrace_interrupted(uintptr_t *bt, uint32_t max_frames);
+unsigned int backtrace_interrupted(uintptr_t *bt, unsigned int btlen,
+ bool *was_truncated);
-/*
- * Backtrace the user stack of the current thread, storing up to max_frames
- * return addresses in bt. Returns 0 on success, and non-zero otherwise. On
- * success, the number of frames written is stored at the value pointed to by
- * frames_out and the value pointed to by user_64_out is set true if the user
- * space thread was running in 64-bit mode, and false otherwise.
+/*!
+ * @function backtrace_user
+ *
+ * @abstract backtrace the current thread's user space stack
+ *
+ * @discussion Backtrace the user stack of the current thread, storing up to
+ * btlen return addresses in bt. This function cannot be called on a kernel
+ * thread, nor can it be called from interrupt context or with interrupts
+ * disabled.
+ *
+ * @param error The precise error code that occurred is stored here, or 0 if no
+ * error occurred.
*
- * Must not be called from interrupt context or with interrupts disabled.
+ * @param user64 On success, true is stored here if user space was running in
+ * 64-bit mode, and false is stored otherwise.
+ *
+ * @param was_truncated true is stored here if the full stack could not be written
+ * to bt.
+ *
+ * @return Returns the number of frames written to bt.
+ *
+ * @seealso backtrace
*/
-int backtrace_user(uintptr_t *bt, uint32_t max_frames, uint32_t *frames_out,
- bool *user_64_out);
+unsigned int backtrace_user(uintptr_t *bt, unsigned int btlen, int *error,
+ bool *user64, bool *was_truncated);
/*
- * Backtrace the user stack of the given thread, storing up to max_frames return
- * addresses in bt. Returns 0 on success, and non-zero otherwise. On success,
- * the number of frames written is stored at the value pointed to by frames_out
- * and the value pointed to by user_64_out is set true if the user space thread
- * was running in 64-bit mode, and false otherwise.
+ * @function backtrace_thread_user
+ *
+ * @abstract backtrace a given thread's user space stack
+ *
+ * @discussion Backtrace the user stack of the given thread, storing up to btlen
+ * return addresses in bt. This function cannot be called on a kernel thread,
+ * nor can it be called from interrupt context or with interrupts disabled.
+ *
+ * @param thread The user thread to backtrace is required.
*
- * Must not be called from interrupt context or with interrupts disabled.
+ * @see backtrace_user
*/
-int backtrace_thread_user(void *thread, uintptr_t *bt, uint32_t max_frames,
- uint32_t *frames_out, bool *user_64_out);
+unsigned int backtrace_thread_user(void *thread, uintptr_t *bt,
+ unsigned int btlen, int *error, bool *user64, bool *was_truncated);
__END_DECLS
-#endif /* !defined(BACKTRACE_H) */
+#endif /* !defined(KERN_BACKTRACE_H) */
projects / apple / xnu.git / blobdiff