external/android-libunwind/include/libunwind-common.h

   1 /* libunwind - a platform-independent unwind library
   2    Copyright (C) 2001-2004 Hewlett-Packard Co
   3         Contributed by David Mosberger-Tang <davidm@hpl.hp.com>
   4
   5 This file is part of libunwind.
   6
   7 Permission is hereby granted, free of charge, to any person obtaining
   8 a copy of this software and associated documentation files (the
   9 "Software"), to deal in the Software without restriction, including
  10 without limitation the rights to use, copy, modify, merge, publish,
  11 distribute, sublicense, and/or sell copies of the Software, and to
  12 permit persons to whom the Software is furnished to do so, subject to
  13 the following conditions:
  14
  15 The above copyright notice and this permission notice shall be
  16 included in all copies or substantial portions of the Software.
  17
  18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  19 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  20 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  21 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  22 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  23 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  24 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.  */
  25
  26 /* ANDROID support update. */
  27 #include <sys/types.h>
  28 /* End of ANDROID update. */
  29
  30 #define UNW_VERSION_MAJOR       1
  31 #define UNW_VERSION_MINOR       1
  32 #define UNW_VERSION_EXTRA
  33
  34 #define UNW_VERSION_CODE(maj,min)       (((maj) << 16) | (min))
  35 #define UNW_VERSION     UNW_VERSION_CODE(UNW_VERSION_MAJOR, UNW_VERSION_MINOR)
  36
  37 #define UNW_PASTE2(x,y) x##y
  38 #define UNW_PASTE(x,y)  UNW_PASTE2(x,y)
  39 #define UNW_OBJ(fn)     UNW_PASTE(UNW_PREFIX, fn)
  40 #define UNW_ARCH_OBJ(fn) UNW_PASTE(UNW_PASTE(UNW_PASTE(_U,UNW_TARGET),_), fn)
  41
  42 #ifdef UNW_LOCAL_ONLY
  43 # ifdef UNW_ADDITIONAL_PREFIX
  44 #  define UNW_PREFIX    UNW_PASTE(UNW_PASTE(_UUL,UNW_TARGET),_)
  45 # else
  46 #  define UNW_PREFIX    UNW_PASTE(UNW_PASTE(_UL,UNW_TARGET),_)
  47 # endif
  48 #else /* !UNW_LOCAL_ONLY */
  49 # ifdef UNW_ADDITIONAL_PREFIX
  50 #  define UNW_PREFIX    UNW_PASTE(UNW_PASTE(_UU,UNW_TARGET),_)
  51 # else
  52 #  define UNW_PREFIX    UNW_PASTE(UNW_PASTE(_U,UNW_TARGET),_)
  53 # endif
  54 #endif /* !UNW_LOCAL_ONLY */
  55
  56 /* Error codes.  The unwind routines return the *negated* values of
  57    these error codes on error and a non-negative value on success.  */
  58 typedef enum
  59   {
  60     UNW_ESUCCESS = 0,           /* no error */
  61     UNW_EUNSPEC,                /* unspecified (general) error */
  62     UNW_ENOMEM,                 /* out of memory */
  63     UNW_EBADREG,                /* bad register number */
  64     UNW_EREADONLYREG,           /* attempt to write read-only register */
  65     UNW_ESTOPUNWIND,            /* stop unwinding */
  66     UNW_EINVALIDIP,             /* invalid IP */
  67     UNW_EBADFRAME,              /* bad frame */
  68     UNW_EINVAL,                 /* unsupported operation or bad value */
  69     UNW_EBADVERSION,            /* unwind info has unsupported version */
  70     UNW_ENOINFO                 /* no unwind info found */
  71   }
  72 unw_error_t;
  73
  74 /* The following enum defines the indices for a couple of
  75    (pseudo-)registers which have the same meaning across all
  76    platforms.  (RO) means read-only.  (RW) means read-write.  General
  77    registers (aka "integer registers") are expected to start with
  78    index 0.  The number of such registers is architecture-dependent.
  79    The remaining indices can be used as an architecture sees fit.  The
  80    last valid register index is given by UNW_REG_LAST.  */
  81 typedef enum
  82   {
  83     UNW_REG_IP = UNW_TDEP_IP,           /* (rw) instruction pointer (pc) */
  84     UNW_REG_SP = UNW_TDEP_SP,           /* (ro) stack pointer */
  85     UNW_REG_EH = UNW_TDEP_EH,           /* (rw) exception-handling reg base */
  86     UNW_REG_LAST = UNW_TDEP_LAST_REG
  87   }
  88 unw_frame_regnum_t;
  89
  90 /* Number of exception-handler argument registers: */
  91 #define UNW_NUM_EH_REGS         UNW_TDEP_NUM_EH_REGS
  92
  93 typedef enum
  94   {
  95     UNW_CACHE_NONE,                     /* no caching */
  96     UNW_CACHE_GLOBAL,                   /* shared global cache */
  97     UNW_CACHE_PER_THREAD                /* per-thread caching */
  98   }
  99 unw_caching_policy_t;
 100
 101 typedef int unw_regnum_t;
 102
 103 /* The unwind cursor starts at the youngest (most deeply nested) frame
 104    and is used to track the frame state as the unwinder steps from
 105    frame to frame.  It is safe to make (shallow) copies of variables
 106    of this type.  */
 107 typedef struct unw_cursor
 108   {
 109     unw_word_t opaque[UNW_TDEP_CURSOR_LEN];
 110   }
 111 unw_cursor_t;
 112
 113 /* This type encapsulates the entire (preserved) machine-state.  */
 114 typedef unw_tdep_context_t unw_context_t;
 115
 116 /* unw_getcontext() fills the unw_context_t pointed to by UC with the
 117    machine state as it exists at the call-site.  For implementation
 118    reasons, this needs to be a target-dependent macro.  It's easiest
 119    to think of unw_getcontext() as being identical to getcontext(). */
 120 #define unw_getcontext(uc)              unw_tdep_getcontext(uc)
 121
 122 /* Return 1 if register number R is a floating-point register, zero
 123    otherwise.
 124    This routine is signal-safe.  */
 125 #define unw_is_fpreg(r)                 unw_tdep_is_fpreg(r)
 126
 127 typedef unw_tdep_fpreg_t unw_fpreg_t;
 128
 129 typedef struct unw_addr_space *unw_addr_space_t;
 130
 131 /* Each target may define it's own set of flags, but bits 0-15 are
 132    reserved for general libunwind-use.  */
 133 #define UNW_PI_FLAG_FIRST_TDEP_BIT      16
 134 /* The information comes from a .debug_frame section.  */
 135 #define UNW_PI_FLAG_DEBUG_FRAME 32
 136
 137 typedef struct unw_proc_info
 138   {
 139     unw_word_t start_ip;        /* first IP covered by this procedure */
 140     unw_word_t end_ip;          /* first IP NOT covered by this procedure */
 141     unw_word_t lsda;            /* address of lang.-spec. data area (if any) */
 142     unw_word_t handler;         /* optional personality routine */
 143     unw_word_t gp;              /* global-pointer value for this procedure */
 144     unw_word_t flags;           /* misc. flags */
 145
 146     int format;                 /* unwind-info format (arch-specific) */
 147     int unwind_info_size;       /* size of the information (if applicable) */
 148     void *unwind_info;          /* unwind-info (arch-specific) */
 149     unw_tdep_proc_info_t extra; /* target-dependent auxiliary proc-info */
 150   }
 151 unw_proc_info_t;
 152
 153 /* These are backend callback routines that provide access to the
 154    state of a "remote" process.  This can be used, for example, to
 155    unwind another process through the ptrace() interface.  */
 156 typedef struct unw_accessors
 157   {
 158     /* Look up the unwind info associated with instruction-pointer IP.
 159        On success, the routine fills in the PROC_INFO structure.  */
 160     int (*find_proc_info) (unw_addr_space_t, unw_word_t, unw_proc_info_t *,
 161                            int, void *);
 162
 163     /* Release any resources (e.g., memory) that were allocated for
 164        the unwind info returned in by a previous call to
 165        find_proc_info() with NEED_UNWIND_INFO set to 1.  */
 166     void (*put_unwind_info) (unw_addr_space_t, unw_proc_info_t *, void *);
 167
 168     /* Return the list-head of the dynamically registered unwind
 169        info.  */
 170     int (*get_dyn_info_list_addr) (unw_addr_space_t, unw_word_t *, void *);
 171
 172     /* Access aligned word at address ADDR.  The value is returned
 173        according to the endianness of the host (e.g., if the host is
 174        little-endian and the target is big-endian, access_mem() needs
 175        to byte-swap the value before returning it).  */
 176     int (*access_mem) (unw_addr_space_t, unw_word_t, unw_word_t *, int,
 177                        void *);
 178
 179     /* Access register number REG at address ADDR.  */
 180     int (*access_reg) (unw_addr_space_t, unw_regnum_t, unw_word_t *, int,
 181                        void *);
 182
 183     /* Access register number REG at address ADDR.  */
 184     int (*access_fpreg) (unw_addr_space_t, unw_regnum_t,
 185                          unw_fpreg_t *, int, void *);
 186
 187     int (*resume) (unw_addr_space_t, unw_cursor_t *, void *);
 188
 189     /* Optional call back to obtain the name of a (static) procedure.
 190        Dynamically generated procedures are handled automatically by
 191        libunwind.  This callback is optional and may be set to
 192        NULL.  */
 193     int (*get_proc_name) (unw_addr_space_t, unw_word_t, char *, size_t,
 194                           unw_word_t *, void *);
 195   }
 196 unw_accessors_t;
 197
 198 typedef enum unw_save_loc_type
 199   {
 200     UNW_SLT_NONE,       /* register is not saved ("not an l-value") */
 201     UNW_SLT_MEMORY,     /* register has been saved in memory */
 202     UNW_SLT_REG         /* register has been saved in (another) register */
 203   }
 204 unw_save_loc_type_t;
 205
 206 typedef struct unw_save_loc
 207   {
 208     unw_save_loc_type_t type;
 209     union
 210       {
 211         unw_word_t addr;        /* valid if type==UNW_SLT_MEMORY */
 212         unw_regnum_t regnum;    /* valid if type==UNW_SLT_REG */
 213       }
 214     u;
 215     unw_tdep_save_loc_t extra;  /* target-dependent additional information */
 216   }
 217 unw_save_loc_t;
 218
 219 /* ANDROID support update. */
 220 typedef struct unw_map_cursor
 221   {
 222     void *map_list;
 223     void *cur_map;
 224   }
 225 unw_map_cursor_t;
 226
 227 typedef struct unw_map
 228   {
 229     unw_word_t start;
 230     unw_word_t end;
 231     unw_word_t offset;
 232     unw_word_t load_base;
 233     char *path;
 234     int flags;
 235   }
 236 unw_map_t;
 237 /* End of ANDROID update. */
 238
 239 /* These routines work both for local and remote unwinding.  */
 240
 241 #define unw_local_access_addr_space_init UNW_OBJ(local_access_addr_space_init)
 242 #define unw_local_addr_space    UNW_OBJ(local_addr_space)
 243 #define unw_create_addr_space   UNW_OBJ(create_addr_space)
 244 #define unw_destroy_addr_space  UNW_OBJ(destroy_addr_space)
 245 #define unw_get_accessors       UNW_ARCH_OBJ(get_accessors)
 246 #define unw_init_local          UNW_OBJ(init_local)
 247 #define unw_init_remote         UNW_OBJ(init_remote)
 248 #define unw_step                UNW_OBJ(step)
 249 #define unw_resume              UNW_OBJ(resume)
 250 #define unw_get_proc_info       UNW_OBJ(get_proc_info)
 251 #define unw_get_proc_info_by_ip UNW_OBJ(get_proc_info_by_ip)
 252 #define unw_get_reg             UNW_OBJ(get_reg)
 253 #define unw_set_reg             UNW_OBJ(set_reg)
 254 #define unw_get_fpreg           UNW_OBJ(get_fpreg)
 255 #define unw_set_fpreg           UNW_OBJ(set_fpreg)
 256 #define unw_get_save_loc        UNW_OBJ(get_save_loc)
 257 #define unw_is_signal_frame     UNW_OBJ(is_signal_frame)
 258 #define unw_handle_signal_frame UNW_OBJ(handle_signal_frame)
 259 #define unw_get_proc_name       UNW_OBJ(get_proc_name)
 260 #define unw_get_proc_name_by_ip UNW_OBJ(get_proc_name_by_ip)
 261 #define unw_set_caching_policy  UNW_OBJ(set_caching_policy)
 262 #define unw_regname             UNW_ARCH_OBJ(regname)
 263 #define unw_flush_cache         UNW_ARCH_OBJ(flush_cache)
 264 #define unw_strerror            UNW_ARCH_OBJ(strerror)
 265
 266 extern void unw_local_access_addr_space_init (unw_addr_space_t);
 267 extern unw_addr_space_t unw_create_addr_space (unw_accessors_t *, int);
 268 extern void unw_destroy_addr_space (unw_addr_space_t);
 269 extern unw_accessors_t *unw_get_accessors (unw_addr_space_t);
 270 extern void unw_flush_cache (unw_addr_space_t, unw_word_t, unw_word_t);
 271 extern int unw_set_caching_policy (unw_addr_space_t, unw_caching_policy_t);
 272 extern const char *unw_regname (unw_regnum_t);
 273
 274 extern int unw_init_local (unw_cursor_t *, unw_context_t *);
 275 extern int unw_init_remote (unw_cursor_t *, unw_addr_space_t, void *);
 276 extern int unw_step (unw_cursor_t *);
 277 extern int unw_resume (unw_cursor_t *);
 278 extern int unw_get_proc_info (unw_cursor_t *, unw_proc_info_t *);
 279 extern int unw_get_proc_info_by_ip (unw_addr_space_t, unw_word_t,
 280                                     unw_proc_info_t *, void *);
 281 extern int unw_get_reg (unw_cursor_t *, int, unw_word_t *);
 282 extern int unw_set_reg (unw_cursor_t *, int, unw_word_t);
 283 extern int unw_get_fpreg (unw_cursor_t *, int, unw_fpreg_t *);
 284 extern int unw_set_fpreg (unw_cursor_t *, int, unw_fpreg_t);
 285 extern int unw_get_save_loc (unw_cursor_t *, int, unw_save_loc_t *);
 286 extern int unw_is_signal_frame (unw_cursor_t *);
 287 extern int unw_handle_signal_frame (unw_cursor_t *);
 288 extern int unw_get_proc_name (unw_cursor_t *, char *, size_t, unw_word_t *);
 289 extern int unw_get_proc_name_by_ip (unw_addr_space_t, unw_word_t, char *,
 290                                     size_t, unw_word_t *, void *);
 291 extern const char *unw_strerror (int);
 292 extern int unw_backtrace (void **, int);
 293
 294 /* ANDROID support update. */
 295 extern int unw_map_local_cursor_valid (unw_map_cursor_t *);
 296 extern void unw_map_local_cursor_get (unw_map_cursor_t *);
 297 extern int unw_map_local_cursor_get_next (unw_map_cursor_t *, unw_map_t *);
 298 extern int unw_map_local_create (void);
 299 extern void unw_map_local_destroy (void);
 300 extern void unw_map_set (unw_addr_space_t, unw_map_cursor_t *);
 301 extern void unw_map_cursor_reset (unw_map_cursor_t *);
 302 extern void unw_map_cursor_clear (unw_map_cursor_t *);
 303 extern int unw_map_cursor_create (unw_map_cursor_t *, pid_t);
 304 extern void unw_map_cursor_destroy (unw_map_cursor_t *);
 305 extern int unw_map_cursor_get_next (unw_map_cursor_t *, unw_map_t *);
 306 /* End of ANDROID update. */
 307
 308 extern unw_addr_space_t unw_local_addr_space;