libbacktrace/internal.h

   1 /* internal.h -- Internal header file for stack backtrace library.
   2    Copyright (C) 2012-2020 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(), (void *) NULL)
 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   /* Non-zero if threaded.  */
 132   int threaded;
 133   /* The master lock for fileline_fn, fileline_data, syminfo_fn,
 134      syminfo_data, fileline_initialization_failed and everything the
 135      data pointers point to.  */
 136   void *lock;
 137   /* The function that returns file/line information.  */
 138   fileline fileline_fn;
 139   /* The data to pass to FILELINE_FN.  */
 140   void *fileline_data;
 141   /* The function that returns symbol information.  */
 142   syminfo syminfo_fn;
 143   /* The data to pass to SYMINFO_FN.  */
 144   void *syminfo_data;
 145   /* Whether initializing the file/line information failed.  */
 146   int fileline_initialization_failed;
 147   /* The lock for the freelist.  */
 148   int lock_alloc;
 149   /* The freelist when using mmap.  */
 150   struct backtrace_freelist_struct *freelist;
 151 };
 152
 153 /* Open a file for reading.  Returns -1 on error.  If DOES_NOT_EXIST
 154    is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1
 155    if the file does not exist.  If the file does not exist and
 156    DOES_NOT_EXIST is not NULL, the function will return -1 and will
 157    not call ERROR_CALLBACK.  On other errors, or if DOES_NOT_EXIST is
 158    NULL, the function will call ERROR_CALLBACK before returning.  */
 159 extern int backtrace_open (const char *filename,
 160                            backtrace_error_callback error_callback,
 161                            void *data,
 162                            int *does_not_exist);
 163
 164 /* A view of the contents of a file.  This supports mmap when
 165    available.  A view will remain in memory even after backtrace_close
 166    is called on the file descriptor from which the view was
 167    obtained.  */
 168
 169 struct backtrace_view
 170 {
 171   /* The data that the caller requested.  */
 172   const void *data;
 173   /* The base of the view.  */
 174   void *base;
 175   /* The total length of the view.  */
 176   size_t len;
 177 };
 178
 179 /* Create a view of SIZE bytes from DESCRIPTOR at OFFSET.  Store the
 180    result in *VIEW.  Returns 1 on success, 0 on error.  */
 181 extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
 182                                off_t offset, uint64_t size,
 183                                backtrace_error_callback error_callback,
 184                                void *data, struct backtrace_view *view);
 185
 186 /* Release a view created by backtrace_get_view.  */
 187 extern void backtrace_release_view (struct backtrace_state *state,
 188                                     struct backtrace_view *view,
 189                                     backtrace_error_callback error_callback,
 190                                     void *data);
 191
 192 /* Close a file opened by backtrace_open.  Returns 1 on success, 0 on
 193    error.  */
 194
 195 extern int backtrace_close (int descriptor,
 196                             backtrace_error_callback error_callback,
 197                             void *data);
 198
 199 /* Sort without using memory.  */
 200
 201 extern void backtrace_qsort (void *base, size_t count, size_t size,
 202                              int (*compar) (const void *, const void *));
 203
 204 /* Allocate memory.  This is like malloc.  If ERROR_CALLBACK is NULL,
 205    this does not report an error, it just returns NULL.  */
 206
 207 extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
 208                               backtrace_error_callback error_callback,
 209                               void *data) ATTRIBUTE_MALLOC;
 210
 211 /* Free memory allocated by backtrace_alloc.  If ERROR_CALLBACK is
 212    NULL, this does not report an error.  */
 213
 214 extern void backtrace_free (struct backtrace_state *state, void *mem,
 215                             size_t size,
 216                             backtrace_error_callback error_callback,
 217                             void *data);
 218
 219 /* A growable vector of some struct.  This is used for more efficient
 220    allocation when we don't know the final size of some group of data
 221    that we want to represent as an array.  */
 222
 223 struct backtrace_vector
 224 {
 225   /* The base of the vector.  */
 226   void *base;
 227   /* The number of bytes in the vector.  */
 228   size_t size;
 229   /* The number of bytes available at the current allocation.  */
 230   size_t alc;
 231 };
 232
 233 /* Grow VEC by SIZE bytes.  Return a pointer to the newly allocated
 234    bytes.  Note that this may move the entire vector to a new memory
 235    location.  Returns NULL on failure.  */
 236
 237 extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size,
 238                                     backtrace_error_callback error_callback,
 239                                     void *data,
 240                                     struct backtrace_vector *vec);
 241
 242 /* Finish the current allocation on VEC.  Prepare to start a new
 243    allocation.  The finished allocation will never be freed.  Returns
 244    a pointer to the base of the finished entries, or NULL on
 245    failure.  */
 246
 247 extern void* backtrace_vector_finish (struct backtrace_state *state,
 248                                       struct backtrace_vector *vec,
 249                                       backtrace_error_callback error_callback,
 250                                       void *data);
 251
 252 /* Release any extra space allocated for VEC.  This may change
 253    VEC->base.  Returns 1 on success, 0 on failure.  */
 254
 255 extern int backtrace_vector_release (struct backtrace_state *state,
 256                                      struct backtrace_vector *vec,
 257                                      backtrace_error_callback error_callback,
 258                                      void *data);
 259
 260 /* Free the space managed by VEC.  This will reset VEC.  */
 261
 262 static inline void
 263 backtrace_vector_free (struct backtrace_state *state,
 264                        struct backtrace_vector *vec,
 265                        backtrace_error_callback error_callback, void *data)
 266 {
 267   vec->alc += vec->size;
 268   vec->size = 0;
 269   backtrace_vector_release (state, vec, error_callback, data);
 270 }
 271
 272 /* Read initial debug data from a descriptor, and set the
 273    fileline_data, syminfo_fn, and syminfo_data fields of STATE.
 274    Return the fileln_fn field in *FILELN_FN--this is done this way so
 275    that the synchronization code is only implemented once.  This is
 276    called after the descriptor has first been opened.  It will close
 277    the descriptor if it is no longer needed.  Returns 1 on success, 0
 278    on error.  There will be multiple implementations of this function,
 279    for different file formats.  Each system will compile the
 280    appropriate one.  */
 281
 282 extern int backtrace_initialize (struct backtrace_state *state,
 283                                  const char *filename,
 284                                  int descriptor,
 285                                  backtrace_error_callback error_callback,
 286                                  void *data,
 287                                  fileline *fileline_fn);
 288
 289 /* An enum for the DWARF sections we care about.  */
 290
 291 enum dwarf_section
 292 {
 293   DEBUG_INFO,
 294   DEBUG_LINE,
 295   DEBUG_ABBREV,
 296   DEBUG_RANGES,
 297   DEBUG_STR,
 298   DEBUG_ADDR,
 299   DEBUG_STR_OFFSETS,
 300   DEBUG_LINE_STR,
 301   DEBUG_RNGLISTS,
 302
 303   DEBUG_MAX
 304 };
 305
 306 /* Data for the DWARF sections we care about.  */
 307
 308 struct dwarf_sections
 309 {
 310   const unsigned char *data[DEBUG_MAX];
 311   size_t size[DEBUG_MAX];
 312 };
 313
 314 /* DWARF data read from a file, used for .gnu_debugaltlink.  */
 315
 316 struct dwarf_data;
 317
 318 /* Add file/line information for a DWARF module.  */
 319
 320 extern int backtrace_dwarf_add (struct backtrace_state *state,
 321                                 uintptr_t base_address,
 322                                 const struct dwarf_sections *dwarf_sections,
 323                                 int is_bigendian,
 324                                 struct dwarf_data *fileline_altlink,
 325                                 backtrace_error_callback error_callback,
 326                                 void *data, fileline *fileline_fn,
 327                                 struct dwarf_data **fileline_entry);
 328
 329 /* A data structure to pass to backtrace_syminfo_to_full.  */
 330
 331 struct backtrace_call_full
 332 {
 333   backtrace_full_callback full_callback;
 334   backtrace_error_callback full_error_callback;
 335   void *full_data;
 336   int ret;
 337 };
 338
 339 /* A backtrace_syminfo_callback that can call into a
 340    backtrace_full_callback, used when we have a symbol table but no
 341    debug info.  */
 342
 343 extern void backtrace_syminfo_to_full_callback (void *data, uintptr_t pc,
 344                                                 const char *symname,
 345                                                 uintptr_t symval,
 346                                                 uintptr_t symsize);
 347
 348 /* An error callback that corresponds to
 349    backtrace_syminfo_to_full_callback.  */
 350
 351 extern void backtrace_syminfo_to_full_error_callback (void *, const char *,
 352                                                       int);
 353
 354 /* A test-only hook for elf_uncompress_zdebug.  */
 355
 356 extern int backtrace_uncompress_zdebug (struct backtrace_state *,
 357                                         const unsigned char *compressed,
 358                                         size_t compressed_size,
 359                                         backtrace_error_callback, void *data,
 360                                         unsigned char **uncompressed,
 361                                         size_t *uncompressed_size);
 362
 363 /* A test-only hook for elf_uncompress_lzma.  */
 364
 365 extern int backtrace_uncompress_lzma (struct backtrace_state *,
 366                                       const unsigned char *compressed,
 367                                       size_t compressed_size,
 368                                       backtrace_error_callback, void *data,
 369                                       unsigned char **uncompressed,
 370                                       size_t *uncompressed_size);
 371
 372 #endif