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