1/* internal.h -- Internal header file for stack backtrace library.
2   Copyright (C) 2012-2016 Free Software Foundation, Inc.
3   Written by Ian Lance Taylor, Google.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are
7met:
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
21THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
25INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
27SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
29STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
30IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31POSSIBILITY 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
91extern void *backtrace_atomic_load_pointer (void *);
92extern int backtrace_atomic_load_int (int *);
93extern void backtrace_atomic_store_pointer (void *, void *);
94extern void backtrace_atomic_store_size_t (size_t *, size_t);
95extern 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
114typedef 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
121typedef 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
127struct 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  /* The shared library iterator.
152     If this is NULL then dl_iterate_phdr is used (via a wrapper).  */
153  backtrace_so_iterator *so_iterator;
154  /* The ITER_STATE argument to SO_ITERATOR.  */
155  void *iter_state;
156  /* The base address of FILENAME.
157     This is for PIE executables and shared libraries where the caller already
158     knows it.  */
159  uintptr_t base_address;
160  /* Non-zero if BASE_ADDRESS has been set.  */
161  int base_address_set;
162  /* Target-specific state.
163     This is generally initialized inside backtrace_initialize and then
164     freed in backtrace_destroy_target.  */
165  void *target_state;
166};
167
168/* Open a file for reading.  Returns -1 on error.  If DOES_NOT_EXIST
169   is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1
170   if the file does not exist.  If the file does not exist and
171   DOES_NOT_EXIST is not NULL, the function will return -1 and will
172   not call ERROR_CALLBACK.  On other errors, or if DOES_NOT_EXIST is
173   NULL, the function will call ERROR_CALLBACK before returning.  */
174extern int backtrace_open (const char *filename,
175			   backtrace_error_callback error_callback,
176			   void *data,
177			   int *does_not_exist);
178
179/* A view of the contents of a file.  This supports mmap when
180   available.  A view will remain in memory even after backtrace_close
181   is called on the file descriptor from which the view was
182   obtained.  */
183
184struct backtrace_view
185{
186  /* The data that the caller requested.  */
187  const void *data;
188  /* The base of the view.  */
189  void *base;
190  /* The total length of the view.  */
191  size_t len;
192};
193
194/* Create a view of SIZE bytes from DESCRIPTOR at OFFSET.  Store the
195   result in *VIEW.  Returns 1 on success, 0 on error.  */
196extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
197			       off_t offset, size_t size,
198			       backtrace_error_callback error_callback,
199			       void *data, struct backtrace_view *view);
200
201/* Release a view created by backtrace_get_view.  */
202extern void backtrace_release_view (struct backtrace_state *state,
203				    struct backtrace_view *view,
204				    backtrace_error_callback error_callback,
205				    void *data);
206
207/* Close a file opened by backtrace_open.  Returns 1 on success, 0 on
208   error.  */
209
210extern int backtrace_close (int descriptor,
211			    backtrace_error_callback error_callback,
212			    void *data);
213
214/* Sort without using memory.  */
215
216extern void backtrace_qsort (void *base, size_t count, size_t size,
217			     int (*compar) (const void *, const void *));
218
219/* Allocate memory.  This is like malloc.  If ERROR_CALLBACK is NULL,
220   this does not report an error, it just returns NULL.  */
221
222extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
223			      backtrace_error_callback error_callback,
224			      void *data) ATTRIBUTE_MALLOC;
225
226/* Free memory allocated by backtrace_alloc.  If ERROR_CALLBACK is
227   NULL, this does not report an error.  */
228
229extern void backtrace_free (struct backtrace_state *state, void *mem,
230			    size_t size,
231			    backtrace_error_callback error_callback,
232			    void *data);
233
234/* A growable vector of some struct.  This is used for more efficient
235   allocation when we don't know the final size of some group of data
236   that we want to represent as an array.  */
237
238struct backtrace_vector
239{
240  /* The base of the vector.  */
241  void *base;
242  /* The number of bytes in the vector.  */
243  size_t size;
244  /* The number of bytes available at the current allocation.  */
245  size_t alc;
246};
247
248/* Grow VEC by SIZE bytes.  Return a pointer to the newly allocated
249   bytes.  Note that this may move the entire vector to a new memory
250   location.  Returns NULL on failure.  */
251
252extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size,
253				    backtrace_error_callback error_callback,
254				    void *data,
255				    struct backtrace_vector *vec);
256
257/* Finish the current allocation on VEC.  Prepare to start a new
258   allocation.  The finished allocation will never be freed.  Returns
259   a pointer to the base of the finished entries, or NULL on
260   failure.  */
261
262extern void* backtrace_vector_finish (struct backtrace_state *state,
263				      struct backtrace_vector *vec,
264				      backtrace_error_callback error_callback,
265				      void *data);
266
267/* Release any extra space allocated for VEC.  This may change
268   VEC->base.  Returns 1 on success, 0 on failure.  */
269
270extern int backtrace_vector_release (struct backtrace_state *state,
271				     struct backtrace_vector *vec,
272				     backtrace_error_callback error_callback,
273				     void *data);
274
275/* Read initial debug data from a descriptor, and set the
276   fileline_data, syminfo_fn, and syminfo_data fields of STATE.
277   Return the fileln_fn field in *FILELN_FN--this is done this way so
278   that the synchronization code is only implemented once.  This is
279   called after the descriptor has first been opened.  It will close
280   the descriptor if it is no longer needed.  Returns 1 on success, 0
281   on error.  There will be multiple implementations of this function,
282   for different file formats.  Each system will compile the
283   appropriate one.  */
284
285extern int backtrace_initialize (struct backtrace_state *state,
286				 int descriptor,
287				 backtrace_error_callback error_callback,
288				 void *data,
289				 fileline *fileline_fn);
290
291/* Called by backtrace_destroy_state to free all target-specific resources
292   held by STATE.  */
293
294extern void backtrace_destroy_target (struct backtrace_state *state,
295                                      backtrace_error_callback error_callback,
296                                      void *data);
297
298/* Add file/line information for a DWARF module.  */
299
300extern int backtrace_dwarf_add (struct backtrace_state *state,
301				uintptr_t base_address,
302				const unsigned char* dwarf_info,
303				size_t dwarf_info_size,
304				const unsigned char *dwarf_line,
305				size_t dwarf_line_size,
306				const unsigned char *dwarf_abbrev,
307				size_t dwarf_abbrev_size,
308				const unsigned char *dwarf_ranges,
309				size_t dwarf_range_size,
310				const unsigned char *dwarf_str,
311				size_t dwarf_str_size,
312				int is_bigendian,
313				backtrace_error_callback error_callback,
314				void *data, fileline *fileline_fn);
315
316#endif
317