1 /* Interfaces for libdw.
2 Copyright (C) 2002, 2004 Red Hat, Inc.
3 Contributed by Ulrich Drepper <drepper@redhat.com>, 2002.
4
5 This program is Open Source software; you can redistribute it and/or
6 modify it under the terms of the Open Software License version 1.0 as
7 published by the Open Source Initiative.
8
9 You should have received a copy of the Open Software License along
10 with this program; if not, you may obtain a copy of the Open Software
11 License version 1.0 from http://www.opensource.org/licenses/osl.php or
12 by writing the Open Source Initiative c/o Lawrence Rosen, Esq.,
13 3001 King Ranch Road, Ukiah, CA 95482. */
14
15 #ifndef _LIBDW_H
16 #define _LIBDW_H 1
17
18 #include <gelf.h>
19 #include <stdbool.h>
20 #include <stddef.h>
21
22
23 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
24 # define __nonnull_attribute__(...) __attribute__ ((__nonnull__ (__VA_ARGS__)))
25 #else
26 # define __nonnull_attribute__(args...)
27 #endif
28
29
30 /* Mode for the session. */
31 typedef enum
32 {
33 DWARF_C_READ, /* Read .. */
34 DWARF_C_RDWR, /* Read and write .. */
35 DWARF_C_WRITE, /* Write .. */
36 }
37 Dwarf_Cmd;
38
39
40 /* Callback results. */
41 enum
42 {
43 DWARF_CB_OK = 0,
44 DWARF_CB_ABORT
45 };
46
47
48 /* Error values. */
49 enum
50 {
51 DW_TAG_invalid = 0
52 #define DW_TAG_invalid DW_TAG_invalid
53 };
54
55
56 /* Type for offset in DWARF file. */
57 typedef GElf_Off Dwarf_Off;
58
59 /* Type for address in DWARF file. */
60 typedef GElf_Addr Dwarf_Addr;
61
62 /* Integer types. Big enough to hold any numeric value. */
63 typedef GElf_Xword Dwarf_Word;
64 typedef GElf_Sxword Dwarf_Sword;
65 /* For the times we know we do not need that much. */
66 typedef GElf_Half Dwarf_Half;
67
68
69 /* DWARF abbreviation record. */
70 typedef struct Dwarf_Abbrev Dwarf_Abbrev;
71
72 /* Source code line information for CU. */
73 typedef struct Dwarf_Lines_s Dwarf_Lines;
74
75 /* One source code line information. */
76 typedef struct Dwarf_Line_s Dwarf_Line;
77
78 /* Source file information. */
79 typedef struct Dwarf_Files_s Dwarf_Files;
80
81 /* One address range record. */
82 typedef struct Dwarf_Arange_s Dwarf_Arange;
83
84 /* Address ranges of a file. */
85 typedef struct Dwarf_Aranges_s Dwarf_Aranges;
86
87 /* CU representation. */
88 struct Dwarf_CU;
89
90 /* Attribute representation. */
91 typedef struct
92 {
93 unsigned int code;
94 unsigned int form;
95 unsigned char *valp;
96 struct Dwarf_CU *cu;
97 } Dwarf_Attribute;
98
99
100 /* Data block representation. */
101 typedef struct
102 {
103 Dwarf_Word length;
104 unsigned char *data;
105 } Dwarf_Block;
106
107
108 /* Macro information. */
109 typedef struct
110 {
111 unsigned int opcode;
112 Dwarf_Word param1;
113 union
114 {
115 Dwarf_Word u;
116 const char *s;
117 } param2;
118 } Dwarf_Macro;
119
120
121 /* DIE information. */
122 typedef struct
123 {
124 /* The offset can be computed from the address. */
125 void *addr;
126 struct Dwarf_CU *cu;
127 Dwarf_Abbrev *abbrev;
128 // XXX We'll see what other information will be needed.
129 } Dwarf_Die;
130
131 /* Returned to show the last DIE has be returned. */
132 #define DWARF_END_DIE ((Dwarf_Die *) -1l)
133
134
135 /* Global symbol information. */
136 typedef struct
137 {
138 Dwarf_Off cu_offset;
139 Dwarf_Off die_offset;
140 const char *name;
141 } Dwarf_Global;
142
143
144 // XXX It remains to be seen whether the next two need to be exported.
145 /* Location record. */
146 typedef struct
147 {
148 uint8_t atom; /* Operation */
149 Dwarf_Word number; /* Operand */
150 Dwarf_Word number2; /* Possible second operand */
151 Dwarf_Word offset; /* Offset in location expression */
152 } Dwarf_Loc;
153
154
155 /* Handle for debug sessions. */
156 typedef struct Dwarf Dwarf;
157
158
159 /* Out-Of-Memory handler. */
160 typedef void (*__attribute__ ((noreturn)) Dwarf_OOM) (void);
161
162
163 /* Create a handle for a new debug session. */
164 extern Dwarf *dwarf_begin (int fildes, Dwarf_Cmd cmd);
165
166 /* Create a handle for a new debug session for an ELF file. */
167 extern Dwarf *dwarf_begin_elf (Elf *elf, Dwarf_Cmd cmd, Elf_Scn *scngrp);
168
169 /* Retrieve ELF descriptor used for DWARF access. */
170 extern Elf *dwarf_getelf (Dwarf *dwarf);
171
172 /* Release debugging handling context. */
173 extern int dwarf_end (Dwarf *dwarf);
174
175
176 /* Get the data block for the .debug_info section. */
177 extern Elf_Data *dwarf_getscn_info (Dwarf *dwarf);
178
179 /* Read the header for the DWARF CU header. */
180 extern int dwarf_nextcu (Dwarf *dwarf, Dwarf_Off off, Dwarf_Off *next_off,
181 size_t *header_sizep, Dwarf_Off *abbrev_offsetp,
182 uint8_t *address_sizep, uint8_t *offset_sizep)
183 __nonnull_attribute__ (3);
184
185
186 /* Return DIE at given offset. */
187 extern Dwarf_Die *dwarf_offdie (Dwarf *dbg, Dwarf_Off offset,
188 Dwarf_Die *result) __nonnull_attribute__ (3);
189
190 /* Return offset of DIE. */
191 extern Dwarf_Off dwarf_dieoffset (Dwarf_Die *die);
192
193 /* Return offset of DIE in CU. */
194 extern Dwarf_Off dwarf_cuoffset (Dwarf_Die *die);
195
196 /* Return vhild of current DIE. */
197 extern int dwarf_child (Dwarf_Die *die, Dwarf_Die *result)
198 __nonnull_attribute__ (2);
199
200 /* Return sibling of given DIE. */
201 extern int dwarf_siblingof (Dwarf_Die *die, Dwarf_Die *result)
202 __nonnull_attribute__ (2);
203
204 /* Check whether the DIE has children. */
205 extern int dwarf_haschildren (Dwarf_Die *die);
206
207 /* Get attributes of the DIE. */
208 extern ptrdiff_t dwarf_getattrs (Dwarf_Die *die,
209 int (*callback) (Dwarf_Attribute *, void *),
210 void *arg, ptrdiff_t offset);
211
212 /* Return tag of given DIE. */
213 extern int dwarf_tag (Dwarf_Die *die);
214
215
216 /* Return specific attribute of DIE. */
217 extern Dwarf_Attribute *dwarf_attr (Dwarf_Die *die, unsigned int search_name,
218 Dwarf_Attribute *result)
219 __nonnull_attribute__ (3);
220
221 /* Check whether given DIE has specific attribute. */
222 extern int dwarf_hasattr (Dwarf_Die *die, unsigned int search_name);
223
224
225 /* Check whether given attribute has specific form. */
226 extern int dwarf_hasform (Dwarf_Attribute *attr, unsigned int search_form);
227
228 /* Return attribute code of given attribute. */
229 extern unsigned int dwarf_whatattr (Dwarf_Attribute *attr);
230
231 /* Return form code of given attribute. */
232 extern unsigned int dwarf_whatform (Dwarf_Attribute *attr);
233
234
235 /* Return string associated with given attribute. */
236 extern const char *dwarf_formstring (Dwarf_Attribute *attrp);
237
238 /* Return unsigned constant represented by attribute. */
239 extern int dwarf_formudata (Dwarf_Attribute *attr, Dwarf_Word *return_uval)
240 __nonnull_attribute__ (2);
241
242 /* Return signed constant represented by attribute. */
243 extern int dwarf_formsdata (Dwarf_Attribute *attr, Dwarf_Sword *return_uval)
244 __nonnull_attribute__ (2);
245
246 /* Return address represented by attribute. */
247 extern int dwarf_formaddr (Dwarf_Attribute *attr, Dwarf_Addr *return_addr)
248 __nonnull_attribute__ (2);
249
250 /* Return reference offset represented by attribute. */
251 extern int dwarf_formref (Dwarf_Attribute *attr, Dwarf_Off *return_offset)
252 __nonnull_attribute__ (2);
253
254 /* Return block represented by attribute. */
255 extern int dwarf_formblock (Dwarf_Attribute *attr, Dwarf_Block *return_block)
256 __nonnull_attribute__ (2);
257
258 /* Return flag represented by attribute. */
259 extern int dwarf_formflag (Dwarf_Attribute *attr, bool *return_bool)
260 __nonnull_attribute__ (2);
261
262
263 /* Simplified attribute value access functions. */
264
265 /* Return string in name attribute of DIE. */
266 extern const char *dwarf_diename (Dwarf_Die *die);
267
268 /* Return high PC attribute of DIE. */
269 extern int dwarf_highpc (Dwarf_Die *die, Dwarf_Addr *return_addr)
270 __nonnull_attribute__ (2);
271
272 /* Return low PC attribute of DIE. */
273 extern int dwarf_lowpc (Dwarf_Die *die, Dwarf_Addr *return_addr)
274 __nonnull_attribute__ (2);
275
276 /* Return byte size attribute of DIE. */
277 extern int dwarf_bytesize (Dwarf_Die *die);
278
279 /* Return bit size attribute of DIE. */
280 extern int dwarf_bitsize (Dwarf_Die *die);
281
282 /* Return bit offset attribute of DIE. */
283 extern int dwarf_bitoffset (Dwarf_Die *die);
284
285 /* Return array order attribute of DIE. */
286 extern int dwarf_arrayorder (Dwarf_Die *die);
287
288 /* Return source language attribute of DIE. */
289 extern int dwarf_srclang (Dwarf_Die *die);
290
291
292 /* Get abbreviation at given offset for given DIE. */
293 extern Dwarf_Abbrev *dwarf_getabbrev (Dwarf_Die *die, Dwarf_Off offset,
294 size_t *lengthp);
295
296 /* Get abbreviation at given offset in .debug_abbrev section. */
297 extern int dwarf_offabbrev (Dwarf *dbg, Dwarf_Off offset, size_t *lengthp,
298 Dwarf_Abbrev *abbrevp)
299 __nonnull_attribute__ (4);
300
301 /* Get abbreviation code. */
302 extern unsigned int dwarf_getabbrevcode (Dwarf_Abbrev *abbrev);
303
304 /* Get abbreviation tag. */
305 extern unsigned int dwarf_getabbrevtag (Dwarf_Abbrev *abbrev);
306
307 /* Return true if abbreviation is children flag set. */
308 extern int dwarf_abbrevhaschildren (Dwarf_Abbrev *abbrev);
309
310 /* Get number of attributes of abbreviation. */
311 extern int dwarf_getattrcnt (Dwarf_Abbrev *abbrev, size_t *attrcntp)
312 __nonnull_attribute__ (2);
313
314 /* Get specific attribute of abbreviation. */
315 extern int dwarf_getabbrevattr (Dwarf_Abbrev *abbrev, size_t idx,
316 unsigned int *namep, unsigned int *formp,
317 Dwarf_Off *offset);
318
319
320 /* Get string from-debug_str section. */
321 extern const char *dwarf_getstring (Dwarf *dbg, Dwarf_Off offset,
322 size_t *lenp);
323
324
325 /* Get public symbol information. */
326 extern ptrdiff_t dwarf_getpubnames (Dwarf *dbg,
327 int (*callback) (Dwarf *, Dwarf_Global *,
328 void *),
329 void *arg, ptrdiff_t offset)
330 __nonnull_attribute__ (2);
331
332
333 /* Get source file information for CU. */
334 extern int dwarf_getsrclines (Dwarf_Die *cudie, Dwarf_Lines **lines,
335 size_t *nlines) __nonnull_attribute__ (2, 3);
336
337 /* Return one of the source lines of the CU. */
338 extern Dwarf_Line *dwarf_onesrcline (Dwarf_Lines *lines, size_t idx);
339
340 /* Get the file source files used in the CU. */
341 extern int dwarf_getsrcfiles (Dwarf_Die *cudie, Dwarf_Files **files,
342 size_t *nfiles)
343 __nonnull_attribute__ (2);
344
345
346 /* Get source for address in CU. */
347 extern Dwarf_Line *dwarf_getsrc_die (Dwarf_Die *cudie, Dwarf_Addr addr);
348
349 /* Return line address. */
350 extern int dwarf_lineaddr (Dwarf_Line *line, Dwarf_Addr *addrp);
351
352 /* Return line number. */
353 extern int dwarf_lineno (Dwarf_Line *line, int *linep)
354 __nonnull_attribute__ (2);
355
356 /* Return column in line. */
357 extern int dwarf_linecol (Dwarf_Line *line, int *colp)
358 __nonnull_attribute__ (2);
359
360 /* Return true if record is for beginning of a statement. */
361 extern int dwarf_linebeginstatement (Dwarf_Line *line, bool *flagp)
362 __nonnull_attribute__ (2);
363
364 /* Return true if record is for end of sequence. */
365 extern int dwarf_lineendsequence (Dwarf_Line *line, bool *flagp)
366 __nonnull_attribute__ (2);
367
368 /* Return true if record is for beginning of a basic block. */
369 extern int dwarf_lineblock (Dwarf_Line *line, bool *flagp)
370 __nonnull_attribute__ (2);
371
372 /* Return true if record is for end of prologue. */
373 extern int dwarf_lineprologueend (Dwarf_Line *line, bool *flagp)
374 __nonnull_attribute__ (2);
375
376 /* Return true if record is for beginning of epilogue. */
377 extern int dwarf_lineepiloguebegin (Dwarf_Line *line, bool *flagp)
378 __nonnull_attribute__ (2);
379
380
381 /* Find line information for address. */
382 extern const char *dwarf_linesrc (Dwarf_Line *line,
383 Dwarf_Word *mtime, Dwarf_Word *length);
384
385 /* Return file information. */
386 extern const char *dwarf_filesrc (Dwarf_Files *file, size_t idx,
387 Dwarf_Word *mtime, Dwarf_Word *length);
388
389
390 /* Return location expression list. */
391 extern int dwarf_getloclist (Dwarf_Attribute *attr, Dwarf_Loc **llbuf,
392 size_t *listlen) __nonnull_attribute__ (2, 3);
393
394
395
396 /* Return list address ranges. */
397 extern int dwarf_getaranges (Dwarf *dbg, Dwarf_Aranges **aranges,
398 size_t *naranges)
399 __nonnull_attribute__ (2);
400
401 /* Return one of the address range entries. */
402 extern Dwarf_Arange *dwarf_onearange (Dwarf_Aranges *aranges, size_t idx);
403
404 /* Return information in address range record. */
405 extern int dwarf_getarangeinfo (Dwarf_Arange *arange, Dwarf_Addr *addrp,
406 Dwarf_Word *lengthp, Dwarf_Off *offsetp);
407
408 /* Get address range which includes given address. */
409 extern Dwarf_Arange *dwarf_getarange_addr (Dwarf_Aranges *aranges,
410 Dwarf_Addr addr);
411
412
413 /* Call callback function for each of the macro information entry for
414 the CU. */
415 extern ptrdiff_t dwarf_getmacros (Dwarf_Die *cudie,
416 int (*callback) (Dwarf_Macro *, void *),
417 void *arg, ptrdiff_t offset)
418 __nonnull_attribute__ (2);
419
420
421 /* Return error code of last failing function call. This value is kept
422 separately for each thread. */
423 extern int dwarf_errno (void);
424
425 /* Return error string for ERROR. If ERROR is zero, return error string
426 for most recent error or NULL is none occurred. If ERROR is -1 the
427 behaviour is similar to the last case except that not NULL but a legal
428 string is returned. */
429 extern const char *dwarf_errmsg (int err);
430
431
432 /* Register new Out-Of-Memory handler. The old handler is returned. */
433 extern Dwarf_OOM dwarf_new_oom_handler (Dwarf *dbg, Dwarf_OOM handler);
434
435
436 /* Inline optimizations. */
437 #ifdef __OPTIMIZE__
438 /* Return attribute code of given attribute. */
439 extern inline unsigned int
dwarf_whatattr(Dwarf_Attribute * attr)440 dwarf_whatattr (Dwarf_Attribute *attr)
441 {
442 return attr == NULL ? 0 : attr->code;
443 }
444
445 /* Return attribute code of given attribute. */
446 extern inline unsigned int
dwarf_whatform(Dwarf_Attribute * attr)447 dwarf_whatform (Dwarf_Attribute *attr)
448 {
449 return attr == NULL ? 0 : attr->form;
450 }
451 #endif /* Optimize. */
452
453 #endif /* libdw.h */
454