libunwind/include/unwind.h

   1 //===----------------------------------------------------------------------===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //
   8 // C++ ABI Level 1 ABI documented at:
   9 //   https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html
  10 //
  11 //===----------------------------------------------------------------------===//
  12
  13 #ifndef __UNWIND_H__
  14 #define __UNWIND_H__
  15
  16 #include <__libunwind_config.h>
  17
  18 #include <stdint.h>
  19 #include <stddef.h>
  20
  21 #if defined(__SEH__) && !defined(__USING_SJLJ_EXCEPTIONS__) && defined(_WIN32)
  22 #include <windows.h>
  23 #include <ntverp.h>
  24 #endif
  25
  26 #if defined(__APPLE__)
  27 #define LIBUNWIND_UNAVAIL __attribute__ (( unavailable ))
  28 #else
  29 #define LIBUNWIND_UNAVAIL
  30 #endif
  31
  32 typedef enum {
  33   _URC_NO_REASON = 0,
  34   _URC_OK = 0,
  35   _URC_FOREIGN_EXCEPTION_CAUGHT = 1,
  36   _URC_FATAL_PHASE2_ERROR = 2,
  37   _URC_FATAL_PHASE1_ERROR = 3,
  38   _URC_NORMAL_STOP = 4,
  39   _URC_END_OF_STACK = 5,
  40   _URC_HANDLER_FOUND = 6,
  41   _URC_INSTALL_CONTEXT = 7,
  42   _URC_CONTINUE_UNWIND = 8,
  43 #if defined(_LIBUNWIND_ARM_EHABI)
  44   _URC_FAILURE = 9
  45 #endif
  46 } _Unwind_Reason_Code;
  47
  48 typedef enum {
  49   _UA_SEARCH_PHASE = 1,
  50   _UA_CLEANUP_PHASE = 2,
  51   _UA_HANDLER_FRAME = 4,
  52   _UA_FORCE_UNWIND = 8,
  53   _UA_END_OF_STACK = 16 // gcc extension to C++ ABI
  54 } _Unwind_Action;
  55
  56 typedef struct _Unwind_Context _Unwind_Context;   // opaque
  57
  58 #if defined(_LIBUNWIND_ARM_EHABI)
  59 #include <unwind_arm_ehabi.h>
  60 #else
  61 #include <unwind_itanium.h>
  62 #endif
  63
  64 typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)
  65     (int version,
  66      _Unwind_Action actions,
  67      _Unwind_Exception_Class exceptionClass,
  68      _Unwind_Exception* exceptionObject,
  69      struct _Unwind_Context* context,
  70      void* stop_parameter);
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 extern uintptr_t _Unwind_GetRegionStart(struct _Unwind_Context *context);
  77 extern uintptr_t
  78     _Unwind_GetLanguageSpecificData(struct _Unwind_Context *context);
  79 #ifdef __USING_SJLJ_EXCEPTIONS__
  80 extern _Unwind_Reason_Code
  81     _Unwind_SjLj_ForcedUnwind(_Unwind_Exception *exception_object,
  82                               _Unwind_Stop_Fn stop, void *stop_parameter);
  83 #else
  84 extern _Unwind_Reason_Code
  85     _Unwind_ForcedUnwind(_Unwind_Exception *exception_object,
  86                          _Unwind_Stop_Fn stop, void *stop_parameter);
  87 #endif
  88
  89 #ifdef __USING_SJLJ_EXCEPTIONS__
  90 typedef struct _Unwind_FunctionContext *_Unwind_FunctionContext_t;
  91 extern void _Unwind_SjLj_Register(_Unwind_FunctionContext_t fc);
  92 extern void _Unwind_SjLj_Unregister(_Unwind_FunctionContext_t fc);
  93 #endif
  94
  95 //
  96 // The following are semi-supported extensions to the C++ ABI
  97 //
  98
  99 //
 100 //  called by __cxa_rethrow().
 101 //
 102 #ifdef __USING_SJLJ_EXCEPTIONS__
 103 extern _Unwind_Reason_Code
 104     _Unwind_SjLj_Resume_or_Rethrow(_Unwind_Exception *exception_object);
 105 #else
 106 extern _Unwind_Reason_Code
 107     _Unwind_Resume_or_Rethrow(_Unwind_Exception *exception_object);
 108 #endif
 109
 110 // _Unwind_Backtrace() is a gcc extension that walks the stack and calls the
 111 // _Unwind_Trace_Fn once per frame until it reaches the bottom of the stack
 112 // or the _Unwind_Trace_Fn function returns something other than _URC_NO_REASON.
 113 typedef _Unwind_Reason_Code (*_Unwind_Trace_Fn)(struct _Unwind_Context *,
 114                                                 void *);
 115 extern _Unwind_Reason_Code _Unwind_Backtrace(_Unwind_Trace_Fn, void *);
 116
 117 // _Unwind_GetCFA is a gcc extension that can be called from within a
 118 // personality handler to get the CFA (stack pointer before call) of
 119 // current frame.
 120 extern uintptr_t _Unwind_GetCFA(struct _Unwind_Context *);
 121
 122
 123 // _Unwind_GetIPInfo is a gcc extension that can be called from within a
 124 // personality handler.  Similar to _Unwind_GetIP() but also returns in
 125 // *ipBefore a non-zero value if the instruction pointer is at or before the
 126 // instruction causing the unwind. Normally, in a function call, the IP returned
 127 // is the return address which is after the call instruction and may be past the
 128 // end of the function containing the call instruction.
 129 extern uintptr_t _Unwind_GetIPInfo(struct _Unwind_Context *context,
 130                                    int *ipBefore);
 131
 132
 133 // __register_frame() is used with dynamically generated code to register the
 134 // FDE for a generated (JIT) code.  The FDE must use pc-rel addressing to point
 135 // to its function and optional LSDA.
 136 // __register_frame() has existed in all versions of Mac OS X, but in 10.4 and
 137 // 10.5 it was buggy and did not actually register the FDE with the unwinder.
 138 // In 10.6 and later it does register properly.
 139 extern void __register_frame(const void *fde);
 140 extern void __deregister_frame(const void *fde);
 141
 142 // _Unwind_Find_FDE() will locate the FDE if the pc is in some function that has
 143 // an associated FDE. Note, Mac OS X 10.6 and later, introduces "compact unwind
 144 // info" which the runtime uses in preference to DWARF unwind info.  This
 145 // function will only work if the target function has an FDE but no compact
 146 // unwind info.
 147 struct dwarf_eh_bases {
 148   uintptr_t tbase;
 149   uintptr_t dbase;
 150   uintptr_t func;
 151 };
 152 extern const void *_Unwind_Find_FDE(const void *pc, struct dwarf_eh_bases *);
 153
 154
 155 // This function attempts to find the start (address of first instruction) of
 156 // a function given an address inside the function.  It only works if the
 157 // function has an FDE (DWARF unwind info).
 158 // This function is unimplemented on Mac OS X 10.6 and later.  Instead, use
 159 // _Unwind_Find_FDE() and look at the dwarf_eh_bases.func result.
 160 extern void *_Unwind_FindEnclosingFunction(void *pc);
 161
 162 // Mac OS X does not support text-rel and data-rel addressing so these functions
 163 // are unimplemented.
 164 extern uintptr_t _Unwind_GetDataRelBase(struct _Unwind_Context *context)
 165     LIBUNWIND_UNAVAIL;
 166 extern uintptr_t _Unwind_GetTextRelBase(struct _Unwind_Context *context)
 167     LIBUNWIND_UNAVAIL;
 168
 169 // Mac OS X 10.4 and 10.5 had implementations of these functions in
 170 // libgcc_s.dylib, but they never worked.
 171 /// These functions are no longer available on Mac OS X.
 172 extern void __register_frame_info_bases(const void *fde, void *ob, void *tb,
 173                                         void *db) LIBUNWIND_UNAVAIL;
 174 extern void __register_frame_info(const void *fde, void *ob)
 175     LIBUNWIND_UNAVAIL;
 176 extern void __register_frame_info_table_bases(const void *fde, void *ob,
 177                                               void *tb, void *db)
 178     LIBUNWIND_UNAVAIL;
 179 extern void __register_frame_info_table(const void *fde, void *ob)
 180     LIBUNWIND_UNAVAIL;
 181 extern void __register_frame_table(const void *fde)
 182     LIBUNWIND_UNAVAIL;
 183 extern void *__deregister_frame_info(const void *fde)
 184     LIBUNWIND_UNAVAIL;
 185 extern void *__deregister_frame_info_bases(const void *fde)
 186     LIBUNWIND_UNAVAIL;
 187
 188 #if defined(__SEH__) && !defined(__USING_SJLJ_EXCEPTIONS__)
 189 #ifndef _WIN32
 190 typedef struct _EXCEPTION_RECORD EXCEPTION_RECORD;
 191 typedef struct _CONTEXT CONTEXT;
 192 typedef struct _DISPATCHER_CONTEXT DISPATCHER_CONTEXT;
 193 #elif !defined(__MINGW32__) && VER_PRODUCTBUILD < 8000
 194 typedef struct _DISPATCHER_CONTEXT DISPATCHER_CONTEXT;
 195 #endif
 196 // This is the common wrapper for GCC-style personality functions with SEH.
 197 extern EXCEPTION_DISPOSITION _GCC_specific_handler(EXCEPTION_RECORD *exc,
 198                                                    void *frame, CONTEXT *ctx,
 199                                                    DISPATCHER_CONTEXT *disp,
 200                                                    _Unwind_Personality_Fn pers);
 201 #endif
 202
 203 #ifdef __cplusplus
 204 }
 205 #endif
 206
 207 #endif // __UNWIND_H__