xref: /illumos-gate/usr/src/head/stack_unwind.h (revision 6e270ca8)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 /*
28  * Public interfaces for AMD64 Unwind routines
29  */
30 
31 #ifndef _STACK_UNWIND_H
32 #define	_STACK_UNWIND_H
33 
34 #include <sys/types.h>
35 
36 #ifdef	__cplusplus
37 extern "C" {
38 #endif
39 
40 #if defined(__amd64)	/* none of this is valid except for AMD64 */
41 
42 typedef enum {
43 	_URC_NO_REASON = 0,
44 	_URC_FOREIGN_EXCEPTION_CAUGHT = 1,
45 	_URC_FATAL_PHASE2_ERROR = 2,
46 	_URC_FATAL_PHASE1_ERROR = 3,
47 	_URC_NORMAL_STOP = 4,
48 	_URC_END_OF_STACK = 5,
49 	_URC_HANDLER_FOUND = 6,
50 	_URC_INSTALL_CONTEXT = 7,
51 	_URC_CONTINUE_UNWIND = 8
52 } _Unwind_Reason_Code;
53 
54 typedef int _Unwind_Action;
55 extern const _Unwind_Action _UA_SEARCH_PHASE;
56 extern const _Unwind_Action _UA_CLEANUP_PHASE;
57 extern const _Unwind_Action _UA_HANDLER_FRAME;
58 extern const _Unwind_Action _UA_FORCE_UNWIND;
59 
60 struct _Unwind_Exception;
61 struct _Unwind_Context;
62 
63 
64 /*
65  * Signature of language specific call back for deleting exception object
66  */
67 typedef void (*_Unwind_Exception_Cleanup_Fn)(
68 	_Unwind_Reason_Code reason,
69 	struct _Unwind_Exception *exc);
70 
71 /*
72  * Header preceding language specific exception object
73  * For Sun C++ these fields are the beginning of the
74  * language specific structure.
75  */
76 struct _Unwind_Exception {
77 	uint64_t exception_class;
78 	_Unwind_Exception_Cleanup_Fn exception_cleanup;
79 	uint64_t private_1;
80 	uint64_t private_2;
81 };
82 
83 /*
84  * Signature for language specific routine - address is in eh_frame CIE.
85  * During phase one it predicts whether exception would be caught at this
86  * frame and during phase two selects a handler as predicted.  An action
87  * of _UA_FORCE_UNWIND will prevent any catch block from being selected.
88  *
89  * The personality function is the only call back used when
90  * _Unwind_RaiseException() is called.
91  */
92 typedef _Unwind_Reason_Code (*_Unwind_Personality_Fn)(
93 	int version,
94 	_Unwind_Action actions,
95 	uint64_t exceptionClass,
96 	struct _Unwind_Exception *exceptionObject,
97 	struct _Unwind_Context *context);
98 
99 /*
100  * Signature of callback function that is used when _Unwind_ForcedUnwind()
101  * is called.  It is called at every step of walkback and that can control
102  * the execution of the personality routine at each frame.
103  */
104 typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)(
105 	int version,
106 	_Unwind_Action actions,
107 	uint64_t exceptionClass,
108 	struct _Unwind_Exception *exceptionObject,
109 	struct _Unwind_Context *context,
110 	void *stop_parameter);
111 
112 /*
113  * Here begins the external functional interface
114  */
115 
116 /*
117  * Used to implement C++ throw - starts walkback with caller's caller.
118  * The routine in the middle must use %rbp as a frame pointer
119  */
120 _Unwind_Reason_Code _Unwind_RaiseException(
121 	struct _Unwind_Exception *exception_object);
122 
123 /*
124  * Used (with different stop functions) for POSIX thread cancellation
125  * and stack walking - starts walkback with caller's caller.
126  *
127  * Note: must be called by a routine which has a real FP and doesn't use
128  * callee saves registers.
129  */
130 _Unwind_Reason_Code _Unwind_ForcedUnwind(
131 	struct _Unwind_Exception *exception_object,
132 	_Unwind_Stop_Fn stop,
133 	void *stop_parameter);
134 
135 /*
136  * Used to resume unwinding at end of cleanup (not catch) code
137  * Assumes that caller is language specific cleanup code and
138  * pops the stack one level before resuming walk.
139  */
140 void _Unwind_Resume(struct _Unwind_Exception *exception_object);
141 
142 /*
143  * Calls destructor function for exception object
144  */
145 void _Unwind_DeleteException(struct _Unwind_Exception *exception_object);
146 /*
147  * {
148  *	(*(exception_object->exception_cleanup))(_URC_NO_REASON,
149  *		exception_object);
150  * }
151  */
152 
153 
154 #if 0
155 
156 extern "C" _Unwind_Reason_Code
157 __example_stop_fn(int version, int actions, uint64_t exclass,
158     struct _Unwind_Exception *exception_object,
159     struct _Unwind_Context *ctx, void *_Sa)
160 {
161 	_Unwind_Reason_Code res;
162 
163 	uint64_t fp = _Unwind_GetCFA(ctx);
164 
165 	if (fp == 0 || _Unwind_GetGR(ctx, RET_ADD) == 0) {
166 		if (no_return)
167 			die;
168 		res = _URC_END_OF_STACK;
169 	} else {
170 		/*
171 		 * Your logic here:
172 		 * res = ........
173 		 */
174 	}
175 	switch (res) {
176 	case _URC_NO_REASON:
177 		/*
178 		 * framework will call personality routine for current context
179 		 * then then move one frame back the stack and call here with
180 		 * updated context. POSIX thread cancellation uses this pattern.
181 		 *
182 		 * If this path is taken the exception object passed must have
183 		 * been constructed by the same language system supplying the
184 		 * personality routines. i.e. foreign exceptions are not
185 		 * implemented.
186 		 *
187 		 * The Sun Microsystems C++ runtime contains the routine
188 		 *
189 		 *	_ex_unwind(_Unwind_Stop_fn sfunc, void *sfunc_arg)
190 		 *
191 		 * which is a wrapper around _Unwind_ForcedUnwind that
192 		 * sets up a C++ exception object.
193 		 *
194 		 * Once this path is taken, the stack frame from which
195 		 * _Unwind_ForcedUnwind was called is not guaranteed to
196 		 * still exist. Thus the return codes listed below which
197 		 * result in that call returning are rendered bogus.
198 		 *
199 		 * A thread reaching the end of the stack during cancellation
200 		 * must die instead of returning _URC_END_OF_STACK.
201 		 */
202 		break;
203 	case _URC_CONTINUE_UNWIND:
204 		/*
205 		 * framework will move one frame back the stack and
206 		 * call here with updated context
207 		 *
208 		 * The exception record supplied to _Unwind_ForcedUnwind
209 		 * need only contain the header and may be stack allocated
210 		 * if this function will never allow the personality
211 		 * function to run (as in a trace generator).
212 		 */
213 		break;
214 	case _URC_INSTALL_CONTEXT:
215 		/*
216 		 * framework will resume execution of user code at location
217 		 * specified by (altered) context
218 		 */
219 		_Unwind_Delete_Exception(res, exception_object);
220 		break;
221 	case _URC_NORMAL_STOP:
222 		/*
223 		 * call to _Unwind_ForcedUnwind will return _URC_NORMAL_STOP
224 		 */
225 		_Unwind_Delete_Exception(res, exception_object);
226 		break;
227 	case _URC_END_OF_STACK:
228 		/*
229 		 * call to _Unwind_ForcedUnwind will return _URC_END_OF_STACK
230 		 */
231 		_Unwind_Delete_Exception(res, exception_object);
232 		break;
233 	case _URC_FOREIGN_EXCEPTION_CAUGHT:
234 	case _URC_FATAL_PHASE2_ERROR:
235 	case _URC_FATAL_PHASE1_ERROR:
236 	case _URC_HANDLER_FOUND:
237 		/*
238 		 * call to _Unwind_ForcedUnwind will return
239 		 * _URC_FATAL_PHASE2_ERROR
240 		 */
241 		_Unwind_Delete_Exception(res, exception_object);
242 		break;
243 	}
244 	return (res);
245 }
246 
247 #endif
248 
249 /*
250  * Stack frame context accessors defined in ABI
251  * (despite all the dire text in the ABI these are reliable Get/Set routines)
252  * Note: RA is handled as a GR value
253  */
254 
255 /*
256  * Valid Index values for _Unwind_GetGR
257  */
258 #define	GPR_RBX	3	/* callee saves */
259 #define	FP_RBP	6	/* callee saves (optional frame pointer) */
260 #define	SP_RSP	7	/* callee saves */
261 #define	EIR_R12	12	/* callee saves */
262 #define	EIR_R13	13	/* callee saves */
263 #define	EIR_R14	14	/* callee saves */
264 #define	EIR_R15	15	/* callee saves */
265 #define	RET_ADD	16	/* virtual register - really caller's PC */
266 
267 /*
268  * Valid Index values for _Unwind_SetGR
269  */
270 #define	GPR_RDX	1	/* landing pad parameter */
271 #define	GPR_RCX	2	/* landing pad parameter */
272 #define	GPR_RSI	4	/* landing pad parameter */
273 #define	GPR_RDI	5	/* landing pad parameter */
274 
275 uint64_t _Unwind_GetGR(struct _Unwind_Context *context, int index);
276 
277 void _Unwind_SetGR(struct _Unwind_Context *context, int index,
278 	uint64_t new_value);
279 
280 uint64_t _Unwind_GetCFA(struct _Unwind_Context *context);
281 
282 uint64_t _Unwind_GetIP(struct _Unwind_Context *context);
283 
284 void _Unwind_SetIP(struct _Unwind_Context *context, uint64_t new_value);
285 
286 void *_Unwind_GetLanguageSpecificData(struct _Unwind_Context *context);
287 
288 uint64_t _Unwind_GetRegionStart(struct _Unwind_Context *context);
289 
290 #endif	/* __amd64 */
291 
292 #ifdef	__cplusplus
293 }
294 #endif
295 
296 #endif	/* _STACK_UNWIND_H */
297