2018-08-31 Paul Thomas <pault@gcc.gnu.org>
[official-gcc.git] / libbacktrace / internal.h
blobbff8ed470e4f054b7a63982c2b5b53932a4fb4a2
1 /* internal.h -- Internal header file for stack backtrace library.
2 Copyright (C) 2012-2018 Free Software Foundation, Inc.
3 Written by Ian Lance Taylor, Google.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions are
7 met:
9 (1) Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
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.
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.
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. */
33 #ifndef BACKTRACE_INTERNAL_H
34 #define BACKTRACE_INTERNAL_H
36 /* We assume that <sys/types.h> and "backtrace.h" have already been
37 included. */
39 #ifndef GCC_VERSION
40 # define GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__)
41 #endif
43 #if (GCC_VERSION < 2007)
44 # define __attribute__(x)
45 #endif
47 #ifndef ATTRIBUTE_UNUSED
48 # define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
49 #endif
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
59 #ifndef HAVE_SYNC_FUNCTIONS
61 /* Define out the sync functions. These should never be called if
62 they are not available. */
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()
68 #endif /* !defined (HAVE_SYNC_FUNCTIONS) */
70 #ifdef HAVE_ATOMIC_FUNCTIONS
72 /* We have the atomic builtin functions. */
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)
85 #else /* !defined (HAVE_ATOMIC_FUNCTIONS) */
86 #ifdef HAVE_SYNC_FUNCTIONS
88 /* We have the sync functions but not the atomic functions. Define
89 the atomic ones in terms of the sync ones. */
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);
97 #else /* !defined (HAVE_SYNC_FUNCTIONS) */
99 /* We have neither the sync nor the atomic functions. These will
100 never be called. */
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()
108 #endif /* !defined (HAVE_SYNC_FUNCTIONS) */
109 #endif /* !defined (HAVE_ATOMIC_FUNCTIONS) */
111 /* The type of the function that collects file/line information. This
112 is like backtrace_pcinfo. */
114 typedef int (*fileline) (struct backtrace_state *state, uintptr_t pc,
115 backtrace_full_callback callback,
116 backtrace_error_callback error_callback, void *data);
118 /* The type of the function that collects symbol information. This is
119 like backtrace_syminfo. */
121 typedef void (*syminfo) (struct backtrace_state *state, uintptr_t pc,
122 backtrace_syminfo_callback callback,
123 backtrace_error_callback error_callback, void *data);
125 /* What the backtrace state pointer points to. */
127 struct backtrace_state
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;
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);
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. */
169 struct backtrace_view
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;
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, size_t size,
183 backtrace_error_callback error_callback,
184 void *data, struct backtrace_view *view);
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);
192 /* Close a file opened by backtrace_open. Returns 1 on success, 0 on
193 error. */
195 extern int backtrace_close (int descriptor,
196 backtrace_error_callback error_callback,
197 void *data);
199 /* Sort without using memory. */
201 extern void backtrace_qsort (void *base, size_t count, size_t size,
202 int (*compar) (const void *, const void *));
204 /* Allocate memory. This is like malloc. If ERROR_CALLBACK is NULL,
205 this does not report an error, it just returns NULL. */
207 extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
208 backtrace_error_callback error_callback,
209 void *data) ATTRIBUTE_MALLOC;
211 /* Free memory allocated by backtrace_alloc. If ERROR_CALLBACK is
212 NULL, this does not report an error. */
214 extern void backtrace_free (struct backtrace_state *state, void *mem,
215 size_t size,
216 backtrace_error_callback error_callback,
217 void *data);
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. */
223 struct backtrace_vector
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;
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. */
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);
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. */
247 extern void* backtrace_vector_finish (struct backtrace_state *state,
248 struct backtrace_vector *vec,
249 backtrace_error_callback error_callback,
250 void *data);
252 /* Release any extra space allocated for VEC. This may change
253 VEC->base. Returns 1 on success, 0 on failure. */
255 extern int backtrace_vector_release (struct backtrace_state *state,
256 struct backtrace_vector *vec,
257 backtrace_error_callback error_callback,
258 void *data);
260 /* Read initial debug data from a descriptor, and set the
261 fileline_data, syminfo_fn, and syminfo_data fields of STATE.
262 Return the fileln_fn field in *FILELN_FN--this is done this way so
263 that the synchronization code is only implemented once. This is
264 called after the descriptor has first been opened. It will close
265 the descriptor if it is no longer needed. Returns 1 on success, 0
266 on error. There will be multiple implementations of this function,
267 for different file formats. Each system will compile the
268 appropriate one. */
270 extern int backtrace_initialize (struct backtrace_state *state,
271 const char *filename,
272 int descriptor,
273 backtrace_error_callback error_callback,
274 void *data,
275 fileline *fileline_fn);
277 /* Add file/line information for a DWARF module. */
279 extern int backtrace_dwarf_add (struct backtrace_state *state,
280 uintptr_t base_address,
281 const unsigned char* dwarf_info,
282 size_t dwarf_info_size,
283 const unsigned char *dwarf_line,
284 size_t dwarf_line_size,
285 const unsigned char *dwarf_abbrev,
286 size_t dwarf_abbrev_size,
287 const unsigned char *dwarf_ranges,
288 size_t dwarf_range_size,
289 const unsigned char *dwarf_str,
290 size_t dwarf_str_size,
291 int is_bigendian,
292 backtrace_error_callback error_callback,
293 void *data, fileline *fileline_fn);
295 /* A test-only hook for elf_uncompress_zdebug. */
297 extern int backtrace_uncompress_zdebug (struct backtrace_state *,
298 const unsigned char *compressed,
299 size_t compressed_size,
300 backtrace_error_callback, void *data,
301 unsigned char **uncompressed,
302 size_t *uncompressed_size);
304 #endif