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 390