1/* Exception handling and frame unwind runtime interface routines.
2 Copyright (C) 2001-2020 Free Software Foundation, Inc.
3
4 This file is part of the GNU C Library.
5
6 The GNU C Library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
10
11 The GNU C Library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public
17 License along with the GNU C Library; if not, see
18 <https://www.gnu.org/licenses/>. */
19
20/* This is derived from the C++ ABI for IA-64. Where we diverge
21 for cross-architecture compatibility are noted with "@@@". */
22
23#ifndef _UNWIND_H
24#define _UNWIND_H 1
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30/* Level 1: Base ABI */
31
32/* @@@ The IA-64 ABI uses uint64 throughout. Most places this is
33 inefficient for 32-bit and smaller machines. */
34typedef unsigned _Unwind_Word __attribute__((__mode__(__unwind_word__)));
35typedef signed _Unwind_Sword __attribute__((__mode__(__unwind_word__)));
36#if defined(__ia64__) && defined(__hpux__)
37typedef unsigned _Unwind_Ptr __attribute__((__mode__(__word__)));
38#else
39typedef unsigned _Unwind_Ptr __attribute__((__mode__(__pointer__)));
40#endif
41typedef unsigned _Unwind_Internal_Ptr __attribute__((__mode__(__pointer__)));
42
43/* @@@ The IA-64 ABI uses a 64-bit word to identify the producer and
44 consumer of an exception. We'll go along with this for now even on
45 32-bit machines. We'll need to provide some other option for
46 16-bit machines and for machines with > 8 bits per byte. */
47typedef unsigned _Unwind_Exception_Class __attribute__((__mode__(__DI__)));
48
49/* The unwind interface uses reason codes in several contexts to
50 identify the reasons for failures or other actions. */
51typedef enum
52{
53 _URC_NO_REASON = 0,
54 _URC_FOREIGN_EXCEPTION_CAUGHT = 1,
55 _URC_FATAL_PHASE2_ERROR = 2,
56 _URC_FATAL_PHASE1_ERROR = 3,
57 _URC_NORMAL_STOP = 4,
58 _URC_END_OF_STACK = 5,
59 _URC_HANDLER_FOUND = 6,
60 _URC_INSTALL_CONTEXT = 7,
61 _URC_CONTINUE_UNWIND = 8
62} _Unwind_Reason_Code;
63
64
65/* The unwind interface uses a pointer to an exception header object
66 as its representation of an exception being thrown. In general, the
67 full representation of an exception object is language- and
68 implementation-specific, but it will be prefixed by a header
69 understood by the unwind interface. */
70
71struct _Unwind_Exception;
72
73typedef void (*_Unwind_Exception_Cleanup_Fn) (_Unwind_Reason_Code,
74 struct _Unwind_Exception *);
75
76struct _Unwind_Exception
77{
78 _Unwind_Exception_Class exception_class;
79 _Unwind_Exception_Cleanup_Fn exception_cleanup;
80 _Unwind_Word private_1;
81 _Unwind_Word private_2;
82
83 /* @@@ The IA-64 ABI says that this structure must be double-word aligned.
84 Taking that literally does not make much sense generically. Instead we
85 provide the maximum alignment required by any type for the machine. */
86} __attribute__((__aligned__));
87
88
89/* The ACTIONS argument to the personality routine is a bitwise OR of one
90 or more of the following constants. */
91typedef int _Unwind_Action;
92
93#define _UA_SEARCH_PHASE 1
94#define _UA_CLEANUP_PHASE 2
95#define _UA_HANDLER_FRAME 4
96#define _UA_FORCE_UNWIND 8
97#define _UA_END_OF_STACK 16
98
99/* This is an opaque type used to refer to a system-specific data
100 structure used by the system unwinder. This context is created and
101 destroyed by the system, and passed to the personality routine
102 during unwinding. */
103struct _Unwind_Context;
104
105/* Raise an exception, passing along the given exception object. */
106extern _Unwind_Reason_Code _Unwind_RaiseException (struct _Unwind_Exception *);
107
108/* Raise an exception for forced unwinding. */
109
110typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)
111 (int, _Unwind_Action, _Unwind_Exception_Class,
112 struct _Unwind_Exception *, struct _Unwind_Context *, void *);
113
114extern _Unwind_Reason_Code _Unwind_ForcedUnwind (struct _Unwind_Exception *,
115 _Unwind_Stop_Fn,
116 void *);
117
118/* Helper to invoke the exception_cleanup routine. */
119extern void _Unwind_DeleteException (struct _Unwind_Exception *);
120
121/* Resume propagation of an existing exception. This is used after
122 e.g. executing cleanup code, and not to implement rethrowing. */
123extern void _Unwind_Resume (struct _Unwind_Exception *);
124
125/* @@@ Use unwind data to perform a stack backtrace. The trace callback
126 is called for every stack frame in the call chain, but no cleanup
127 actions are performed. */
128typedef _Unwind_Reason_Code (*_Unwind_Trace_Fn)
129 (struct _Unwind_Context *, void *);
130
131extern _Unwind_Reason_Code _Unwind_Backtrace (_Unwind_Trace_Fn, void *);
132
133/* These functions are used for communicating information about the unwind
134 context (i.e. the unwind descriptors and the user register state) between
135 the unwind library and the personality routine and landing pad. Only
136 selected registers maybe manipulated. */
137
138extern _Unwind_Word _Unwind_GetGR (struct _Unwind_Context *, int);
139extern void _Unwind_SetGR (struct _Unwind_Context *, int, _Unwind_Word);
140
141extern _Unwind_Ptr _Unwind_GetIP (struct _Unwind_Context *);
142extern void _Unwind_SetIP (struct _Unwind_Context *, _Unwind_Ptr);
143
144/* @@@ Retrieve the CFA of the given context. */
145extern _Unwind_Word _Unwind_GetCFA (struct _Unwind_Context *);
146
147extern void *_Unwind_GetLanguageSpecificData (struct _Unwind_Context *);
148
149extern _Unwind_Ptr _Unwind_GetRegionStart (struct _Unwind_Context *);
150
151
152/* The personality routine is the function in the C++ (or other language)
153 runtime library which serves as an interface between the system unwind
154 library and language-specific exception handling semantics. It is
155 specific to the code fragment described by an unwind info block, and
156 it is always referenced via the pointer in the unwind info block, and
157 hence it has no ABI-specified name.
158
159 Note that this implies that two different C++ implementations can
160 use different names, and have different contents in the language
161 specific data area. Moreover, that the language specific data
162 area contains no version info because name of the function invoked
163 provides more effective versioning by detecting at link time the
164 lack of code to handle the different data format. */
165
166typedef _Unwind_Reason_Code (*_Unwind_Personality_Fn)
167 (int, _Unwind_Action, _Unwind_Exception_Class,
168 struct _Unwind_Exception *, struct _Unwind_Context *);
169
170/* @@@ The following alternate entry points are for setjmp/longjmp
171 based unwinding. */
172
173struct SjLj_Function_Context;
174extern void _Unwind_SjLj_Register (struct SjLj_Function_Context *);
175extern void _Unwind_SjLj_Unregister (struct SjLj_Function_Context *);
176
177extern _Unwind_Reason_Code _Unwind_SjLj_RaiseException
178 (struct _Unwind_Exception *);
179extern _Unwind_Reason_Code _Unwind_SjLj_ForcedUnwind
180 (struct _Unwind_Exception *, _Unwind_Stop_Fn, void *);
181extern void _Unwind_SjLj_Resume (struct _Unwind_Exception *);
182
183/* @@@ The following provide access to the base addresses for text
184 and data-relative addressing in the LDSA. In order to stay link
185 compatible with the standard ABI for IA-64, we inline these. */
186
187#ifdef __ia64__
188#include <stdlib.h>
189
190static inline _Unwind_Ptr
191_Unwind_GetDataRelBase (struct _Unwind_Context *_C)
192{
193 /* The GP is stored in R1. */
194 return _Unwind_GetGR (_C, 1);
195}
196
197static inline _Unwind_Ptr
198_Unwind_GetTextRelBase (struct _Unwind_Context *_C)
199{
200 abort ();
201 return 0;
202}
203
204/* @@@ Retrieve the Backing Store Pointer of the given context. */
205extern _Unwind_Word _Unwind_GetBSP (struct _Unwind_Context *);
206#else
207extern _Unwind_Ptr _Unwind_GetDataRelBase (struct _Unwind_Context *);
208extern _Unwind_Ptr _Unwind_GetTextRelBase (struct _Unwind_Context *);
209#endif
210
211/* @@@ Given an address, return the entry point of the function that
212 contains it. */
213extern void * _Unwind_FindEnclosingFunction (void *pc);
214
215#ifdef __cplusplus
216}
217#endif
218
219#endif /* unwind.h */
220