libunwind-common.h revision 3569969a3ee6383bd1608f9483b888bb3e2c45a8 
1/* 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
7libunwind is free software; you can redistribute it and/or modify
8it under the terms of the GNU General Public License as published by
9the Free Software Foundation; either version 2, or (at your option)
10any later version.
11
12libunwind is distributed in the hope that it will be useful,
13but WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15GNU General Public License for more details.
16
17You should have received a copy of the GNU General Public License
18along with GNU CC; see the file COPYING.  If not, write to
19the Free Software Foundation, 59 Temple Place - Suite 330,
20Boston, MA 02111-1307, USA.
21
22As a special exception, if you link this library with other files to
23produce an executable, this library does not by itself cause the
24resulting executable to be covered by the GNU General Public License.
25This exception does not however invalidate any other reasons why the
26executable file might be covered by the GNU General Public
27License.  */
28
29#define UNW_PASTE2(x,y)	x##y
30#define UNW_PASTE(x,y)	UNW_PASTE2(x,y)
31#define UNW_OBJ(fn)	UNW_PASTE(UNW_PREFIX, fn)
32
33#ifdef UNW_LOCAL_ONLY
34# define UNW_PREFIX	UNW_PASTE(UNW_PASTE(_UL,UNW_TARGET),_)
35#else /* !UNW_LOCAL_ONLY */
36# define UNW_PREFIX	UNW_PASTE(UNW_PASTE(_U,UNW_TARGET),_)
37#endif /* !UNW_LOCAL_ONLY */
38
39typedef unw_tdep_word_t unw_word_t;
40
41/* This needs to be big enough to accommodate the unwind state of any
42   architecture, while leaving some slack for future expansion.
43   Changing this value will require recompiling all users of this
44   library.  */
45#define UNW_STATE_LEN	127
46
47/* Error codes.  The unwind routines return the *negated* values of
48   these error codes on error and a non-negative value on success.  */
49typedef enum
50  {
51    UNW_ESUCCESS = 0,		/* no error */
52    UNW_EUNSPEC,		/* unspecified (general) error */
53    UNW_ENOMEM,			/* out of memory */
54    UNW_EBADREG,		/* bad register number */
55    UNW_EREADONLYREG,		/* attempt to write read-only register */
56    UNW_ESTOPUNWIND,		/* stop unwinding */
57    UNW_EINVALIDIP,		/* invalid IP */
58    UNW_EBADFRAME,		/* bad frame */
59    UNW_EINVAL,			/* unsupported operation */
60    UNW_EBADVERSION,		/* unwind info has unsupported version */
61    UNW_ENOINFO			/* no unwind info found */
62  }
63unw_error_t;
64
65/* The following enum defines the indices for a couple of
66   (pseudo-)registers which have the same meaning across all
67   platforms.  (RO) means read-only.  (RW) means read-write.  General
68   registers (aka "integer registers") are expected to start with
69   index 0.  The number of such registers is architecture-dependent.
70   The remaining indices can be used as an architecture sees fit.  The
71   last valid register index is given by UNW_REG_LAST.  */
72typedef enum
73  {
74    UNW_REG_IP = UNW_TDEP_IP,		/* (rw) instruction pointer (pc) */
75    UNW_REG_SP = UNW_TDEP_SP,		/* (ro) stack pointer */
76    UNW_REG_PROC_START = UNW_TDEP_PROC_START,	/* (ro) proc startaddr */
77    UNW_REG_HANDLER = UNW_TDEP_HANDLER,	/* (ro) addr. of personality routine */
78    UNW_REG_LSDA = UNW_TDEP_LSDA,	/* (ro) addr. of lang.-specific data */
79    UNW_REG_LAST = UNW_TDEP_LAST_REG
80  }
81unw_frame_regnum_t;
82
83typedef int unw_regnum_t;
84
85/* The unwind cursor starts at the youngest (most deeply nested) frame
86   and is used to track the frame state as the unwinder steps from
87   frame to frame.  It is safe to make (shallow) copies of variables
88   of this type.  */
89typedef struct unw_cursor
90  {
91    unw_word_t opaque[UNW_STATE_LEN];
92  }
93unw_cursor_t;
94
95/* This type encapsulates the entire (preserved) machine-state.  */
96typedef unw_tdep_context_t unw_context_t;
97
98/* unw_getcontext() fills the unw_context_t pointed to by UC with the
99   machine state as it exists at the call-site.  For implementation
100   reasons, this needs to be a target-dependent macro.  It's easiest
101   to think of unw_getcontext() as being identical to getcontext(). */
102#define unw_getcontext(uc)	unw_tdep_getcontext(uc)
103
104/* We will assume that "long double" is sufficiently large and aligned
105   to hold the contents of a floating-point register.  Note that the
106   fp register format is not usually the same format as a "long
107   double".  Instead, the content of unw_fpreg_t should be manipulated
108   only through the "raw.bits" member. */
109typedef union
110  {
111    struct { unw_word_t bits[1]; } raw;
112    long double dummy;	/* dummy to force 16-byte alignment */
113  }
114unw_fpreg_t;
115
116/* These are backend callback routines that provide access to the
117   state of a "remote" process.  This can be used, for example, to
118   unwind another process through the ptrace() interface.  */
119typedef struct unw_accessors
120  {
121    /* Lock for unwind info for address IP.  The architecture specific
122       UNWIND_INFO is updated as necessary.  */
123    int (*acquire_unwind_info) (unw_word_t ip, void *unwind_info, void *arg);
124    int (*release_unwind_info) (void *unwind_info, void *arg);
125
126    /* Access aligned word at address ADDR.  */
127    int (*access_mem) (unw_word_t addr, unw_word_t *val, int write, void *arg);
128
129    /* Access register number REG at address ADDR.  */
130    int (*access_reg) (unw_regnum_t reg, unw_word_t *val, int write,
131		       void *arg);
132
133    /* Access register number REG at address ADDR.  */
134    int (*access_fpreg) (unw_regnum_t reg, unw_fpreg_t *val, int write,
135			 void *arg);
136
137    int (*resume) (unw_cursor_t *c, void *arg);
138
139    void *arg;		/* application-specific data */
140  }
141unw_accessors_t;
142
143typedef enum unw_save_loc_type
144  {
145    UNW_SLT_NONE,	/* register is not saved ("not an l-value") */
146    UNW_SLT_MEMORY,	/* register has been saved in memory */
147    UNW_SLT_REG		/* register has been saved in (another) register */
148  }
149unw_save_loc_type_t;
150
151typedef struct unw_save_loc
152  {
153    unw_save_loc_type_t type;
154    union
155      {
156	unw_word_t addr;	/* valid if type==UNW_SLT_MEMORY */
157	unw_regnum_t regnum;	/* valid if type==UNW_SLT_REG */
158      }
159    u;
160    unw_tdep_save_loc_t extra;	/* target-dependent additional information */
161  }
162unw_save_loc_t;
163
164/* These routines work both for local and remote unwinding.  */
165
166extern int UNW_OBJ(init_local) (unw_cursor_t *c, ucontext_t *u);
167extern int UNW_OBJ(init_remote) (unw_cursor_t *c, unw_accessors_t *a);
168extern int UNW_OBJ(step) (unw_cursor_t *c);
169extern int UNW_OBJ(resume) (unw_cursor_t *c);
170extern int UNW_OBJ(get_reg) (unw_cursor_t *c, int regnum, unw_word_t *valp);
171extern int UNW_OBJ(set_reg) (unw_cursor_t *c, int regnum, unw_word_t val);
172extern int UNW_OBJ(get_fpreg) (unw_cursor_t *c, int regnum, unw_fpreg_t *val);
173extern int UNW_OBJ(set_fpreg) (unw_cursor_t *c, int regnum, unw_fpreg_t val);
174extern int UNW_OBJ(get_save_loc) (unw_cursor_t *c, int regnum,
175				  unw_save_loc_t *loc);
176extern int UNW_OBJ(is_signal_frame) (unw_cursor_t *c);
177extern const char *UNW_OBJ(regname) (int regnum);
178
179/* Initialize cursor C such that unwinding starts at the point
180   represented by the context U.  Returns zero on success, negative
181   value on failure.  */
182#define unw_init_local(c,u)	UNW_OBJ(init_local)(c, u)
183
184/* Initialize cursor C such that it accesses the unwind target through
185   accessors A.  */
186#define unw_init_remote(c,a)	UNW_OBJ(init_remote)(c, a)
187
188/* Move cursor up by one step (up meaning toward earlier, less deeply
189   nested frames).  Returns positive number if there are more frames
190   to unwind, 0 if last frame has been reached, negative number in
191   case of an error.  */
192#define unw_step(c)		UNW_OBJ(step)(c)
193
194/* Resume execution at the point identified by the cursor.  */
195#define unw_resume(c)		UNW_OBJ(resume)(c)
196
197/* Register accessor routines.  Return zero on success, negative value
198   on failure.  */
199#define unw_get_reg(c,r,v)	UNW_OBJ(get_reg)(c,r,v)
200#define unw_set_reg(c,r,v)	UNW_OBJ(set_reg)(c,r,v)
201
202/* Floating-point accessor routines.  Return zero on success, negative
203   value on failure.  */
204#define unw_get_fpreg(c,r,v)	UNW_OBJ(get_fpreg)(c,r,v)
205#define unw_set_fpreg(c,r,v)	UNW_OBJ(set_fpreg)(c,r,v)
206
207#define unw_get_save_loc(c,r,l)	UNW_OBJ(get_save_loc)(c,r,l)
208
209/* Return 1 if register number R is a floating-point register, zero
210   otherwise.  */
211#define unw_is_fpreg(r)		unw_tdep_is_fpreg(r)
212
213/* Returns non-zero value if the cursor points to a signal frame.  */
214#define unw_is_signal_frame(c)	UNW_OBJ(is_signal_frame)(c)
215
216/* Returns the canonical register name of register R.  R must be in
217   the range from 0 to UNW_REG_LAST.  Like all other unwind routines,
218   this one is re-entrant (i.e., the returned string must be a string
219   constant.  */
220#define unw_regname(r)		UNW_OBJ(regname)(r)
221