git.cworth.org Git - vogl/blob - src/libbacktrace/internal.h

   1 /* internal.h -- Internal header file for stack backtrace library.
   2    Copyright (C) 2012-2014 Free Software Foundation, Inc.
   3    Written by Ian Lance Taylor, Google.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are
   7 met:
   8
   9     (1) Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11
  12     (2) Redistributions in binary form must reproduce the above copyright
  13     notice, this list of conditions and the following disclaimer in
  14     the documentation and/or other materials provided with the
  15     distribution.
  16
  17     (3) The name of the author may not be used to
  18     endorse or promote products derived from this software without
  19     specific prior written permission.
  20
  21 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  23 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  24 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
  25 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  27 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  29 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  30 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  31 POSSIBILITY OF SUCH DAMAGE.  */
  32
  33 #ifndef BACKTRACE_INTERNAL_H
  34 #define BACKTRACE_INTERNAL_H
  35
  36 /* We assume that <sys/types.h> and "backtrace.h" have already been
  37    included.  */
  38
  39 #ifndef GCC_VERSION
  40 # define GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__)
  41 #endif
  42
  43 #if (GCC_VERSION < 2007)
  44 # define __attribute__(x)
  45 #endif
  46
  47 #ifndef ATTRIBUTE_UNUSED
  48 # define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
  49 #endif
  50
  51 #ifndef ATTRIBUTE_MALLOC
  52 # if (GCC_VERSION >= 2096)
  53 #  define ATTRIBUTE_MALLOC __attribute__ ((__malloc__))
  54 # else
  55 #  define ATTRIBUTE_MALLOC
  56 # endif
  57 #endif
  58
  59 #ifndef HAVE_SYNC_FUNCTIONS
  60
  61 /* Define out the sync functions.  These should never be called if
  62    they are not available.  */
  63
  64 #define __sync_bool_compare_and_swap(A, B, C) (abort(), 1)
  65 #define __sync_lock_test_and_set(A, B) (abort(), 0)
  66 #define __sync_lock_release(A) abort()
  67
  68 #endif /* !defined (HAVE_SYNC_FUNCTIONS) */
  69
  70 #ifdef HAVE_ATOMIC_FUNCTIONS
  71
  72 /* We have the atomic builtin functions.  */
  73
  74 #define backtrace_atomic_load_pointer(p) \
  75     __atomic_load_n ((p), __ATOMIC_ACQUIRE)
  76 #define backtrace_atomic_load_int(p) \
  77     __atomic_load_n ((p), __ATOMIC_ACQUIRE)
  78 #define backtrace_atomic_store_pointer(p, v) \
  79     __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
  80 #define backtrace_atomic_store_size_t(p, v) \
  81     __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
  82 #define backtrace_atomic_store_int(p, v) \
  83     __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
  84
  85 #else /* !defined (HAVE_ATOMIC_FUNCTIONS) */
  86 #ifdef HAVE_SYNC_FUNCTIONS
  87
  88 /* We have the sync functions but not the atomic functions.  Define
  89    the atomic ones in terms of the sync ones.  */
  90
  91 extern void *backtrace_atomic_load_pointer (void *);
  92 extern int backtrace_atomic_load_int (int *);
  93 extern void backtrace_atomic_store_pointer (void *, void *);
  94 extern void backtrace_atomic_store_size_t (size_t *, size_t);
  95 extern void backtrace_atomic_store_int (int *, int);
  96
  97 #else /* !defined (HAVE_SYNC_FUNCTIONS) */
  98
  99 /* We have neither the sync nor the atomic functions.  These will
 100    never be called.  */
 101
 102 #define backtrace_atomic_load_pointer(p) (abort(), 0)
 103 #define backtrace_atomic_load_int(p) (abort(), 0)
 104 #define backtrace_atomic_store_pointer(p, v) abort()
 105 #define backtrace_atomic_store_size_t(p, v) abort()
 106 #define backtrace_atomic_store_int(p, v) abort()
 107
 108 #endif /* !defined (HAVE_SYNC_FUNCTIONS) */
 109 #endif /* !defined (HAVE_ATOMIC_FUNCTIONS) */
 110
 111 /* The type of the function that collects file/line information.  This
 112    is like backtrace_pcinfo.  */
 113
 114 typedef int (*fileline) (struct backtrace_state *state, uintptr_t pc,
 115                          backtrace_full_callback callback,
 116                          backtrace_error_callback error_callback, void *data);
 117
 118 /* The type of the function that collects symbol information.  This is
 119    like backtrace_syminfo.  */
 120
 121 typedef void (*syminfo) (struct backtrace_state *state, uintptr_t pc,
 122                          backtrace_syminfo_callback callback,
 123                          backtrace_error_callback error_callback, void *data);
 124
 125 /* What the backtrace state pointer points to.  */
 126
 127 struct backtrace_state
 128 {
 129   /* The name of the executable.  */
 130   const char *filename;
 131   /* The name of the debug symbols filename.  */
 132   const char *debug_filename;
 133   /* Non-zero if threaded.  */
 134   int threaded;
 135   /* The master lock for fileline_fn, fileline_data, syminfo_fn,
 136      syminfo_data, fileline_initialization_failed and everything the
 137      data pointers point to.  */
 138   void *lock;
 139   /* The function that returns file/line information.  */
 140   fileline fileline_fn;
 141   /* The data to pass to FILELINE_FN.  */
 142   void *fileline_data;
 143   /* The function that returns symbol information.  */
 144   syminfo syminfo_fn;
 145   /* The data to pass to SYMINFO_FN.  */
 146   void *syminfo_data;
 147   /* Whether initializing the file/line information failed.  */
 148   int fileline_initialization_failed;
 149   /* The lock for the freelist.  */
 150   int lock_alloc;
 151   /* The freelist when using mmap.  */
 152   struct backtrace_freelist_struct *freelist;
 153 };
 154
 155 /* Open a file for reading.  Returns -1 on error.  If DOES_NOT_EXIST
 156    is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1
 157    if the file does not exist.  If the file does not exist and
 158    DOES_NOT_EXIST is not NULL, the function will return -1 and will
 159    not call ERROR_CALLBACK.  On other errors, or if DOES_NOT_EXIST is
 160    NULL, the function will call ERROR_CALLBACK before returning.  */
 161 extern int backtrace_open (const char *filename,
 162                            backtrace_error_callback error_callback,
 163                            void *data,
 164                            int *does_not_exist);
 165
 166 /* A view of the contents of a file.  This supports mmap when
 167    available.  A view will remain in memory even after backtrace_close
 168    is called on the file descriptor from which the view was
 169    obtained.  */
 170
 171 struct backtrace_view
 172 {
 173   /* The data that the caller requested.  */
 174   const void *data;
 175   /* The base of the view.  */
 176   void *base;
 177   /* The total length of the view.  */
 178   size_t len;
 179 };
 180
 181 /* Create a view of SIZE bytes from DESCRIPTOR at OFFSET.  Store the
 182    result in *VIEW.  Returns 1 on success, 0 on error.  */
 183 extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
 184                                off_t offset, size_t size,
 185                                backtrace_error_callback error_callback,
 186                                void *data, struct backtrace_view *view);
 187
 188 /* Release a view created by backtrace_get_view.  */
 189 extern void backtrace_release_view (struct backtrace_state *state,
 190                                     struct backtrace_view *view,
 191                                     backtrace_error_callback error_callback,
 192                                     void *data);
 193
 194 /* Close a file opened by backtrace_open.  Returns 1 on success, 0 on
 195    error.  */
 196
 197 extern int backtrace_close (int descriptor,
 198                             backtrace_error_callback error_callback,
 199                             void *data);
 200
 201 /* Allocate memory.  This is like malloc.  */
 202
 203 extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
 204                               backtrace_error_callback error_callback,
 205                               void *data) ATTRIBUTE_MALLOC;
 206
 207 /* Free memory allocated by backtrace_alloc.  */
 208
 209 extern void backtrace_free (struct backtrace_state *state, void *mem,
 210                             size_t size,
 211                             backtrace_error_callback error_callback,
 212                             void *data);
 213
 214 /* Allocate memory like strdup. */
 215
 216 extern char *backtrace_strdup (struct backtrace_state *state, const char *str,
 217                                backtrace_error_callback error_callback,
 218                                void *data) ATTRIBUTE_MALLOC;
 219
 220 /* A growable vector of some struct.  This is used for more efficient
 221    allocation when we don't know the final size of some group of data
 222    that we want to represent as an array.  */
 223
 224 struct backtrace_vector
 225 {
 226   /* The base of the vector.  */
 227   void *base;
 228   /* The number of bytes in the vector.  */
 229   size_t size;
 230   /* The number of bytes available at the current allocation.  */
 231   size_t alc;
 232 };
 233
 234 /* Grow VEC by SIZE bytes.  Return a pointer to the newly allocated
 235    bytes.  Note that this may move the entire vector to a new memory
 236    location.  Returns NULL on failure.  */
 237
 238 extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size,
 239                                     backtrace_error_callback error_callback,
 240                                     void *data,
 241                                     struct backtrace_vector *vec);
 242
 243 /* Finish the current allocation on VEC.  Prepare to start a new
 244    allocation.  The finished allocation will never be freed.  Returns
 245    a pointer to the base of the finished entries, or NULL on
 246    failure.  */
 247
 248 extern void* backtrace_vector_finish (struct backtrace_state *state,
 249                                       struct backtrace_vector *vec,
 250                                       backtrace_error_callback error_callback,
 251                                       void *data);
 252
 253 /* Release any extra space allocated for VEC.  This may change
 254    VEC->base.  Returns 1 on success, 0 on failure.  */
 255
 256 extern int backtrace_vector_release (struct backtrace_state *state,
 257                                      struct backtrace_vector *vec,
 258                                      backtrace_error_callback error_callback,
 259                                      void *data);
 260
 261 /* Read initial debug data from a descriptor, and set the
 262    fileline_data, syminfo_fn, and syminfo_data fields of STATE.
 263    Return the fileln_fn field in *FILELN_FN--this is done this way so
 264    that the synchronization code is only implemented once.  This is
 265    called after the descriptor has first been opened.  It will close
 266    the descriptor if it is no longer needed.  Returns 1 on success, 0
 267    on error.  There will be multiple implementations of this function,
 268    for different file formats.  Each system will compile the
 269    appropriate one.  */
 270
 271 extern int backtrace_initialize (struct backtrace_state *state,
 272                                  const char *filename,
 273                                  uintptr_t base_address,
 274                  int is_exe,
 275                                  backtrace_error_callback error_callback,
 276                                  void *data,
 277                                  fileline *fileline_fn);
 278
 279 /* Add file/line information for a DWARF module.  */
 280
 281 extern int backtrace_dwarf_add (struct backtrace_state *state,
 282                                 uintptr_t base_address,
 283                                 const unsigned char* dwarf_info,
 284                                 size_t dwarf_info_size,
 285                                 const unsigned char *dwarf_line,
 286                                 size_t dwarf_line_size,
 287                                 const unsigned char *dwarf_abbrev,
 288                                 size_t dwarf_abbrev_size,
 289                                 const unsigned char *dwarf_ranges,
 290                                 size_t dwarf_range_size,
 291                                 const unsigned char *dwarf_str,
 292                                 size_t dwarf_str_size,
 293                                 int is_bigendian,
 294                                 backtrace_error_callback error_callback,
 295                                 void *data, fileline *fileline_fn);
 296
 297 #endif