libbacktrace/internal.h

   1 /* internal.h -- Internal header file for stack backtrace library.
   2    Copyright (C) 2012-2024 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 ATTRIBUTE_FALLTHROUGH
  60 # if (GCC_VERSION >= 7000)
  61 #  define ATTRIBUTE_FALLTHROUGH __attribute__ ((__fallthrough__))
  62 # else
  63 #  define ATTRIBUTE_FALLTHROUGH
  64 # endif
  65 #endif
  66
  67 #ifndef HAVE_SYNC_FUNCTIONS
  68
  69 /* Define out the sync functions.  These should never be called if
  70    they are not available.  */
  71
  72 #define __sync_bool_compare_and_swap(A, B, C) (abort(), 1)
  73 #define __sync_lock_test_and_set(A, B) (abort(), 0)
  74 #define __sync_lock_release(A) abort()
  75
  76 #endif /* !defined (HAVE_SYNC_FUNCTIONS) */
  77
  78 #ifdef HAVE_ATOMIC_FUNCTIONS
  79
  80 /* We have the atomic builtin functions.  */
  81
  82 #define backtrace_atomic_load_pointer(p) \
  83     __atomic_load_n ((p), __ATOMIC_ACQUIRE)
  84 #define backtrace_atomic_load_int(p) \
  85     __atomic_load_n ((p), __ATOMIC_ACQUIRE)
  86 #define backtrace_atomic_store_pointer(p, v) \
  87     __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
  88 #define backtrace_atomic_store_size_t(p, v) \
  89     __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
  90 #define backtrace_atomic_store_int(p, v) \
  91     __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
  92
  93 #else /* !defined (HAVE_ATOMIC_FUNCTIONS) */
  94 #ifdef HAVE_SYNC_FUNCTIONS
  95
  96 /* We have the sync functions but not the atomic functions.  Define
  97    the atomic ones in terms of the sync ones.  */
  98
  99 extern void *backtrace_atomic_load_pointer (void *);
 100 extern int backtrace_atomic_load_int (int *);
 101 extern void backtrace_atomic_store_pointer (void *, void *);
 102 extern void backtrace_atomic_store_size_t (size_t *, size_t);
 103 extern void backtrace_atomic_store_int (int *, int);
 104
 105 #else /* !defined (HAVE_SYNC_FUNCTIONS) */
 106
 107 /* We have neither the sync nor the atomic functions.  These will
 108    never be called.  */
 109
 110 #define backtrace_atomic_load_pointer(p) (abort(), (void *) NULL)
 111 #define backtrace_atomic_load_int(p) (abort(), 0)
 112 #define backtrace_atomic_store_pointer(p, v) abort()
 113 #define backtrace_atomic_store_size_t(p, v) abort()
 114 #define backtrace_atomic_store_int(p, v) abort()
 115
 116 #endif /* !defined (HAVE_SYNC_FUNCTIONS) */
 117 #endif /* !defined (HAVE_ATOMIC_FUNCTIONS) */
 118
 119 /* The type of the function that collects file/line information.  This
 120    is like backtrace_pcinfo.  */
 121
 122 typedef int (*fileline) (struct backtrace_state *state, uintptr_t pc,
 123                          backtrace_full_callback callback,
 124                          backtrace_error_callback error_callback, void *data);
 125
 126 /* The type of the function that collects symbol information.  This is
 127    like backtrace_syminfo.  */
 128
 129 typedef void (*syminfo) (struct backtrace_state *state, uintptr_t pc,
 130                          backtrace_syminfo_callback callback,
 131                          backtrace_error_callback error_callback, void *data);
 132
 133 /* What the backtrace state pointer points to.  */
 134
 135 struct backtrace_state
 136 {
 137   /* The name of the executable.  */
 138   const char *filename;
 139   /* Non-zero if threaded.  */
 140   int threaded;
 141   /* The master lock for fileline_fn, fileline_data, syminfo_fn,
 142      syminfo_data, fileline_initialization_failed and everything the
 143      data pointers point to.  */
 144   void *lock;
 145   /* The function that returns file/line information.  */
 146   fileline fileline_fn;
 147   /* The data to pass to FILELINE_FN.  */
 148   void *fileline_data;
 149   /* The function that returns symbol information.  */
 150   syminfo syminfo_fn;
 151   /* The data to pass to SYMINFO_FN.  */
 152   void *syminfo_data;
 153   /* Whether initializing the file/line information failed.  */
 154   int fileline_initialization_failed;
 155   /* The lock for the freelist.  */
 156   int lock_alloc;
 157   /* The freelist when using mmap.  */
 158   struct backtrace_freelist_struct *freelist;
 159 };
 160
 161 /* Open a file for reading.  Returns -1 on error.  If DOES_NOT_EXIST
 162    is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1
 163    if the file does not exist.  If the file does not exist and
 164    DOES_NOT_EXIST is not NULL, the function will return -1 and will
 165    not call ERROR_CALLBACK.  On other errors, or if DOES_NOT_EXIST is
 166    NULL, the function will call ERROR_CALLBACK before returning.  */
 167 extern int backtrace_open (const char *filename,
 168                            backtrace_error_callback error_callback,
 169                            void *data,
 170                            int *does_not_exist);
 171
 172 /* A view of the contents of a file.  This supports mmap when
 173    available.  A view will remain in memory even after backtrace_close
 174    is called on the file descriptor from which the view was
 175    obtained.  */
 176
 177 struct backtrace_view
 178 {
 179   /* The data that the caller requested.  */
 180   const void *data;
 181   /* The base of the view.  */
 182   void *base;
 183   /* The total length of the view.  */
 184   size_t len;
 185 };
 186
 187 /* Create a view of SIZE bytes from DESCRIPTOR at OFFSET.  Store the
 188    result in *VIEW.  Returns 1 on success, 0 on error.  */
 189 extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
 190                                off_t offset, uint64_t size,
 191                                backtrace_error_callback error_callback,
 192                                void *data, struct backtrace_view *view);
 193
 194 /* Release a view created by backtrace_get_view.  */
 195 extern void backtrace_release_view (struct backtrace_state *state,
 196                                     struct backtrace_view *view,
 197                                     backtrace_error_callback error_callback,
 198                                     void *data);
 199
 200 /* Close a file opened by backtrace_open.  Returns 1 on success, 0 on
 201    error.  */
 202
 203 extern int backtrace_close (int descriptor,
 204                             backtrace_error_callback error_callback,
 205                             void *data);
 206
 207 /* Sort without using memory.  */
 208
 209 extern void backtrace_qsort (void *base, size_t count, size_t size,
 210                              int (*compar) (const void *, const void *));
 211
 212 /* Allocate memory.  This is like malloc.  If ERROR_CALLBACK is NULL,
 213    this does not report an error, it just returns NULL.  */
 214
 215 extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
 216                               backtrace_error_callback error_callback,
 217                               void *data) ATTRIBUTE_MALLOC;
 218
 219 /* Free memory allocated by backtrace_alloc.  If ERROR_CALLBACK is
 220    NULL, this does not report an error.  */
 221
 222 extern void backtrace_free (struct backtrace_state *state, void *mem,
 223                             size_t size,
 224                             backtrace_error_callback error_callback,
 225                             void *data);
 226
 227 /* A growable vector of some struct.  This is used for more efficient
 228    allocation when we don't know the final size of some group of data
 229    that we want to represent as an array.  */
 230
 231 struct backtrace_vector
 232 {
 233   /* The base of the vector.  */
 234   void *base;
 235   /* The number of bytes in the vector.  */
 236   size_t size;
 237   /* The number of bytes available at the current allocation.  */
 238   size_t alc;
 239 };
 240
 241 /* Grow VEC by SIZE bytes.  Return a pointer to the newly allocated
 242    bytes.  Note that this may move the entire vector to a new memory
 243    location.  Returns NULL on failure.  */
 244
 245 extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size,
 246                                     backtrace_error_callback error_callback,
 247                                     void *data,
 248                                     struct backtrace_vector *vec);
 249
 250 /* Finish the current allocation on VEC.  Prepare to start a new
 251    allocation.  The finished allocation will never be freed.  Returns
 252    a pointer to the base of the finished entries, or NULL on
 253    failure.  */
 254
 255 extern void* backtrace_vector_finish (struct backtrace_state *state,
 256                                       struct backtrace_vector *vec,
 257                                       backtrace_error_callback error_callback,
 258                                       void *data);
 259
 260 /* Release any extra space allocated for VEC.  This may change
 261    VEC->base.  Returns 1 on success, 0 on failure.  */
 262
 263 extern int backtrace_vector_release (struct backtrace_state *state,
 264                                      struct backtrace_vector *vec,
 265                                      backtrace_error_callback error_callback,
 266                                      void *data);
 267
 268 /* Free the space managed by VEC.  This will reset VEC.  */
 269
 270 static inline void
 271 backtrace_vector_free (struct backtrace_state *state,
 272                        struct backtrace_vector *vec,
 273                        backtrace_error_callback error_callback, void *data)
 274 {
 275   vec->alc += vec->size;
 276   vec->size = 0;
 277   backtrace_vector_release (state, vec, error_callback, data);
 278 }
 279
 280 /* Read initial debug data from a descriptor, and set the
 281    fileline_data, syminfo_fn, and syminfo_data fields of STATE.
 282    Return the fileln_fn field in *FILELN_FN--this is done this way so
 283    that the synchronization code is only implemented once.  This is
 284    called after the descriptor has first been opened.  It will close
 285    the descriptor if it is no longer needed.  Returns 1 on success, 0
 286    on error.  There will be multiple implementations of this function,
 287    for different file formats.  Each system will compile the
 288    appropriate one.  */
 289
 290 extern int backtrace_initialize (struct backtrace_state *state,
 291                                  const char *filename,
 292                                  int descriptor,
 293                                  backtrace_error_callback error_callback,
 294                                  void *data,
 295                                  fileline *fileline_fn);
 296
 297 /* An enum for the DWARF sections we care about.  */
 298
 299 enum dwarf_section
 300 {
 301   DEBUG_INFO,
 302   DEBUG_LINE,
 303   DEBUG_ABBREV,
 304   DEBUG_RANGES,
 305   DEBUG_STR,
 306   DEBUG_ADDR,
 307   DEBUG_STR_OFFSETS,
 308   DEBUG_LINE_STR,
 309   DEBUG_RNGLISTS,
 310
 311   DEBUG_MAX
 312 };
 313
 314 /* Data for the DWARF sections we care about.  */
 315
 316 struct dwarf_sections
 317 {
 318   const unsigned char *data[DEBUG_MAX];
 319   size_t size[DEBUG_MAX];
 320 };
 321
 322 /* DWARF data read from a file, used for .gnu_debugaltlink.  */
 323
 324 struct dwarf_data;
 325
 326 /* Add file/line information for a DWARF module.  */
 327
 328 extern int backtrace_dwarf_add (struct backtrace_state *state,
 329                                 uintptr_t base_address,
 330                                 const struct dwarf_sections *dwarf_sections,
 331                                 int is_bigendian,
 332                                 struct dwarf_data *fileline_altlink,
 333                                 backtrace_error_callback error_callback,
 334                                 void *data, fileline *fileline_fn,
 335                                 struct dwarf_data **fileline_entry);
 336
 337 /* A data structure to pass to backtrace_syminfo_to_full.  */
 338
 339 struct backtrace_call_full
 340 {
 341   backtrace_full_callback full_callback;
 342   backtrace_error_callback full_error_callback;
 343   void *full_data;
 344   int ret;
 345 };
 346
 347 /* A backtrace_syminfo_callback that can call into a
 348    backtrace_full_callback, used when we have a symbol table but no
 349    debug info.  */
 350
 351 extern void backtrace_syminfo_to_full_callback (void *data, uintptr_t pc,
 352                                                 const char *symname,
 353                                                 uintptr_t symval,
 354                                                 uintptr_t symsize);
 355
 356 /* An error callback that corresponds to
 357    backtrace_syminfo_to_full_callback.  */
 358
 359 extern void backtrace_syminfo_to_full_error_callback (void *, const char *,
 360                                                       int);
 361
 362 /* A test-only hook for elf_uncompress_zdebug.  */
 363
 364 extern int backtrace_uncompress_zdebug (struct backtrace_state *,
 365                                         const unsigned char *compressed,
 366                                         size_t compressed_size,
 367                                         backtrace_error_callback, void *data,
 368                                         unsigned char **uncompressed,
 369                                         size_t *uncompressed_size);
 370
 371 /* A test-only hook for elf_zstd_decompress.  */
 372
 373 extern int backtrace_uncompress_zstd (struct backtrace_state *,
 374                                       const unsigned char *compressed,
 375                                       size_t compressed_size,
 376                                       backtrace_error_callback, void *data,
 377                                       unsigned char *uncompressed,
 378                                       size_t uncompressed_size);
 379
 380 /* A test-only hook for elf_uncompress_lzma.  */
 381
 382 extern int backtrace_uncompress_lzma (struct backtrace_state *,
 383                                       const unsigned char *compressed,
 384                                       size_t compressed_size,
 385                                       backtrace_error_callback, void *data,
 386                                       unsigned char **uncompressed,
 387                                       size_t *uncompressed_size);
 388
 389 #endif