libgcc/unwind-generic.h

   1 /* Exception handling and frame unwind runtime interface routines.
   2    Copyright (C) 2001-2024 Free Software Foundation, Inc.
   3
   4    This file is part of GCC.
   5
   6    GCC is free software; you can redistribute it and/or modify it
   7    under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3, or (at your option)
   9    any later version.
  10
  11    GCC is distributed in the hope that it will be useful, but WITHOUT
  12    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13    or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
  14    License for more details.
  15
  16    Under Section 7 of GPL version 3, you are granted additional
  17    permissions described in the GCC Runtime Library Exception, version
  18    3.1, as published by the Free Software Foundation.
  19
  20    You should have received a copy of the GNU General Public License and
  21    a copy of the GCC Runtime Library Exception along with this program;
  22    see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  23    <http://www.gnu.org/licenses/>.  */
  24
  25 /* This is derived from the C++ ABI for IA-64.  Where we diverge
  26    for cross-architecture compatibility are noted with "@@@".  */
  27
  28 #ifndef _UNWIND_H
  29 #define _UNWIND_H
  30
  31 #if defined (__SEH__) && !defined (__USING_SJLJ_EXCEPTIONS__)
  32 /* Only for _GCC_specific_handler.  */
  33 #define WIN32_LEAN_AND_MEAN
  34 #include <windows.h>
  35 #endif
  36
  37 #ifndef HIDE_EXPORTS
  38 #pragma GCC visibility push(default)
  39 #endif
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /* Level 1: Base ABI  */
  46
  47 /* @@@ The IA-64 ABI uses uint64 throughout.  Most places this is
  48    inefficient for 32-bit and smaller machines.  */
  49 typedef unsigned _Unwind_Word __attribute__((__mode__(__unwind_word__)));
  50 typedef signed _Unwind_Sword __attribute__((__mode__(__unwind_word__)));
  51 #if defined(__ia64__) && defined(__hpux__)
  52 typedef unsigned _Unwind_Ptr __attribute__((__mode__(__word__)));
  53 #else
  54 typedef unsigned _Unwind_Ptr __attribute__((__mode__(__pointer__)));
  55 #endif
  56 typedef unsigned _Unwind_Internal_Ptr __attribute__((__mode__(__pointer__)));
  57
  58 /* @@@ The IA-64 ABI uses a 64-bit word to identify the producer and
  59    consumer of an exception.  We'll go along with this for now even on
  60    32-bit machines.  We'll need to provide some other option for
  61    16-bit machines and for machines with > 8 bits per byte.  */
  62 typedef unsigned _Unwind_Exception_Class __attribute__((__mode__(__DI__)));
  63
  64 /* The unwind interface uses reason codes in several contexts to
  65    identify the reasons for failures or other actions.  */
  66 typedef enum
  67 {
  68   _URC_NO_REASON = 0,
  69   _URC_FOREIGN_EXCEPTION_CAUGHT = 1,
  70   _URC_FATAL_PHASE2_ERROR = 2,
  71   _URC_FATAL_PHASE1_ERROR = 3,
  72   _URC_NORMAL_STOP = 4,
  73   _URC_END_OF_STACK = 5,
  74   _URC_HANDLER_FOUND = 6,
  75   _URC_INSTALL_CONTEXT = 7,
  76   _URC_CONTINUE_UNWIND = 8
  77 } _Unwind_Reason_Code;
  78
  79
  80 /* The unwind interface uses a pointer to an exception header object
  81    as its representation of an exception being thrown. In general, the
  82    full representation of an exception object is language- and
  83    implementation-specific, but it will be prefixed by a header
  84    understood by the unwind interface.  */
  85
  86 struct _Unwind_Exception;
  87
  88 typedef void (*_Unwind_Exception_Cleanup_Fn) (_Unwind_Reason_Code,
  89                                               struct _Unwind_Exception *);
  90
  91 struct _Unwind_Exception
  92 {
  93   _Unwind_Exception_Class exception_class;
  94   _Unwind_Exception_Cleanup_Fn exception_cleanup;
  95
  96 #if !defined (__USING_SJLJ_EXCEPTIONS__) && defined (__SEH__)
  97   _Unwind_Word private_[6];
  98 #else
  99   _Unwind_Word private_1;
 100   _Unwind_Word private_2;
 101 #endif
 102
 103   /* @@@ The IA-64 ABI says that this structure must be double-word aligned.
 104      Taking that literally does not make much sense generically.  Instead we
 105      provide the maximum alignment required by any type for the machine.  */
 106 } __attribute__((__aligned__));
 107
 108
 109 /* The ACTIONS argument to the personality routine is a bitwise OR of one
 110    or more of the following constants.  */
 111 typedef int _Unwind_Action;
 112
 113 #define _UA_SEARCH_PHASE        1
 114 #define _UA_CLEANUP_PHASE       2
 115 #define _UA_HANDLER_FRAME       4
 116 #define _UA_FORCE_UNWIND        8
 117 #define _UA_END_OF_STACK        16
 118
 119 /* The target can override this macro to define any back-end-specific
 120    attributes required for the lowest-level stack frame.  */
 121 #ifndef LIBGCC2_UNWIND_ATTRIBUTE
 122 #define LIBGCC2_UNWIND_ATTRIBUTE
 123 #endif
 124
 125 /* This is an opaque type used to refer to a system-specific data
 126    structure used by the system unwinder. This context is created and
 127    destroyed by the system, and passed to the personality routine
 128    during unwinding.  */
 129 struct _Unwind_Context;
 130
 131 /* Raise an exception, passing along the given exception object.  */
 132 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 133 _Unwind_RaiseException (struct _Unwind_Exception *);
 134
 135 /* Raise an exception for forced unwinding.  */
 136
 137 typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)
 138      (int, _Unwind_Action, _Unwind_Exception_Class,
 139       struct _Unwind_Exception *, struct _Unwind_Context *, void *);
 140
 141 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 142 _Unwind_ForcedUnwind (struct _Unwind_Exception *, _Unwind_Stop_Fn, void *);
 143
 144 /* Helper to invoke the exception_cleanup routine.  */
 145 extern void _Unwind_DeleteException (struct _Unwind_Exception *);
 146
 147 /* Resume propagation of an existing exception.  This is used after
 148    e.g. executing cleanup code, and not to implement rethrowing.  */
 149 extern void LIBGCC2_UNWIND_ATTRIBUTE
 150 _Unwind_Resume (struct _Unwind_Exception *);
 151
 152 /* @@@ Resume propagation of a FORCE_UNWIND exception, or to rethrow
 153    a normal exception that was handled.  */
 154 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 155 _Unwind_Resume_or_Rethrow (struct _Unwind_Exception *);
 156
 157 /* @@@ Use unwind data to perform a stack backtrace.  The trace callback
 158    is called for every stack frame in the call chain, but no cleanup
 159    actions are performed.  */
 160 typedef _Unwind_Reason_Code (*_Unwind_Trace_Fn)
 161      (struct _Unwind_Context *, void *);
 162
 163 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 164 _Unwind_Backtrace (_Unwind_Trace_Fn, void *);
 165
 166 /* These functions are used for communicating information about the unwind
 167    context (i.e. the unwind descriptors and the user register state) between
 168    the unwind library and the personality routine and landing pad.  Only
 169    selected registers may be manipulated.  */
 170
 171 extern _Unwind_Word _Unwind_GetGR (struct _Unwind_Context *, int);
 172 extern void _Unwind_SetGR (struct _Unwind_Context *, int, _Unwind_Word);
 173
 174 extern _Unwind_Ptr _Unwind_GetIP (struct _Unwind_Context *);
 175 extern _Unwind_Ptr _Unwind_GetIPInfo (struct _Unwind_Context *, int *);
 176 extern void _Unwind_SetIP (struct _Unwind_Context *, _Unwind_Ptr);
 177
 178 /* @@@ Retrieve the CFA of the given context.  */
 179 extern _Unwind_Word _Unwind_GetCFA (struct _Unwind_Context *);
 180
 181 extern void *_Unwind_GetLanguageSpecificData (struct _Unwind_Context *);
 182
 183 extern _Unwind_Ptr _Unwind_GetRegionStart (struct _Unwind_Context *);
 184
 185
 186 /* The personality routine is the function in the C++ (or other language)
 187    runtime library which serves as an interface between the system unwind
 188    library and language-specific exception handling semantics.  It is
 189    specific to the code fragment described by an unwind info block, and
 190    it is always referenced via the pointer in the unwind info block, and
 191    hence it has no ABI-specified name.
 192
 193    Note that this implies that two different C++ implementations can
 194    use different names, and have different contents in the language
 195    specific data area.  Moreover, that the language specific data
 196    area contains no version info because name of the function invoked
 197    provides more effective versioning by detecting at link time the
 198    lack of code to handle the different data format.  */
 199
 200 typedef _Unwind_Reason_Code (*_Unwind_Personality_Fn)
 201      (int, _Unwind_Action, _Unwind_Exception_Class,
 202       struct _Unwind_Exception *, struct _Unwind_Context *);
 203
 204 /* @@@ The following alternate entry points are for setjmp/longjmp
 205    based unwinding.  */
 206
 207 struct SjLj_Function_Context;
 208 extern void _Unwind_SjLj_Register (struct SjLj_Function_Context *);
 209 extern void _Unwind_SjLj_Unregister (struct SjLj_Function_Context *);
 210
 211 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 212 _Unwind_SjLj_RaiseException (struct _Unwind_Exception *);
 213 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 214 _Unwind_SjLj_ForcedUnwind (struct _Unwind_Exception *, _Unwind_Stop_Fn, void *);
 215 extern void LIBGCC2_UNWIND_ATTRIBUTE
 216 _Unwind_SjLj_Resume (struct _Unwind_Exception *);
 217 extern _Unwind_Reason_Code LIBGCC2_UNWIND_ATTRIBUTE
 218 _Unwind_SjLj_Resume_or_Rethrow (struct _Unwind_Exception *);
 219
 220 /* @@@ The following provide access to the base addresses for text
 221    and data-relative addressing in the LDSA.  In order to stay link
 222    compatible with the standard ABI for IA-64, we inline these.  */
 223
 224 #ifdef __ia64__
 225 static inline _Unwind_Ptr
 226 _Unwind_GetDataRelBase (struct _Unwind_Context *_C)
 227 {
 228   /* The GP is stored in R1.  */
 229   return _Unwind_GetGR (_C, 1);
 230 }
 231
 232 static inline _Unwind_Ptr
 233 _Unwind_GetTextRelBase (struct _Unwind_Context *_C __attribute__ ((__unused__)))
 234 {
 235   __builtin_abort ();
 236   return 0;
 237 }
 238
 239 /* @@@ Retrieve the Backing Store Pointer of the given context.  */
 240 extern _Unwind_Word _Unwind_GetBSP (struct _Unwind_Context *);
 241 #else
 242 extern _Unwind_Ptr _Unwind_GetDataRelBase (struct _Unwind_Context *);
 243 extern _Unwind_Ptr _Unwind_GetTextRelBase (struct _Unwind_Context *);
 244 #endif
 245
 246 /* @@@ Given an address, return the entry point of the function that
 247    contains it.  */
 248 extern void * _Unwind_FindEnclosingFunction (void *pc);
 249
 250 #ifndef __SIZEOF_LONG__
 251   #error "__SIZEOF_LONG__ macro not defined"
 252 #endif
 253
 254 #ifndef __SIZEOF_POINTER__
 255   #error "__SIZEOF_POINTER__ macro not defined"
 256 #endif
 257
 258
 259 /* leb128 type numbers have a potentially unlimited size.
 260    The target of the following definitions of _sleb128_t and _uleb128_t
 261    is to have efficient data types large enough to hold the leb128 type
 262    numbers used in the unwind code.
 263    Mostly these types will simply be defined to long and unsigned long
 264    except when a unsigned long data type on the target machine is not
 265    capable of storing a pointer.  */
 266
 267 #if __SIZEOF_LONG__ >= __SIZEOF_POINTER__
 268   typedef long _sleb128_t;
 269   typedef unsigned long _uleb128_t;
 270 #elif __SIZEOF_LONG_LONG__ >= __SIZEOF_POINTER__
 271   typedef long long _sleb128_t;
 272   typedef unsigned long long _uleb128_t;
 273 #else
 274 # error "What type shall we use for _sleb128_t?"
 275 #endif
 276
 277 #if defined (__SEH__) && !defined (__USING_SJLJ_EXCEPTIONS__)
 278 /* Handles the mapping from SEH to GCC interfaces.  */
 279 EXCEPTION_DISPOSITION _GCC_specific_handler (PEXCEPTION_RECORD, void *,
 280                                              PCONTEXT, PDISPATCHER_CONTEXT,
 281                                              _Unwind_Personality_Fn);
 282 #endif
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #ifndef HIDE_EXPORTS
 289 #pragma GCC visibility pop
 290 #endif
 291
 292 /* Additional actions to unwind number of stack frames.  */
 293 #define _Unwind_Frames_Extra(frames)
 294
 295 /* Increment frame count.  */
 296 #define _Unwind_Frames_Increment(exc, context, frames) frames++
 297
 298 #endif /* unwind.h */