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         """ config:
  78                 A DwarfConfig object
  79
  80             debug_*_sec:
  81                 DebugSectionDescriptor for a section. Pass None for sections
  82                 that don't exist. These arguments are best given with
  83                 keyword syntax.
  84         """
  85         self.config = config
  86         self.debug_info_sec = debug_info_sec
  87         self.debug_aranges_sec = debug_aranges_sec
  88         self.debug_abbrev_sec = debug_abbrev_sec
  89         self.debug_frame_sec = debug_frame_sec
  90         self.eh_frame_sec = eh_frame_sec
  91         self.debug_str_sec = debug_str_sec
  92         self.debug_loc_sec = debug_loc_sec
  93         self.debug_ranges_sec = debug_ranges_sec
  94         self.debug_line_sec = debug_line_sec
  95         self.debug_pubtypes_sec = debug_pubtypes_sec
  96         self.debug_pubnames_sec = debug_pubnames_sec
  97
  98         # This is the DWARFStructs the context uses, so it doesn't depend on
  99         # DWARF format and address_size (these are determined per CU) - set them
 100         # to default values.
 101         self.structs = DWARFStructs(
 102             little_endian=self.config.little_endian,
 103             dwarf_format=32,
 104             address_size=self.config.default_address_size)
 105
 106         # Cache for abbrev tables: a dict keyed by offset
 107         self._abbrevtable_cache = {}
 108
 109         # Cache of compile units and map of their offsets for bisect lookup.
 110         # Access with .iter_CUs(), .get_CU_containing(), and/or .get_CU_at().
 111         self._cu_cache = []
 112         self._cu_offsets_map = []
 113
 114     @property
 115     def has_debug_info(self):
 116         """ Return whether this contains debug information.
 117
 118         It can be not the case when the ELF only contains .eh_frame, which is
 119         encoded DWARF but not actually for debugging.
 120         """
 121         return bool(self.debug_info_sec)
 122
 123     def get_DIE_from_lut_entry(self, lut_entry):
 124         """ Get the DIE from the pubnames or putbtypes lookup table entry.
 125
 126             lut_entry:
 127                 A NameLUTEntry object from a NameLUT instance (see
 128                 .get_pubmames and .get_pubtypes methods).
 129         """
 130         cu = self.get_CU_at(lut_entry.cu_ofs)
 131         return self.get_DIE_from_refaddr(lut_entry.die_ofs, cu)
 132
 133     def get_DIE_from_refaddr(self, refaddr, cu=None):
 134         """ Given a .debug_info section offset of a DIE, return the DIE.
 135
 136             refaddr:
 137                 The refaddr may come from a DW_FORM_ref_addr attribute.
 138
 139             cu:
 140                 The compile unit object, if known.  If None a search
 141                 from the closest offset less than refaddr will be performed.
 142         """
 143         if cu is None:
 144             cu = self.get_CU_containing(refaddr)
 145         return cu.get_DIE_from_refaddr(refaddr)
 146
 147     def get_CU_containing(self, refaddr):
 148         """ Find the CU that includes the given reference address in the
 149             .debug_info section.
 150
 151             refaddr:
 152                 Either a refaddr of a DIE (possibly from a DW_FORM_ref_addr
 153                 attribute) or the section offset of a CU (possibly from an
 154                 aranges table).
 155
 156            This function will parse and cache CUs until the search criteria
 157            is met, starting from the closest known offset lessthan or equal
 158            to the given address.
 159         """
 160         dwarf_assert(
 161             self.has_debug_info,
 162             'CU lookup but no debug info section')
 163         dwarf_assert(
 164             0 <= refaddr < self.debug_info_sec.size,
 165             "refaddr %s beyond .debug_info size" % refaddr)
 166
 167         # The CU containing the DIE we desire will be to the right of the
 168         # DIE insert point.  If we have a CU address, then it will be a
 169         # match but the right insert minus one will still be the item.
 170         # The first CU starts at offset 0, so start there if cache is empty.
 171         i = bisect_right(self._cu_offsets_map, refaddr)
 172         start = self._cu_offsets_map[i - 1] if i > 0 else 0
 173
 174         # parse CUs until we find one containing the desired address
 175         for cu in self._parse_CUs_iter(start):
 176             if cu.cu_offset <= refaddr < cu.cu_offset + cu.size:
 177                 return cu
 178
 179         raise ValueError("CU for reference address %s not found" % refaddr)
 180
 181     def get_CU_at(self, offset):
 182         """ Given a CU header offset, return the parsed CU.
 183
 184             offset:
 185                 The offset may be from an accelerated access table such as
 186                 the public names, public types, address range table, or
 187                 prior use.
 188
 189             This function will directly parse the CU doing no validation of
 190             the offset beyond checking the size of the .debug_info section.
 191         """
 192         dwarf_assert(
 193             self.has_debug_info,
 194             'CU lookup but no debug info section')
 195         dwarf_assert(
 196             0 <= offset < self.debug_info_sec.size,
 197             "offset %s beyond .debug_info size" % offset)
 198
 199         return self._cached_CU_at_offset(offset)
 200
 201     def iter_CUs(self):
 202         """ Yield all the compile units (CompileUnit objects) in the debug info
 203         """
 204         return self._parse_CUs_iter()
 205
 206     def get_abbrev_table(self, offset):
 207         """ Get an AbbrevTable from the given offset in the debug_abbrev
 208             section.
 209
 210             The only verification done on the offset is that it's within the
 211             bounds of the section (if not, an exception is raised).
 212             It is the caller's responsibility to make sure the offset actually
 213             points to a valid abbreviation table.
 214
 215             AbbrevTable objects are cached internally (two calls for the same
 216             offset will return the same object).
 217         """
 218         dwarf_assert(
 219             offset < self.debug_abbrev_sec.size,
 220             "Offset '0x%x' to abbrev table out of section bounds" % offset)
 221         if offset not in self._abbrevtable_cache:
 222             self._abbrevtable_cache[offset] = AbbrevTable(
 223                 structs=self.structs,
 224                 stream=self.debug_abbrev_sec.stream,
 225                 offset=offset)
 226         return self._abbrevtable_cache[offset]
 227
 228     def get_string_from_table(self, offset):
 229         """ Obtain a string from the string table section, given an offset
 230             relative to the section.
 231         """
 232         return parse_cstring_from_stream(self.debug_str_sec.stream, offset)
 233
 234     def line_program_for_CU(self, CU):
 235         """ Given a CU object, fetch the line program it points to from the
 236             .debug_line section.
 237             If the CU doesn't point to a line program, return None.
 238         """
 239         # The line program is pointed to by the DW_AT_stmt_list attribute of
 240         # the top DIE of a CU.
 241         top_DIE = CU.get_top_DIE()
 242         if 'DW_AT_stmt_list' in top_DIE.attributes:
 243             return self._parse_line_program_at_offset(
 244                     top_DIE.attributes['DW_AT_stmt_list'].value, CU.structs)
 245         else:
 246             return None
 247
 248     def has_CFI(self):
 249         """ Does this dwarf info have a dwarf_frame CFI section?
 250         """
 251         return self.debug_frame_sec is not None
 252
 253     def CFI_entries(self):
 254         """ Get a list of dwarf_frame CFI entries from the .debug_frame section.
 255         """
 256         cfi = CallFrameInfo(
 257             stream=self.debug_frame_sec.stream,
 258             size=self.debug_frame_sec.size,
 259             address=self.debug_frame_sec.address,
 260             base_structs=self.structs)
 261         return cfi.get_entries()
 262
 263     def has_EH_CFI(self):
 264         """ Does this dwarf info have a eh_frame CFI section?
 265         """
 266         return self.eh_frame_sec is not None
 267
 268     def EH_CFI_entries(self):
 269         """ Get a list of eh_frame CFI entries from the .eh_frame section.
 270         """
 271         cfi = CallFrameInfo(
 272             stream=self.eh_frame_sec.stream,
 273             size=self.eh_frame_sec.size,
 274             address=self.eh_frame_sec.address,
 275             base_structs=self.structs,
 276             for_eh_frame=True)
 277         return cfi.get_entries()
 278
 279     def get_pubtypes(self):
 280         """
 281         Returns a NameLUT object that contains information read from the
 282         .debug_pubtypes section in the ELF file.
 283
 284         NameLUT is essentially a dictionary containing the CU/DIE offsets of
 285         each symbol. See the NameLUT doc string for more details.
 286         """
 287
 288         if self.debug_pubtypes_sec:
 289             return NameLUT(self.debug_pubtypes_sec.stream,
 290                     self.debug_pubtypes_sec.size,
 291                     self.structs)
 292         else:
 293             return None
 294
 295     def get_pubnames(self):
 296         """
 297         Returns a NameLUT object that contains information read from the
 298         .debug_pubnames 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_pubnames_sec:
 305             return NameLUT(self.debug_pubnames_sec.stream,
 306                     self.debug_pubnames_sec.size,
 307                     self.structs)
 308         else:
 309             return None
 310
 311     def get_aranges(self):
 312         """ Get an ARanges object representing the .debug_aranges section of
 313             the DWARF data, or None if the section doesn't exist
 314         """
 315         if self.debug_aranges_sec:
 316             return ARanges(self.debug_aranges_sec.stream,
 317                 self.debug_aranges_sec.size,
 318                 self.structs)
 319         else:
 320             return None
 321
 322     def location_lists(self):
 323         """ Get a LocationLists object representing the .debug_loc section of
 324             the DWARF data, or None if this section doesn't exist.
 325         """
 326         if self.debug_loc_sec:
 327             return LocationLists(self.debug_loc_sec.stream, self.structs)
 328         else:
 329             return None
 330
 331     def range_lists(self):
 332         """ Get a RangeLists object representing the .debug_ranges section of
 333             the DWARF data, or None if this section doesn't exist.
 334         """
 335         if self.debug_ranges_sec:
 336             return RangeLists(self.debug_ranges_sec.stream, self.structs)
 337         else:
 338             return None
 339
 340     #------ PRIVATE ------#
 341
 342     def _parse_CUs_iter(self, offset=0):
 343         """ Iterate CU objects in order of appearance in the debug_info section.
 344
 345             offset:
 346                 The offset of the first CU to yield.  Additional iterations
 347                 will return the sequential unit objects.
 348
 349             See .iter_CUs(), .get_CU_containing(), and .get_CU_at().
 350         """
 351         if self.debug_info_sec is None:
 352             return
 353
 354         while offset < self.debug_info_sec.size:
 355             cu = self._cached_CU_at_offset(offset)
 356             # Compute the offset of the next CU in the section. The unit_length
 357             # field of the CU header contains its size not including the length
 358             # field itself.
 359             offset = (  offset +
 360                         cu['unit_length'] +
 361                         cu.structs.initial_length_field_size())
 362             yield cu
 363
 364     def _cached_CU_at_offset(self, offset):
 365         """ Return the CU with unit header at the given offset into the
 366             debug_info section from the cache.  If not present, the unit is
 367             header is parsed and the object is installed in the cache.
 368
 369             offset:
 370                 The offset of the unit header in the .debug_info section
 371                 to of the unit to fetch from the cache.
 372
 373             See get_CU_at().
 374         """
 375         # Find the insert point for the requested offset.  With bisect_right,
 376         # if this entry is present in the cache it will be the prior entry.
 377         i = bisect_right(self._cu_offsets_map, offset)
 378         if i >= 1 and offset == self._cu_offsets_map[i - 1]:
 379             return self._cu_cache[i - 1]
 380
 381         # Parse the CU and insert the offset and object into the cache.
 382         # The ._cu_offsets_map[] contains just the numeric offsets for the
 383         # bisect_right search while the parallel indexed ._cu_cache[] holds
 384         # the object references.
 385         cu = self._parse_CU_at_offset(offset)
 386         self._cu_offsets_map.insert(i, offset)
 387         self._cu_cache.insert(i, cu)
 388         return cu
 389
 390     def _parse_CU_at_offset(self, offset):
 391         """ Parse and return a CU at the given offset in the debug_info stream.
 392         """
 393         # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
 394         # states that the first 32-bit word of the CU header determines
 395         # whether the CU is represented with 32-bit or 64-bit DWARF format.
 396         #
 397         # So we peek at the first word in the CU header to determine its
 398         # dwarf format. Based on it, we then create a new DWARFStructs
 399         # instance suitable for this CU and use it to parse the rest.
 400         #
 401         initial_length = struct_parse(
 402             self.structs.Dwarf_uint32(''), self.debug_info_sec.stream, offset)
 403         dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 404
 405
 406         # Temporary structs for parsing the header
 407         # The structs for the rest of the CU depend on the header data.
 408         #
 409         cu_structs = DWARFStructs(
 410             little_endian=self.config.little_endian,
 411             dwarf_format=dwarf_format,
 412             address_size=4,
 413             dwarf_version=2)
 414
 415         cu_header = struct_parse(
 416             cu_structs.Dwarf_CU_header, self.debug_info_sec.stream, offset)
 417
 418         # structs for the rest of the CU, taking into account bitness and DWARF version
 419         cu_structs = DWARFStructs(
 420             little_endian=self.config.little_endian,
 421             dwarf_format=dwarf_format,
 422             address_size=cu_header['address_size'],
 423             dwarf_version=cu_header['version'])
 424
 425         cu_die_offset = self.debug_info_sec.stream.tell()
 426         dwarf_assert(
 427             self._is_supported_version(cu_header['version']),
 428             "Expected supported DWARF version. Got '%s'" % cu_header['version'])
 429         return CompileUnit(
 430                 header=cu_header,
 431                 dwarfinfo=self,
 432                 structs=cu_structs,
 433                 cu_offset=offset,
 434                 cu_die_offset=cu_die_offset)
 435
 436     def _is_supported_version(self, version):
 437         """ DWARF version supported by this parser
 438         """
 439         return 2 <= version <= 5
 440
 441     def _parse_line_program_at_offset(self, debug_line_offset, structs):
 442         """ Given an offset to the .debug_line section, parse the line program
 443             starting at this offset in the section and return it.
 444             structs is the DWARFStructs object used to do this parsing.
 445         """
 446         lineprog_header = struct_parse(
 447             structs.Dwarf_lineprog_header,
 448             self.debug_line_sec.stream,
 449             debug_line_offset)
 450
 451         # Calculate the offset to the next line program (see DWARF 6.2.4)
 452         end_offset = (  debug_line_offset + lineprog_header['unit_length'] +
 453                         structs.initial_length_field_size())
 454
 455         return LineProgram(
 456             header=lineprog_header,
 457             stream=self.debug_line_sec.stream,
 458             structs=structs,
 459             program_start_offset=self.debug_line_sec.stream.tell(),
 460             program_end_offset=end_offset)