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
  23 from .ranges import RangeLists
  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 # Ignored for now
 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 section of
 347             the DWARF data, or None if this section doesn't exist.
 348         """
 349         if self.debug_loclists_sec:
 350             assert(self.debug_loc_sec is None) # Are there ever files with both kinds of location sections?
 351             return LocationLists(self.debug_loclists_sec.stream, self.structs, 5, self)
 352         elif self.debug_loc_sec:
 353             return LocationLists(self.debug_loc_sec.stream, self.structs)
 354         else:
 355             return None
 356
 357     def range_lists(self):
 358         """ Get a RangeLists object representing the .debug_ranges section of
 359             the DWARF data, or None if this section doesn't exist.
 360         """
 361         if self.debug_ranges_sec:
 362             return RangeLists(self.debug_ranges_sec.stream, self.structs)
 363         else:
 364             return None
 365
 366     #------ PRIVATE ------#
 367
 368     def _parse_CUs_iter(self, offset=0):
 369         """ Iterate CU objects in order of appearance in the debug_info section.
 370
 371             offset:
 372                 The offset of the first CU to yield.  Additional iterations
 373                 will return the sequential unit objects.
 374
 375             See .iter_CUs(), .get_CU_containing(), and .get_CU_at().
 376         """
 377         if self.debug_info_sec is None:
 378             return
 379
 380         while offset < self.debug_info_sec.size:
 381             cu = self._cached_CU_at_offset(offset)
 382             # Compute the offset of the next CU in the section. The unit_length
 383             # field of the CU header contains its size not including the length
 384             # field itself.
 385             offset = (  offset +
 386                         cu['unit_length'] +
 387                         cu.structs.initial_length_field_size())
 388             yield cu
 389
 390     def _cached_CU_at_offset(self, offset):
 391         """ Return the CU with unit header at the given offset into the
 392             debug_info section from the cache.  If not present, the unit is
 393             header is parsed and the object is installed in the cache.
 394
 395             offset:
 396                 The offset of the unit header in the .debug_info section
 397                 to of the unit to fetch from the cache.
 398
 399             See get_CU_at().
 400         """
 401         # Find the insert point for the requested offset.  With bisect_right,
 402         # if this entry is present in the cache it will be the prior entry.
 403         i = bisect_right(self._cu_offsets_map, offset)
 404         if i >= 1 and offset == self._cu_offsets_map[i - 1]:
 405             return self._cu_cache[i - 1]
 406
 407         # Parse the CU and insert the offset and object into the cache.
 408         # The ._cu_offsets_map[] contains just the numeric offsets for the
 409         # bisect_right search while the parallel indexed ._cu_cache[] holds
 410         # the object references.
 411         cu = self._parse_CU_at_offset(offset)
 412         self._cu_offsets_map.insert(i, offset)
 413         self._cu_cache.insert(i, cu)
 414         return cu
 415
 416     def _parse_CU_at_offset(self, offset):
 417         """ Parse and return a CU at the given offset in the debug_info stream.
 418         """
 419         # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
 420         # states that the first 32-bit word of the CU header determines
 421         # whether the CU is represented with 32-bit or 64-bit DWARF format.
 422         #
 423         # So we peek at the first word in the CU header to determine its
 424         # dwarf format. Based on it, we then create a new DWARFStructs
 425         # instance suitable for this CU and use it to parse the rest.
 426         #
 427         initial_length = struct_parse(
 428             self.structs.Dwarf_uint32(''), self.debug_info_sec.stream, offset)
 429         dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 430
 431
 432         # Temporary structs for parsing the header
 433         # The structs for the rest of the CU depend on the header data.
 434         #
 435         cu_structs = DWARFStructs(
 436             little_endian=self.config.little_endian,
 437             dwarf_format=dwarf_format,
 438             address_size=4,
 439             dwarf_version=2)
 440
 441         cu_header = struct_parse(
 442             cu_structs.Dwarf_CU_header, self.debug_info_sec.stream, offset)
 443
 444         # structs for the rest of the CU, taking into account bitness and DWARF version
 445         cu_structs = DWARFStructs(
 446             little_endian=self.config.little_endian,
 447             dwarf_format=dwarf_format,
 448             address_size=cu_header['address_size'],
 449             dwarf_version=cu_header['version'])
 450
 451         cu_die_offset = self.debug_info_sec.stream.tell()
 452         dwarf_assert(
 453             self._is_supported_version(cu_header['version']),
 454             "Expected supported DWARF version. Got '%s'" % cu_header['version'])
 455         return CompileUnit(
 456                 header=cu_header,
 457                 dwarfinfo=self,
 458                 structs=cu_structs,
 459                 cu_offset=offset,
 460                 cu_die_offset=cu_die_offset)
 461
 462     def _is_supported_version(self, version):
 463         """ DWARF version supported by this parser
 464         """
 465         return 2 <= version <= 5
 466
 467     def _parse_line_program_at_offset(self, debug_line_offset, structs):
 468         """ Given an offset to the .debug_line section, parse the line program
 469             starting at this offset in the section and return it.
 470             structs is the DWARFStructs object used to do this parsing.
 471         """
 472         lineprog_header = struct_parse(
 473             structs.Dwarf_lineprog_header,
 474             self.debug_line_sec.stream,
 475             debug_line_offset)
 476
 477         # DWARF5: resolve names
 478         def resolve_strings(self, lineprog_header, format_field, data_field):
 479             if lineprog_header.get(format_field, False):
 480                 data = lineprog_header[data_field]
 481                 for field in lineprog_header[format_field]:
 482                     def replace_value(data, content_type, replacer):
 483                         for entry in data:
 484                             entry[content_type] = replacer(entry[content_type])
 485
 486                     if field.form == 'DW_FORM_line_strp':
 487                         replace_value(data, field.content_type, self.get_string_from_linetable)
 488                     elif field.form == 'DW_FORM_strp':
 489                         replace_value(data, field.content_type, self.get_string_from_table)
 490                     elif field.form in ('DW_FORM_strp_sup', 'DW_FORM_strx', 'DW_FORM_strx1', 'DW_FORM_strx2', 'DW_FORM_strx3', 'DW_FORM_strx4'):
 491                         raise NotImplementedError()
 492
 493         resolve_strings(self, lineprog_header, 'directory_entry_format', 'directories')
 494         resolve_strings(self, lineprog_header, 'file_name_entry_format', 'file_names')
 495
 496         # DWARF5: provide compatible file/directory name arrays for legacy lineprogram consumers
 497         if lineprog_header.get('directories', False):
 498             lineprog_header.include_directory = tuple(d.DW_LNCT_path for d in lineprog_header.directories)
 499         if lineprog_header.get('file_names', False):
 500             lineprog_header.file_entry = tuple(
 501                 Container(**{
 502                     'name':e.get('DW_LNCT_path'),
 503                     'dir_index': e.get('DW_LNCT_directory_index'),
 504                     'mtime': e.get('DW_LNCT_timestamp'),
 505                     'length': e.get('DW_LNCT_size')})
 506                 for e in lineprog_header.file_names)
 507
 508         # Calculate the offset to the next line program (see DWARF 6.2.4)
 509         end_offset = (  debug_line_offset + lineprog_header['unit_length'] +
 510                         structs.initial_length_field_size())
 511
 512         return LineProgram(
 513             header=lineprog_header,
 514             stream=self.debug_line_sec.stream,
 515             structs=structs,
 516             program_start_offset=self.debug_line_sec.stream.tell(),
 517             program_end_offset=end_offset)
 518