blob: 98309abcc29a4b6099bfee613f0154d6b58973f6 [file] [log] [blame]
hp.com!davidm76166fb2002-04-05 23:37:55 +00001/* libunwind - a platform-independent unwind library
2 Copyright (C) 2001-2002 Hewlett-Packard Co
3 Contributed by David Mosberger-Tang <davidm@hpl.hp.com>
4
5This file is part of libunwind.
6
mostang.com!davidmaca38432002-11-16 03:25:36 +00007Permission is hereby granted, free of charge, to any person obtaining
8a copy of this software and associated documentation files (the
9"Software"), to deal in the Software without restriction, including
10without limitation the rights to use, copy, modify, merge, publish,
11distribute, sublicense, and/or sell copies of the Software, and to
12permit persons to whom the Software is furnished to do so, subject to
13the following conditions:
hp.com!davidm76166fb2002-04-05 23:37:55 +000014
mostang.com!davidmaca38432002-11-16 03:25:36 +000015The above copyright notice and this permission notice shall be
16included in all copies or substantial portions of the Software.
hp.com!davidm76166fb2002-04-05 23:37:55 +000017
mostang.com!davidmaca38432002-11-16 03:25:36 +000018THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
22LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
23OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
24WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
hp.com!davidm76166fb2002-04-05 23:37:55 +000025
26#define UNW_PASTE2(x,y) x##y
27#define UNW_PASTE(x,y) UNW_PASTE2(x,y)
28#define UNW_OBJ(fn) UNW_PASTE(UNW_PREFIX, fn)
29
30#ifdef UNW_LOCAL_ONLY
31# define UNW_PREFIX UNW_PASTE(UNW_PASTE(_UL,UNW_TARGET),_)
32#else /* !UNW_LOCAL_ONLY */
33# define UNW_PREFIX UNW_PASTE(UNW_PASTE(_U,UNW_TARGET),_)
34#endif /* !UNW_LOCAL_ONLY */
35
36typedef unw_tdep_word_t unw_word_t;
37
38/* This needs to be big enough to accommodate the unwind state of any
39 architecture, while leaving some slack for future expansion.
40 Changing this value will require recompiling all users of this
41 library. */
42#define UNW_STATE_LEN 127
43
44/* Error codes. The unwind routines return the *negated* values of
45 these error codes on error and a non-negative value on success. */
46typedef enum
47 {
48 UNW_ESUCCESS = 0, /* no error */
49 UNW_EUNSPEC, /* unspecified (general) error */
50 UNW_ENOMEM, /* out of memory */
51 UNW_EBADREG, /* bad register number */
52 UNW_EREADONLYREG, /* attempt to write read-only register */
53 UNW_ESTOPUNWIND, /* stop unwinding */
54 UNW_EINVALIDIP, /* invalid IP */
55 UNW_EBADFRAME, /* bad frame */
56 UNW_EINVAL, /* unsupported operation */
57 UNW_EBADVERSION, /* unwind info has unsupported version */
58 UNW_ENOINFO /* no unwind info found */
59 }
60unw_error_t;
61
62/* The following enum defines the indices for a couple of
63 (pseudo-)registers which have the same meaning across all
64 platforms. (RO) means read-only. (RW) means read-write. General
65 registers (aka "integer registers") are expected to start with
66 index 0. The number of such registers is architecture-dependent.
67 The remaining indices can be used as an architecture sees fit. The
68 last valid register index is given by UNW_REG_LAST. */
69typedef enum
70 {
71 UNW_REG_IP = UNW_TDEP_IP, /* (rw) instruction pointer (pc) */
72 UNW_REG_SP = UNW_TDEP_SP, /* (ro) stack pointer */
73 UNW_REG_PROC_START = UNW_TDEP_PROC_START, /* (ro) proc startaddr */
74 UNW_REG_HANDLER = UNW_TDEP_HANDLER, /* (ro) addr. of personality routine */
75 UNW_REG_LSDA = UNW_TDEP_LSDA, /* (ro) addr. of lang.-specific data */
76 UNW_REG_LAST = UNW_TDEP_LAST_REG
77 }
78unw_frame_regnum_t;
79
mostang.com!davidm16f21892002-11-09 07:59:02 +000080typedef enum
81 {
82 UNW_CACHE_NONE, /* no caching */
83 UNW_CACHE_GLOBAL, /* shared global cache */
84 UNW_CACHE_PER_THREAD /* per-thread caching */
85 }
86unw_caching_policy_t;
87
hp.com!davidm76166fb2002-04-05 23:37:55 +000088typedef int unw_regnum_t;
89
90/* The unwind cursor starts at the youngest (most deeply nested) frame
91 and is used to track the frame state as the unwinder steps from
92 frame to frame. It is safe to make (shallow) copies of variables
93 of this type. */
94typedef struct unw_cursor
95 {
96 unw_word_t opaque[UNW_STATE_LEN];
97 }
98unw_cursor_t;
99
100/* This type encapsulates the entire (preserved) machine-state. */
101typedef unw_tdep_context_t unw_context_t;
102
103/* unw_getcontext() fills the unw_context_t pointed to by UC with the
104 machine state as it exists at the call-site. For implementation
105 reasons, this needs to be a target-dependent macro. It's easiest
106 to think of unw_getcontext() as being identical to getcontext(). */
107#define unw_getcontext(uc) unw_tdep_getcontext(uc)
108
109/* We will assume that "long double" is sufficiently large and aligned
110 to hold the contents of a floating-point register. Note that the
111 fp register format is not usually the same format as a "long
112 double". Instead, the content of unw_fpreg_t should be manipulated
113 only through the "raw.bits" member. */
114typedef union
115 {
116 struct { unw_word_t bits[1]; } raw;
117 long double dummy; /* dummy to force 16-byte alignment */
118 }
119unw_fpreg_t;
120
121/* These are backend callback routines that provide access to the
122 state of a "remote" process. This can be used, for example, to
123 unwind another process through the ptrace() interface. */
124typedef struct unw_accessors
125 {
126 /* Lock for unwind info for address IP. The architecture specific
127 UNWIND_INFO is updated as necessary. */
128 int (*acquire_unwind_info) (unw_word_t ip, void *unwind_info, void *arg);
129 int (*release_unwind_info) (void *unwind_info, void *arg);
130
131 /* Access aligned word at address ADDR. */
132 int (*access_mem) (unw_word_t addr, unw_word_t *val, int write, void *arg);
133
134 /* Access register number REG at address ADDR. */
135 int (*access_reg) (unw_regnum_t reg, unw_word_t *val, int write,
136 void *arg);
137
138 /* Access register number REG at address ADDR. */
139 int (*access_fpreg) (unw_regnum_t reg, unw_fpreg_t *val, int write,
140 void *arg);
141
142 int (*resume) (unw_cursor_t *c, void *arg);
143
144 void *arg; /* application-specific data */
145 }
146unw_accessors_t;
147
148typedef enum unw_save_loc_type
149 {
150 UNW_SLT_NONE, /* register is not saved ("not an l-value") */
151 UNW_SLT_MEMORY, /* register has been saved in memory */
152 UNW_SLT_REG /* register has been saved in (another) register */
153 }
154unw_save_loc_type_t;
155
156typedef struct unw_save_loc
157 {
158 unw_save_loc_type_t type;
159 union
160 {
161 unw_word_t addr; /* valid if type==UNW_SLT_MEMORY */
162 unw_regnum_t regnum; /* valid if type==UNW_SLT_REG */
163 }
164 u;
165 unw_tdep_save_loc_t extra; /* target-dependent additional information */
166 }
167unw_save_loc_t;
168
169/* These routines work both for local and remote unwinding. */
170
171extern int UNW_OBJ(init_local) (unw_cursor_t *c, ucontext_t *u);
172extern int UNW_OBJ(init_remote) (unw_cursor_t *c, unw_accessors_t *a);
173extern int UNW_OBJ(step) (unw_cursor_t *c);
174extern int UNW_OBJ(resume) (unw_cursor_t *c);
175extern int UNW_OBJ(get_reg) (unw_cursor_t *c, int regnum, unw_word_t *valp);
176extern int UNW_OBJ(set_reg) (unw_cursor_t *c, int regnum, unw_word_t val);
177extern int UNW_OBJ(get_fpreg) (unw_cursor_t *c, int regnum, unw_fpreg_t *val);
178extern int UNW_OBJ(set_fpreg) (unw_cursor_t *c, int regnum, unw_fpreg_t val);
179extern int UNW_OBJ(get_save_loc) (unw_cursor_t *c, int regnum,
180 unw_save_loc_t *loc);
181extern int UNW_OBJ(is_signal_frame) (unw_cursor_t *c);
mostang.com!davidm58142c02002-04-12 05:02:40 +0000182extern const char *UNW_OBJ(regname) (int regnum);
hp.com!davidm76166fb2002-04-05 23:37:55 +0000183
184/* Initialize cursor C such that unwinding starts at the point
185 represented by the context U. Returns zero on success, negative
186 value on failure. */
187#define unw_init_local(c,u) UNW_OBJ(init_local)(c, u)
188
189/* Initialize cursor C such that it accesses the unwind target through
190 accessors A. */
191#define unw_init_remote(c,a) UNW_OBJ(init_remote)(c, a)
192
193/* Move cursor up by one step (up meaning toward earlier, less deeply
194 nested frames). Returns positive number if there are more frames
195 to unwind, 0 if last frame has been reached, negative number in
196 case of an error. */
197#define unw_step(c) UNW_OBJ(step)(c)
198
199/* Resume execution at the point identified by the cursor. */
200#define unw_resume(c) UNW_OBJ(resume)(c)
201
202/* Register accessor routines. Return zero on success, negative value
203 on failure. */
204#define unw_get_reg(c,r,v) UNW_OBJ(get_reg)(c,r,v)
205#define unw_set_reg(c,r,v) UNW_OBJ(set_reg)(c,r,v)
206
207/* Floating-point accessor routines. Return zero on success, negative
208 value on failure. */
209#define unw_get_fpreg(c,r,v) UNW_OBJ(get_fpreg)(c,r,v)
210#define unw_set_fpreg(c,r,v) UNW_OBJ(set_fpreg)(c,r,v)
211
212#define unw_get_save_loc(c,r,l) UNW_OBJ(get_save_loc)(c,r,l)
213
214/* Return 1 if register number R is a floating-point register, zero
215 otherwise. */
216#define unw_is_fpreg(r) unw_tdep_is_fpreg(r)
217
218/* Returns non-zero value if the cursor points to a signal frame. */
219#define unw_is_signal_frame(c) UNW_OBJ(is_signal_frame)(c)
mostang.com!davidm58142c02002-04-12 05:02:40 +0000220
221/* Returns the canonical register name of register R. R must be in
222 the range from 0 to UNW_REG_LAST. Like all other unwind routines,
223 this one is re-entrant (i.e., the returned string must be a string
224 constant. */
225#define unw_regname(r) UNW_OBJ(regname)(r)
mostang.com!davidm16f21892002-11-09 07:59:02 +0000226
227/* Sets the caching policy. Caching can be disabled completely by
228 setting the policy to UNW_CACHE_NONE. With UNW_CACHE_GLOBAL, there
229 is a single cache that is shared across all threads. With
230 UNW_CACHE_PER_THREAD, each thread gets its own cache, which can
231 improve performance thanks to less locking and better locality. By
232 default, UNW_CACHE_GLOBAL is in effect. */
233#define unw_set_caching_policy(p) UNW_OBJ(set_caching_policy)(p)
234
235/* Flush all caches (global, per-thread, or any other caches that
236 might exist). This function must be called if any of unwind
237 information might have changed (e.g., because a library might have
238 been removed via a call to dlclose()). */
239#define unw_flush_cache() UNW_OBJ(flush_cache)()