osfmk/kern/backtrace.h

   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) */