1 /* Interfaces for libdw. 2 Copyright (C) 2002, 2004 Red Hat, Inc. 3 Contributed by Ulrich Drepper <drepper (at) 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 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 447 dwarf_whatform (Dwarf_Attribute *attr) 448 { 449 return attr == NULL ? 0 : attr->form; 450 } 451 #endif /* Optimize. */ 452 453 #endif /* libdw.h */ 454
