1 //===------------------------------- unwind.h -----------------------------===//
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 typedef uint32_t _Unwind_State;
60
61 static const _Unwind_State _US_VIRTUAL_UNWIND_FRAME = 0;
62 static const _Unwind_State _US_UNWIND_FRAME_STARTING = 1;
63 static const _Unwind_State _US_UNWIND_FRAME_RESUME = 2;
64 static const _Unwind_State _US_ACTION_MASK = 3;
65 /* Undocumented flag for force unwinding. */
66 static const _Unwind_State _US_FORCE_UNWIND = 8;
67
68 typedef uint32_t _Unwind_EHT_Header;
69
70 struct _Unwind_Control_Block;
71 typedef struct _Unwind_Control_Block _Unwind_Control_Block;
72 typedef struct _Unwind_Control_Block _Unwind_Exception; /* Alias */
73
74 struct _Unwind_Control_Block {
75 uint64_t exception_class;
76 void (*exception_cleanup)(_Unwind_Reason_Code, _Unwind_Control_Block*);
77
78 /* Unwinder cache, private fields for the unwinder's use */
79 struct {
80 uint32_t reserved1; /* init reserved1 to 0, then don't touch */
81 uint32_t reserved2;
82 uint32_t reserved3;
83 uint32_t reserved4;
84 uint32_t reserved5;
85 } unwinder_cache;
86
87 /* Propagation barrier cache (valid after phase 1): */
88 struct {
89 uint32_t sp;
90 uint32_t bitpattern[5];
91 } barrier_cache;
92
93 /* Cleanup cache (preserved over cleanup): */
94 struct {
95 uint32_t bitpattern[4];
96 } cleanup_cache;
97
98 /* Pr cache (for pr's benefit): */
99 struct {
100 uint32_t fnstart; /* function start address */
101 _Unwind_EHT_Header* ehtp; /* pointer to EHT entry header word */
102 uint32_t additional;
103 uint32_t reserved1;
104 } pr_cache;
105
106 long long int :0; /* Enforce the 8-byte alignment */
107 } __attribute__((__aligned__(8)));
108
109 typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)
110 (_Unwind_State state,
111 _Unwind_Exception* exceptionObject,
112 struct _Unwind_Context* context);
113
114 typedef _Unwind_Reason_Code (*_Unwind_Personality_Fn)(
115 _Unwind_State state, _Unwind_Exception *exceptionObject,
116 struct _Unwind_Context *context);
117 #else
118 struct _Unwind_Context; // opaque
119 struct _Unwind_Exception; // forward declaration
120 typedef struct _Unwind_Exception _Unwind_Exception;
121
122 struct _Unwind_Exception {
123 uint64_t exception_class;
124 void (*exception_cleanup)(_Unwind_Reason_Code reason,
125 _Unwind_Exception *exc);
126 #if defined(__SEH__) && !defined(__USING_SJLJ_EXCEPTIONS__)
127 uintptr_t private_[6];
128 #else
129 uintptr_t private_1; // non-zero means forced unwind
130 uintptr_t private_2; // holds sp that phase1 found for phase2 to use
131 #endif
132 #if __SIZEOF_POINTER__ == 4
133 // The implementation of _Unwind_Exception uses an attribute mode on the
134 // above fields which has the side effect of causing this whole struct to
135 // round up to 32 bytes in size (48 with SEH). To be more explicit, we add
136 // pad fields added for binary compatibility.
137 uint32_t reserved[3];
138 #endif
139 // The Itanium ABI requires that _Unwind_Exception objects are "double-word
140 // aligned". GCC has interpreted this to mean "use the maximum useful
141 // alignment for the target"; so do we.
142 } __attribute__((__aligned__));
143
144 typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)
145 (int version,
146 _Unwind_Action actions,
147 uint64_t exceptionClass,
148 _Unwind_Exception* exceptionObject,
149 struct _Unwind_Context* context,
150 void* stop_parameter );
151
152 typedef _Unwind_Reason_Code (*_Unwind_Personality_Fn)(
153 int version, _Unwind_Action actions, uint64_t exceptionClass,
154 _Unwind_Exception *exceptionObject, struct _Unwind_Context *context);
155 #endif
156
157 #ifdef __cplusplus
158 extern "C" {
159 #endif
160
161 //
162 // The following are the base functions documented by the C++ ABI
163 //
164 #ifdef __USING_SJLJ_EXCEPTIONS__
165 extern _Unwind_Reason_Code
166 _Unwind_SjLj_RaiseException(_Unwind_Exception *exception_object);
167 extern void _Unwind_SjLj_Resume(_Unwind_Exception *exception_object);
168 #else
169 extern _Unwind_Reason_Code
170 _Unwind_RaiseException(_Unwind_Exception *exception_object);
171 extern void _Unwind_Resume(_Unwind_Exception *exception_object);
172 #endif
173 extern void _Unwind_DeleteException(_Unwind_Exception *exception_object);
174
175 #if defined(_LIBUNWIND_ARM_EHABI)
176 typedef enum {
177 _UVRSC_CORE = 0, /* integer register */
178 _UVRSC_VFP = 1, /* vfp */
179 _UVRSC_WMMXD = 3, /* Intel WMMX data register */
180 _UVRSC_WMMXC = 4 /* Intel WMMX control register */
181 } _Unwind_VRS_RegClass;
182
183 typedef enum {
184 _UVRSD_UINT32 = 0,
185 _UVRSD_VFPX = 1,
186 _UVRSD_UINT64 = 3,
187 _UVRSD_FLOAT = 4,
188 _UVRSD_DOUBLE = 5
189 } _Unwind_VRS_DataRepresentation;
190
191 typedef enum {
192 _UVRSR_OK = 0,
193 _UVRSR_NOT_IMPLEMENTED = 1,
194 _UVRSR_FAILED = 2
195 } _Unwind_VRS_Result;
196
197 extern void _Unwind_Complete(_Unwind_Exception* exception_object);
198
199 extern _Unwind_VRS_Result
200 _Unwind_VRS_Get(_Unwind_Context *context, _Unwind_VRS_RegClass regclass,
201 uint32_t regno, _Unwind_VRS_DataRepresentation representation,
202 void *valuep);
203
204 extern _Unwind_VRS_Result
205 _Unwind_VRS_Set(_Unwind_Context *context, _Unwind_VRS_RegClass regclass,
206 uint32_t regno, _Unwind_VRS_DataRepresentation representation,
207 void *valuep);
208
209 extern _Unwind_VRS_Result
210 _Unwind_VRS_Pop(_Unwind_Context *context, _Unwind_VRS_RegClass regclass,
211 uint32_t discriminator,
212 _Unwind_VRS_DataRepresentation representation);
213 #endif
214
215 #if !defined(_LIBUNWIND_ARM_EHABI)
216
217 extern uintptr_t _Unwind_GetGR(struct _Unwind_Context *context, int index);
218 extern void _Unwind_SetGR(struct _Unwind_Context *context, int index,
219 uintptr_t new_value);
220 extern uintptr_t _Unwind_GetIP(struct _Unwind_Context *context);
221 extern void _Unwind_SetIP(struct _Unwind_Context *, uintptr_t new_value);
222
223 #else // defined(_LIBUNWIND_ARM_EHABI)
224
225 #if defined(_LIBUNWIND_UNWIND_LEVEL1_EXTERNAL_LINKAGE)
226 #define _LIBUNWIND_EXPORT_UNWIND_LEVEL1 extern
227 #else
228 #define _LIBUNWIND_EXPORT_UNWIND_LEVEL1 static __inline__
229 #endif
230
231 // These are de facto helper functions for ARM, which delegate the function
232 // calls to _Unwind_VRS_Get/Set(). These are not a part of ARM EHABI
233 // specification, thus these function MUST be inlined. Please don't replace
234 // these with the "extern" function declaration; otherwise, the program
235 // including this <unwind.h> header won't be ABI compatible and will result in
236 // link error when we are linking the program with libgcc.
237
238 _LIBUNWIND_EXPORT_UNWIND_LEVEL1
_Unwind_GetGR(struct _Unwind_Context * context,int index)239 uintptr_t _Unwind_GetGR(struct _Unwind_Context *context, int index) {
240 uintptr_t value = 0;
241 _Unwind_VRS_Get(context, _UVRSC_CORE, (uint32_t)index, _UVRSD_UINT32, &value);
242 return value;
243 }
244
245 _LIBUNWIND_EXPORT_UNWIND_LEVEL1
_Unwind_SetGR(struct _Unwind_Context * context,int index,uintptr_t value)246 void _Unwind_SetGR(struct _Unwind_Context *context, int index,
247 uintptr_t value) {
248 _Unwind_VRS_Set(context, _UVRSC_CORE, (uint32_t)index, _UVRSD_UINT32, &value);
249 }
250
251 _LIBUNWIND_EXPORT_UNWIND_LEVEL1
_Unwind_GetIP(struct _Unwind_Context * context)252 uintptr_t _Unwind_GetIP(struct _Unwind_Context *context) {
253 // remove the thumb-bit before returning
254 return _Unwind_GetGR(context, 15) & (~(uintptr_t)0x1);
255 }
256
257 _LIBUNWIND_EXPORT_UNWIND_LEVEL1
_Unwind_SetIP(struct _Unwind_Context * context,uintptr_t value)258 void _Unwind_SetIP(struct _Unwind_Context *context, uintptr_t value) {
259 uintptr_t thumb_bit = _Unwind_GetGR(context, 15) & ((uintptr_t)0x1);
260 _Unwind_SetGR(context, 15, value | thumb_bit);
261 }
262 #endif // defined(_LIBUNWIND_ARM_EHABI)
263
264 extern uintptr_t _Unwind_GetRegionStart(struct _Unwind_Context *context);
265 extern uintptr_t
266 _Unwind_GetLanguageSpecificData(struct _Unwind_Context *context);
267 #ifdef __USING_SJLJ_EXCEPTIONS__
268 extern _Unwind_Reason_Code
269 _Unwind_SjLj_ForcedUnwind(_Unwind_Exception *exception_object,
270 _Unwind_Stop_Fn stop, void *stop_parameter);
271 #else
272 extern _Unwind_Reason_Code
273 _Unwind_ForcedUnwind(_Unwind_Exception *exception_object,
274 _Unwind_Stop_Fn stop, void *stop_parameter);
275 #endif
276
277 #ifdef __USING_SJLJ_EXCEPTIONS__
278 typedef struct _Unwind_FunctionContext *_Unwind_FunctionContext_t;
279 extern void _Unwind_SjLj_Register(_Unwind_FunctionContext_t fc);
280 extern void _Unwind_SjLj_Unregister(_Unwind_FunctionContext_t fc);
281 #endif
282
283 //
284 // The following are semi-suppoted extensions to the C++ ABI
285 //
286
287 //
288 // called by __cxa_rethrow().
289 //
290 #ifdef __USING_SJLJ_EXCEPTIONS__
291 extern _Unwind_Reason_Code
292 _Unwind_SjLj_Resume_or_Rethrow(_Unwind_Exception *exception_object);
293 #else
294 extern _Unwind_Reason_Code
295 _Unwind_Resume_or_Rethrow(_Unwind_Exception *exception_object);
296 #endif
297
298 // _Unwind_Backtrace() is a gcc extension that walks the stack and calls the
299 // _Unwind_Trace_Fn once per frame until it reaches the bottom of the stack
300 // or the _Unwind_Trace_Fn function returns something other than _URC_NO_REASON.
301 typedef _Unwind_Reason_Code (*_Unwind_Trace_Fn)(struct _Unwind_Context *,
302 void *);
303 extern _Unwind_Reason_Code _Unwind_Backtrace(_Unwind_Trace_Fn, void *);
304
305 // _Unwind_GetCFA is a gcc extension that can be called from within a
306 // personality handler to get the CFA (stack pointer before call) of
307 // current frame.
308 extern uintptr_t _Unwind_GetCFA(struct _Unwind_Context *);
309
310
311 // _Unwind_GetIPInfo is a gcc extension that can be called from within a
312 // personality handler. Similar to _Unwind_GetIP() but also returns in
313 // *ipBefore a non-zero value if the instruction pointer is at or before the
314 // instruction causing the unwind. Normally, in a function call, the IP returned
315 // is the return address which is after the call instruction and may be past the
316 // end of the function containing the call instruction.
317 extern uintptr_t _Unwind_GetIPInfo(struct _Unwind_Context *context,
318 int *ipBefore);
319
320
321 // __register_frame() is used with dynamically generated code to register the
322 // FDE for a generated (JIT) code. The FDE must use pc-rel addressing to point
323 // to its function and optional LSDA.
324 // __register_frame() has existed in all versions of Mac OS X, but in 10.4 and
325 // 10.5 it was buggy and did not actually register the FDE with the unwinder.
326 // In 10.6 and later it does register properly.
327 extern void __register_frame(const void *fde);
328 extern void __deregister_frame(const void *fde);
329
330 // _Unwind_Find_FDE() will locate the FDE if the pc is in some function that has
331 // an associated FDE. Note, Mac OS X 10.6 and later, introduces "compact unwind
332 // info" which the runtime uses in preference to DWARF unwind info. This
333 // function will only work if the target function has an FDE but no compact
334 // unwind info.
335 struct dwarf_eh_bases {
336 uintptr_t tbase;
337 uintptr_t dbase;
338 uintptr_t func;
339 };
340 extern const void *_Unwind_Find_FDE(const void *pc, struct dwarf_eh_bases *);
341
342
343 // This function attempts to find the start (address of first instruction) of
344 // a function given an address inside the function. It only works if the
345 // function has an FDE (DWARF unwind info).
346 // This function is unimplemented on Mac OS X 10.6 and later. Instead, use
347 // _Unwind_Find_FDE() and look at the dwarf_eh_bases.func result.
348 extern void *_Unwind_FindEnclosingFunction(void *pc);
349
350 // Mac OS X does not support text-rel and data-rel addressing so these functions
351 // are unimplemented
352 extern uintptr_t _Unwind_GetDataRelBase(struct _Unwind_Context *context)
353 LIBUNWIND_UNAVAIL;
354 extern uintptr_t _Unwind_GetTextRelBase(struct _Unwind_Context *context)
355 LIBUNWIND_UNAVAIL;
356
357 // Mac OS X 10.4 and 10.5 had implementations of these functions in
358 // libgcc_s.dylib, but they never worked.
359 /// These functions are no longer available on Mac OS X.
360 extern void __register_frame_info_bases(const void *fde, void *ob, void *tb,
361 void *db) LIBUNWIND_UNAVAIL;
362 extern void __register_frame_info(const void *fde, void *ob)
363 LIBUNWIND_UNAVAIL;
364 extern void __register_frame_info_table_bases(const void *fde, void *ob,
365 void *tb, void *db)
366 LIBUNWIND_UNAVAIL;
367 extern void __register_frame_info_table(const void *fde, void *ob)
368 LIBUNWIND_UNAVAIL;
369 extern void __register_frame_table(const void *fde)
370 LIBUNWIND_UNAVAIL;
371 extern void *__deregister_frame_info(const void *fde)
372 LIBUNWIND_UNAVAIL;
373 extern void *__deregister_frame_info_bases(const void *fde)
374 LIBUNWIND_UNAVAIL;
375
376 #if defined(__SEH__) && !defined(__USING_SJLJ_EXCEPTIONS__)
377 #ifndef _WIN32
378 typedef struct _EXCEPTION_RECORD EXCEPTION_RECORD;
379 typedef struct _CONTEXT CONTEXT;
380 typedef struct _DISPATCHER_CONTEXT DISPATCHER_CONTEXT;
381 #elif !defined(__MINGW32__) && VER_PRODUCTBUILD < 8000
382 typedef struct _DISPATCHER_CONTEXT DISPATCHER_CONTEXT;
383 #endif
384 // This is the common wrapper for GCC-style personality functions with SEH.
385 extern EXCEPTION_DISPOSITION _GCC_specific_handler(EXCEPTION_RECORD *exc,
386 void *frame, CONTEXT *ctx,
387 DISPATCHER_CONTEXT *disp,
388 _Unwind_Personality_Fn pers);
389 #endif
390
391 #ifdef __cplusplus
392 }
393 #endif
394
395 #endif // __UNWIND_H__
396