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