elftools/dwarf/dwarfinfo.py

   1 #-------------------------------------------------------------------------------
   2 # elftools: dwarf/dwarfinfo.py
   3 #
   4 # DWARFInfo - Main class for accessing DWARF debug information
   5 #
   6 # Eli Bendersky (eliben@gmail.com)
   7 # This code is in the public domain
   8 #-------------------------------------------------------------------------------
   9 import os
  10 from collections import namedtuple
  11 from bisect import bisect_right
  12
  13 from ..construct.lib.container import Container
  14 from ..common.exceptions import DWARFError
  15 from ..common.utils import (struct_parse, dwarf_assert,
  16                             parse_cstring_from_stream)
  17 from .structs import DWARFStructs
  18 from .compileunit import CompileUnit
  19 from .abbrevtable import AbbrevTable
  20 from .lineprogram import LineProgram
  21 from .callframe import CallFrameInfo
  22 from .locationlists import LocationLists, LocationListsPair
  23 from .ranges import RangeLists, RangeListsPair
  24 from .aranges import ARanges
  25 from .namelut import NameLUT
  26 from .dwarf_util import _get_base_offset
  27
  28
  29 # Describes a debug section
  30 #
  31 # stream: a stream object containing the data of this section
  32 # name: section name in the container file
  33 # global_offset: the global offset of the section in its container file
  34 # size: the size of the section's data, in bytes
  35 # address: the virtual address for the section's data
  36 #
  37 # 'name' and 'global_offset' are for descriptional purposes only and
  38 # aren't strictly required for the DWARF parsing to work. 'address' is required
  39 # to properly decode the special '.eh_frame' format.
  40 #
  41 DebugSectionDescriptor = namedtuple('DebugSectionDescriptor',
  42     'stream name global_offset size address')
  43
  44
  45 # Some configuration parameters for the DWARF reader. This exists to allow
  46 # DWARFInfo to be independent from any specific file format/container.
  47 #
  48 # little_endian:
  49 #   boolean flag specifying whether the data in the file is little endian
  50 #
  51 # machine_arch:
  52 #   Machine architecture as a string. For example 'x86' or 'x64'
  53 #
  54 # default_address_size:
  55 #   The default address size for the container file (sizeof pointer, in bytes)
  56 #
  57 DwarfConfig = namedtuple('DwarfConfig',
  58     'little_endian machine_arch default_address_size')
  59
  60
  61 class DWARFInfo(object):
  62     """ Acts also as a "context" to other major objects, bridging between
  63         various parts of the debug information.
  64     """
  65     def __init__(self,
  66             config,
  67             debug_info_sec,
  68             debug_aranges_sec,
  69             debug_abbrev_sec,
  70             debug_frame_sec,
  71             eh_frame_sec,
  72             debug_str_sec,
  73             debug_loc_sec,
  74             debug_ranges_sec,
  75             debug_line_sec,
  76             debug_pubtypes_sec,
  77             debug_pubnames_sec,
  78             debug_addr_sec,
  79             debug_str_offsets_sec,
  80             debug_line_str_sec,
  81             debug_loclists_sec,
  82             debug_rnglists_sec,
  83             debug_sup_sec,
  84             gnu_debugaltlink_sec
  85             ):
  86         """ config:
  87                 A DwarfConfig object
  88
  89             debug_*_sec:
  90                 DebugSectionDescriptor for a section. Pass None for sections
  91                 that don't exist. These arguments are best given with
  92                 keyword syntax.
  93         """
  94         self.config = config
  95         self.debug_info_sec = debug_info_sec
  96         self.debug_aranges_sec = debug_aranges_sec
  97         self.debug_abbrev_sec = debug_abbrev_sec
  98         self.debug_frame_sec = debug_frame_sec
  99         self.eh_frame_sec = eh_frame_sec
 100         self.debug_str_sec = debug_str_sec
 101         self.debug_loc_sec = debug_loc_sec
 102         self.debug_ranges_sec = debug_ranges_sec
 103         self.debug_line_sec = debug_line_sec
 104         self.debug_addr_sec = debug_addr_sec
 105         self.debug_str_offsets_sec = debug_str_offsets_sec
 106         self.debug_line_str_sec = debug_line_str_sec
 107         self.debug_pubtypes_sec = debug_pubtypes_sec
 108         self.debug_pubnames_sec = debug_pubnames_sec
 109         self.debug_loclists_sec = debug_loclists_sec
 110         self.debug_rnglists_sec = debug_rnglists_sec
 111         self.debug_sup_sec = debug_sup_sec
 112         self.gnu_debugaltlink_sec = gnu_debugaltlink_sec
 113
 114         # Sets the supplementary_dwarfinfo to None. Client code can set this
 115         # to something else, typically a DWARFInfo file read from an ELFFile
 116         # which path is stored in the debug_sup_sec or gnu_debugaltlink_sec.
 117         self.supplementary_dwarfinfo = None
 118
 119         # This is the DWARFStructs the context uses, so it doesn't depend on
 120         # DWARF format and address_size (these are determined per CU) - set them
 121         # to default values.
 122         self.structs = DWARFStructs(
 123             little_endian=self.config.little_endian,
 124             dwarf_format=32,
 125             address_size=self.config.default_address_size)
 126
 127         # Cache for abbrev tables: a dict keyed by offset
 128         self._abbrevtable_cache = {}
 129         # Cache for program lines tables: a dict keyed by offset
 130         self._linetable_cache = {}
 131
 132         # Cache of compile units and map of their offsets for bisect lookup.
 133         # Access with .iter_CUs(), .get_CU_containing(), and/or .get_CU_at().
 134         self._cu_cache = []
 135         self._cu_offsets_map = []
 136
 137     @property
 138     def has_debug_info(self):
 139         """ Return whether this contains debug information.
 140
 141         It can be not the case when the ELF only contains .eh_frame, which is
 142         encoded DWARF but not actually for debugging.
 143         """
 144         return bool(self.debug_info_sec)
 145
 146     def get_DIE_from_lut_entry(self, lut_entry):
 147         """ Get the DIE from the pubnames or putbtypes lookup table entry.
 148
 149             lut_entry:
 150                 A NameLUTEntry object from a NameLUT instance (see
 151                 .get_pubmames and .get_pubtypes methods).
 152         """
 153         cu = self.get_CU_at(lut_entry.cu_ofs)
 154         return self.get_DIE_from_refaddr(lut_entry.die_ofs, cu)
 155
 156     def get_DIE_from_refaddr(self, refaddr, cu=None):
 157         """ Given a .debug_info section offset of a DIE, return the DIE.
 158
 159             refaddr:
 160                 The refaddr may come from a DW_FORM_ref_addr attribute.
 161
 162             cu:
 163                 The compile unit object, if known.  If None a search
 164                 from the closest offset less than refaddr will be performed.
 165         """
 166         if cu is None:
 167             cu = self.get_CU_containing(refaddr)
 168         return cu.get_DIE_from_refaddr(refaddr)
 169
 170     def get_CU_containing(self, refaddr):
 171         """ Find the CU that includes the given reference address in the
 172             .debug_info section.
 173
 174             refaddr:
 175                 Either a refaddr of a DIE (possibly from a DW_FORM_ref_addr
 176                 attribute) or the section offset of a CU (possibly from an
 177                 aranges table).
 178
 179            This function will parse and cache CUs until the search criteria
 180            is met, starting from the closest known offset lessthan or equal
 181            to the given address.
 182         """
 183         dwarf_assert(
 184             self.has_debug_info,
 185             'CU lookup but no debug info section')
 186         dwarf_assert(
 187             0 <= refaddr < self.debug_info_sec.size,
 188             "refaddr %s beyond .debug_info size" % refaddr)
 189
 190         # The CU containing the DIE we desire will be to the right of the
 191         # DIE insert point.  If we have a CU address, then it will be a
 192         # match but the right insert minus one will still be the item.
 193         # The first CU starts at offset 0, so start there if cache is empty.
 194         i = bisect_right(self._cu_offsets_map, refaddr)
 195         start = self._cu_offsets_map[i - 1] if i > 0 else 0
 196
 197         # parse CUs until we find one containing the desired address
 198         for cu in self._parse_CUs_iter(start):
 199             if cu.cu_offset <= refaddr < cu.cu_offset + cu.size:
 200                 return cu
 201
 202         raise ValueError("CU for reference address %s not found" % refaddr)
 203
 204     def get_CU_at(self, offset):
 205         """ Given a CU header offset, return the parsed CU.
 206
 207             offset:
 208                 The offset may be from an accelerated access table such as
 209                 the public names, public types, address range table, or
 210                 prior use.
 211
 212             This function will directly parse the CU doing no validation of
 213             the offset beyond checking the size of the .debug_info section.
 214         """
 215         dwarf_assert(
 216             self.has_debug_info,
 217             'CU lookup but no debug info section')
 218         dwarf_assert(
 219             0 <= offset < self.debug_info_sec.size,
 220             "offset %s beyond .debug_info size" % offset)
 221
 222         return self._cached_CU_at_offset(offset)
 223
 224     def iter_CUs(self):
 225         """ Yield all the compile units (CompileUnit objects) in the debug info
 226         """
 227         return self._parse_CUs_iter()
 228
 229     def get_abbrev_table(self, offset):
 230         """ Get an AbbrevTable from the given offset in the debug_abbrev
 231             section.
 232
 233             The only verification done on the offset is that it's within the
 234             bounds of the section (if not, an exception is raised).
 235             It is the caller's responsibility to make sure the offset actually
 236             points to a valid abbreviation table.
 237
 238             AbbrevTable objects are cached internally (two calls for the same
 239             offset will return the same object).
 240         """
 241         dwarf_assert(
 242             offset < self.debug_abbrev_sec.size,
 243             "Offset '0x%x' to abbrev table out of section bounds" % offset)
 244         if offset not in self._abbrevtable_cache:
 245             self._abbrevtable_cache[offset] = AbbrevTable(
 246                 structs=self.structs,
 247                 stream=self.debug_abbrev_sec.stream,
 248                 offset=offset)
 249         return self._abbrevtable_cache[offset]
 250
 251     def get_string_from_table(self, offset):
 252         """ Obtain a string from the string table section, given an offset
 253             relative to the section.
 254         """
 255         return parse_cstring_from_stream(self.debug_str_sec.stream, offset)
 256
 257     def get_string_from_linetable(self, offset):
 258         """ Obtain a string from the string table section, given an offset
 259             relative to the section.
 260         """
 261         return parse_cstring_from_stream(self.debug_line_str_sec.stream, offset)
 262
 263     def line_program_for_CU(self, CU):
 264         """ Given a CU object, fetch the line program it points to from the
 265             .debug_line section.
 266             If the CU doesn't point to a line program, return None.
 267
 268             Note about directory and file names. They are returned as two collections
 269             in the lineprogram object's header - include_directory and file_entry.
 270
 271             In DWARFv5, they have introduced a different, extensible format for those
 272             collections. So in a lineprogram v5+, there are two more collections in
 273             the header - directories and file_names. Those might contain extra DWARFv5
 274             information that is not exposed in include_directory and file_entry.
 275         """
 276         # The line program is pointed to by the DW_AT_stmt_list attribute of
 277         # the top DIE of a CU.
 278         top_DIE = CU.get_top_DIE()
 279         if 'DW_AT_stmt_list' in top_DIE.attributes:
 280             return self._parse_line_program_at_offset(
 281                     top_DIE.attributes['DW_AT_stmt_list'].value, CU.structs)
 282         else:
 283             return None
 284
 285     def has_CFI(self):
 286         """ Does this dwarf info have a dwarf_frame CFI section?
 287         """
 288         return self.debug_frame_sec is not None
 289
 290     def CFI_entries(self):
 291         """ Get a list of dwarf_frame CFI entries from the .debug_frame section.
 292         """
 293         cfi = CallFrameInfo(
 294             stream=self.debug_frame_sec.stream,
 295             size=self.debug_frame_sec.size,
 296             address=self.debug_frame_sec.address,
 297             base_structs=self.structs)
 298         return cfi.get_entries()
 299
 300     def has_EH_CFI(self):
 301         """ Does this dwarf info have a eh_frame CFI section?
 302         """
 303         return self.eh_frame_sec is not None
 304
 305     def EH_CFI_entries(self):
 306         """ Get a list of eh_frame CFI entries from the .eh_frame section.
 307         """
 308         cfi = CallFrameInfo(
 309             stream=self.eh_frame_sec.stream,
 310             size=self.eh_frame_sec.size,
 311             address=self.eh_frame_sec.address,
 312             base_structs=self.structs,
 313             for_eh_frame=True)
 314         return cfi.get_entries()
 315
 316     def get_pubtypes(self):
 317         """
 318         Returns a NameLUT object that contains information read from the
 319         .debug_pubtypes section in the ELF file.
 320
 321         NameLUT is essentially a dictionary containing the CU/DIE offsets of
 322         each symbol. See the NameLUT doc string for more details.
 323         """
 324
 325         if self.debug_pubtypes_sec:
 326             return NameLUT(self.debug_pubtypes_sec.stream,
 327                     self.debug_pubtypes_sec.size,
 328                     self.structs)
 329         else:
 330             return None
 331
 332     def get_pubnames(self):
 333         """
 334         Returns a NameLUT object that contains information read from the
 335         .debug_pubnames section in the ELF file.
 336
 337         NameLUT is essentially a dictionary containing the CU/DIE offsets of
 338         each symbol. See the NameLUT doc string for more details.
 339         """
 340
 341         if self.debug_pubnames_sec:
 342             return NameLUT(self.debug_pubnames_sec.stream,
 343                     self.debug_pubnames_sec.size,
 344                     self.structs)
 345         else:
 346             return None
 347
 348     def get_aranges(self):
 349         """ Get an ARanges object representing the .debug_aranges section of
 350             the DWARF data, or None if the section doesn't exist
 351         """
 352         if self.debug_aranges_sec:
 353             return ARanges(self.debug_aranges_sec.stream,
 354                 self.debug_aranges_sec.size,
 355                 self.structs)
 356         else:
 357             return None
 358
 359     def location_lists(self):
 360         """ Get a LocationLists object representing the .debug_loc/debug_loclists section of
 361             the DWARF data, or None if this section doesn't exist.
 362
 363             If both sections exist, it returns a LocationListsPair.
 364         """
 365         if self.debug_loclists_sec and self.debug_loc_sec is None:
 366             return LocationLists(self.debug_loclists_sec.stream, self.structs, 5, self)
 367         elif self.debug_loc_sec and self.debug_loclists_sec is None:
 368             return LocationLists(self.debug_loc_sec.stream, self.structs, 4, self)
 369         elif self.debug_loc_sec and self.debug_loclists_sec:
 370             return LocationListsPair(self.debug_loc_sec.stream, self.debug_loclists_sec.stream, self.structs, self)
 371         else:
 372             return None
 373
 374     def range_lists(self):
 375         """ Get a RangeLists object representing the .debug_ranges/.debug_rnglists section of
 376             the DWARF data, or None if this section doesn't exist.
 377
 378             If both sections exist, it returns a RangeListsPair.
 379         """
 380         if self.debug_rnglists_sec and self.debug_ranges_sec is None:
 381             return RangeLists(self.debug_rnglists_sec.stream, self.structs, 5, self)
 382         elif self.debug_ranges_sec and self.debug_rnglists_sec is None:
 383             return RangeLists(self.debug_ranges_sec.stream, self.structs, 4, self)
 384         elif self.debug_ranges_sec and self.debug_rnglists_sec:
 385             return RangeListsPair(self.debug_ranges_sec.stream, self.debug_rnglists_sec.stream, self.structs, self)
 386         else:
 387             return None
 388
 389     def get_addr(self, cu, addr_index):
 390         """Provided a CU and an index, retrieves an address from the debug_addr section
 391         """
 392         if not self.debug_addr_sec:
 393             raise DWARFError('The file does not contain a debug_addr section for indirect address access')
 394         # Selectors are not supported, but no assert on that. TODO?
 395         cu_addr_base = _get_base_offset(cu, 'DW_AT_addr_base')
 396         return struct_parse(cu.structs.Dwarf_target_addr(''), self.debug_addr_sec.stream, cu_addr_base + addr_index*cu.header.address_size)
 397
 398     #------ PRIVATE ------#
 399
 400     def _parse_CUs_iter(self, offset=0):
 401         """ Iterate CU objects in order of appearance in the debug_info section.
 402
 403             offset:
 404                 The offset of the first CU to yield.  Additional iterations
 405                 will return the sequential unit objects.
 406
 407             See .iter_CUs(), .get_CU_containing(), and .get_CU_at().
 408         """
 409         if self.debug_info_sec is None:
 410             return
 411
 412         while offset < self.debug_info_sec.size:
 413             cu = self._cached_CU_at_offset(offset)
 414             # Compute the offset of the next CU in the section. The unit_length
 415             # field of the CU header contains its size not including the length
 416             # field itself.
 417             offset = (  offset +
 418                         cu['unit_length'] +
 419                         cu.structs.initial_length_field_size())
 420             yield cu
 421
 422     def _cached_CU_at_offset(self, offset):
 423         """ Return the CU with unit header at the given offset into the
 424             debug_info section from the cache.  If not present, the unit is
 425             header is parsed and the object is installed in the cache.
 426
 427             offset:
 428                 The offset of the unit header in the .debug_info section
 429                 to of the unit to fetch from the cache.
 430
 431             See get_CU_at().
 432         """
 433         # Find the insert point for the requested offset.  With bisect_right,
 434         # if this entry is present in the cache it will be the prior entry.
 435         i = bisect_right(self._cu_offsets_map, offset)
 436         if i >= 1 and offset == self._cu_offsets_map[i - 1]:
 437             return self._cu_cache[i - 1]
 438
 439         # Parse the CU and insert the offset and object into the cache.
 440         # The ._cu_offsets_map[] contains just the numeric offsets for the
 441         # bisect_right search while the parallel indexed ._cu_cache[] holds
 442         # the object references.
 443         cu = self._parse_CU_at_offset(offset)
 444         self._cu_offsets_map.insert(i, offset)
 445         self._cu_cache.insert(i, cu)
 446         return cu
 447
 448     def _parse_CU_at_offset(self, offset):
 449         """ Parse and return a CU at the given offset in the debug_info stream.
 450         """
 451         # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
 452         # states that the first 32-bit word of the CU header determines
 453         # whether the CU is represented with 32-bit or 64-bit DWARF format.
 454         #
 455         # So we peek at the first word in the CU header to determine its
 456         # dwarf format. Based on it, we then create a new DWARFStructs
 457         # instance suitable for this CU and use it to parse the rest.
 458         #
 459         initial_length = struct_parse(
 460             self.structs.Dwarf_uint32(''), self.debug_info_sec.stream, offset)
 461         dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 462
 463
 464         # Temporary structs for parsing the header
 465         # The structs for the rest of the CU depend on the header data.
 466         #
 467         cu_structs = DWARFStructs(
 468             little_endian=self.config.little_endian,
 469             dwarf_format=dwarf_format,
 470             address_size=4,
 471             dwarf_version=2)
 472
 473         cu_header = struct_parse(
 474             cu_structs.Dwarf_CU_header, self.debug_info_sec.stream, offset)
 475
 476         # structs for the rest of the CU, taking into account bitness and DWARF version
 477         cu_structs = DWARFStructs(
 478             little_endian=self.config.little_endian,
 479             dwarf_format=dwarf_format,
 480             address_size=cu_header['address_size'],
 481             dwarf_version=cu_header['version'])
 482
 483         cu_die_offset = self.debug_info_sec.stream.tell()
 484         dwarf_assert(
 485             self._is_supported_version(cu_header['version']),
 486             "Expected supported DWARF version. Got '%s'" % cu_header['version'])
 487         return CompileUnit(
 488                 header=cu_header,
 489                 dwarfinfo=self,
 490                 structs=cu_structs,
 491                 cu_offset=offset,
 492                 cu_die_offset=cu_die_offset)
 493
 494     def _is_supported_version(self, version):
 495         """ DWARF version supported by this parser
 496         """
 497         return 2 <= version <= 5
 498
 499     def _parse_line_program_at_offset(self, offset, structs):
 500         """ Given an offset to the .debug_line section, parse the line program
 501             starting at this offset in the section and return it.
 502             structs is the DWARFStructs object used to do this parsing.
 503         """
 504
 505         if offset in self._linetable_cache:
 506             return self._linetable_cache[offset]
 507
 508         lineprog_header = struct_parse(
 509             structs.Dwarf_lineprog_header,
 510             self.debug_line_sec.stream,
 511             offset)
 512
 513         # DWARF5: resolve names
 514         def resolve_strings(self, lineprog_header, format_field, data_field):
 515             if lineprog_header.get(format_field, False):
 516                 data = lineprog_header[data_field]
 517                 for field in lineprog_header[format_field]:
 518                     def replace_value(data, content_type, replacer):
 519                         for entry in data:
 520                             entry[content_type] = replacer(entry[content_type])
 521
 522                     if field.form == 'DW_FORM_line_strp':
 523                         replace_value(data, field.content_type, self.get_string_from_linetable)
 524                     elif field.form == 'DW_FORM_strp':
 525                         replace_value(data, field.content_type, self.get_string_from_table)
 526                     elif field.form in ('DW_FORM_strp_sup', 'DW_FORM_GNU_strp_alt'):
 527                         if self.supplementary_dwarfinfo:
 528                             replace_value(data, field.content_type, self.supplementary_dwarfinfo.get_string_fromtable)
 529                         else:
 530                             replace_value(data, field.content_type, lambda x: str(x))
 531                     elif field.form in ('DW_FORM_strp_sup', 'DW_FORM_strx', 'DW_FORM_strx1', 'DW_FORM_strx2', 'DW_FORM_strx3', 'DW_FORM_strx4'):
 532                         raise NotImplementedError()
 533
 534         resolve_strings(self, lineprog_header, 'directory_entry_format', 'directories')
 535         resolve_strings(self, lineprog_header, 'file_name_entry_format', 'file_names')
 536
 537         # DWARF5: provide compatible file/directory name arrays for legacy lineprogram consumers
 538         if lineprog_header.get('directories', False):
 539             lineprog_header.include_directory = tuple(d.DW_LNCT_path for d in lineprog_header.directories)
 540         if lineprog_header.get('file_names', False):
 541             lineprog_header.file_entry = tuple(
 542                 Container(**{
 543                     'name':e.get('DW_LNCT_path'),
 544                     'dir_index': e.get('DW_LNCT_directory_index'),
 545                     'mtime': e.get('DW_LNCT_timestamp'),
 546                     'length': e.get('DW_LNCT_size')})
 547                 for e in lineprog_header.file_names)
 548
 549         # Calculate the offset to the next line program (see DWARF 6.2.4)
 550         end_offset = (  offset + lineprog_header['unit_length'] +
 551                         structs.initial_length_field_size())
 552
 553         lineprogram = LineProgram(
 554             header=lineprog_header,
 555             stream=self.debug_line_sec.stream,
 556             structs=structs,
 557             program_start_offset=self.debug_line_sec.stream.tell(),
 558             program_end_offset=end_offset)
 559
 560         self._linetable_cache[offset] = lineprogram
 561         return lineprogram
 562
 563     def parse_debugsupinfo(self):
 564         """
 565         Extract a filename from either .debug_sup or .gnu_debualtlink sections.
 566         """
 567         if self.debug_sup_sec is not None:
 568             self.debug_sup_sec.stream.seek(0)
 569             suplink = self.structs.Dwarf_debugsup.parse_stream(self.debug_sup_sec.stream)
 570             if suplink.is_supplementary == 0:
 571                 return suplink.sup_filename
 572         if self.gnu_debugaltlink_sec is not None:
 573             self.gnu_debugaltlink_sec.stream.seek(0)
 574             suplink = self.structs.Dwarf_debugaltlink.parse_stream(self.gnu_debugaltlink_sec.stream)
 575             return suplink.sup_filename
 576         return None
 577